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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://central-bank-of-libya.gitbook.io/devportal/lypay/lypay-instant-payment-system-technical-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.