> For the complete documentation index, see [llms.txt](https://central-bank-of-libya.gitbook.io/devportal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://central-bank-of-libya.gitbook.io/devportal/lypay/lypay-instant-payment-system-technical-overview.md).

# 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:

  ```http
  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:

  ```http
  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:**

1. If the transaction **fails due to compliance checks** (e.g., daily limit exceeded), it will **immediately return a decline response**.
2. 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:

  ```http
  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**

1. **Retrieve Funds Transfer Status**
   * API:

     ```http
     GET /api/v1/payments/funds-transfers/{UUID}
     ```
   * Allows banks/FIs to query a transaction’s **current status**.
2. **List Transactions by Status**
   * APIs:

     ```http
     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**
3. **Find Transactions Using Internal Merchant Reference**
   * API:

     ```http
     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.

1. **Initiate a Refund**
   * API:

     ```http
     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**:

1. **Create a New Token**
   * API:

     ```http
     POST /api/v1/auth/token
     ```
   * Generates a new API token for the authenticated entity.
2. **Reset Password**
   * API:

     ```http
     POST /api/v1/auth/password/reset
     ```
   * Allows users to update their credentials securely.
3. **Revoke an Existing Token**
   * API:

     ```http
     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.