LYPay Instant Payment System – Technical Overview

1. System Architecture & Prerequisites

LYPay is an instant payment system (IPS) designed for banks and financial institutions (FIs) under the Central Bank of Libya. It ensures real-time funds transfer and seamless interoperability between financial entities.

Key Requirements:

Both the sender and the receiver must be registered in the National Alias Directory (NAD).
Transactions require authentication via Bearer tokens.
Some endpoints (e.g., webhook processing) use HMAC authentication for security.
The system operates asynchronously, meaning transaction execution is not always immediate.

2. Payment Flow – Funds Transfer Execution

LYPay's transaction process follows a structured two-step approach:

Step 1: Initiate the Transaction

API:
```
POST /api/v1/payments/funds-transfers
```
The initiating entity (bank/FI) sends a request containing:
- Sender (Debtor) Account Details
- Receiver (Creditor) Account Details
- Amount and Currency
- Transaction Type (P2P, P2M, M2M)
- Optional Metadata (e.g., bill number, reference label)

Response:

The API responds with:
- Transaction UUID
- Payment Reference & Timestamp
- Fees (if applicable)
- Initial Status: Acknowledged (Transaction not yet executed)

At this stage, the transaction is only recorded but not processed. The FI must explicitly confirm the transaction.

Step 2: Confirm the Transaction

API:

POST /api/v1/payments/funds-transfers/{UUID}/confirm

This step confirms the transaction using:
- Transaction UUID
- Payment Reference
- Transaction Timestamp

Response Behavior:

✅ Immediate Response Scenarios:

If the transaction fails due to compliance checks (e.g., daily limit exceeded), it will immediately return a decline response.
If the transaction executes in under 5 seconds, the API will return the final status (Confirmed or Declined).

✅ Asynchronous Execution Scenario:

If the transaction requires further processing, the system responds with:
- Status: Processing
A webhook notification (transaction-update) will be sent once execution is complete.

3. Webhook Notifications for Status Updates

LYPay operates asynchronously, meaning banks/FIs do not always receive an instant status update. Note: When we say webhooks, we mean endpoints that should be developed and provided by the banks or financial institutions

API:
```
POST /webhooks
```
The system automatically sends a webhook notification when a transaction status changes.
Webhook types:
- transaction_status_update (Indicates whether a transaction was confirmed or declined)
- transaction_credit_notice (Indicates a credit event in the recipient’s account)

This eliminates the need for continuous polling.

4. Additional APIs for Transaction Management

Beyond the initiate-confirm workflow, LYPay provides several key APIs for querying, refunding, and managing transactions:

A. Querying Transactions

Retrieve Funds Transfer Status
- API:
  GET /api/v1/payments/funds-transfers/{UUID}
- Allows banks/FIs to query a transaction’s current status.
List Transactions by Status
- APIs:
  GET /api/v1/payments/debited-funds-transfers GET /api/v1/payments/credited-funds-transfers
- Fetches a paginated list of transactions based on:
  - Transaction Type (P2P, P2M)
  - Transaction Status (Completed, Declined)
  - Transaction Date
Find Transactions Using Internal Merchant Reference
- API:
  GET /api/v1/payments/credited-funds-transfers/by-internal-merchant-reference
- Enables merchants to retrieve transaction details based on their own internal identifiers.

B. Refund and Reversal Handling

LYPay supports refunds for transactions, allowing merchants and banks to reverse payments when necessary.

Initiate a Refund
- API:
  POST /api/v1/payments/funds-transfers/{UUID}/refund
- Allows the bank to refund a completed transaction.
- The refunded amount must not exceed the original transaction amount.

C. Authentication & Token Management

To ensure secure API access, LYPay provides token-based authentication:

Create a New Token
- API:
  POST /api/v1/auth/token
- Generates a new API token for the authenticated entity.
Reset Password
- API:
  POST /api/v1/auth/password/reset
- Allows users to update their credentials securely.
Revoke an Existing Token
- API:
  POST /auth/revoke
- Immediately invalidates a previously issued API token.

5. Compliance & Security Features

LYPay ensures that all transactions adhere to regulatory guidelines and financial security measures:

✅ National Alias Directory (NAD) Enforcement

Both sender & receiver must be registered in NAD before initiating transactions.

✅ Transaction Limits & Compliance Checks

The system automatically rejects transactions that exceed:
- Daily Transfer Limits
- AML Compliance Thresholds
- Suspicious Activity Detected

✅ Asynchronous Processing & Secure Webhooks

Transactions are processed in real-time, but in cases where verification is needed, the system uses webhooks for status updates.

✅ Bearer Token & HMAC Authentication

Sensitive APIs require Bearer authentication, while webhook events use HMAC signatures to prevent tampering.

Conclusion

LYPay is a secure, real-time payment system built for banks and financial institutions in Libya. Its asynchronous transaction flow, two-step payment confirmation, and webhook notifications ensure a robust and scalable financial ecosystem.

📌 Key Takeaways:

Step 1: Initiate the transaction (Acknowledged status).
Step 2: Confirm the transaction (Processing or Immediate Response).
Asynchronous Processing: Webhooks notify FIs when transactions are finalized.
Additional APIs: Query transactions, handle refunds, and manage authentication.
Security Features: NAD enforcement, AML compliance, and secure API access.

This ensures fast, reliable, and secure payments for Libya’s financial institutions.

PreviousAccounting & Settlement in LYPay NextAPI Documentation

Last updated 3 days ago