Payments

This section explains how to create and manage payment transactions.

Payment Flow

1. Authentication: Obtain an Access Token (see Authentication section).
2. Create Transaction: Send payment details to the API.
3. Redirect Customer: Redirect the customer to the payment URL received in the response.
4. Handle Result: Receive the result at the return_url (success) or cancel_url (cancellation/failure).

Create a New Transaction

Endpoint: POST /payment/create

Headers:

Authorization: Bearer {access_token}
Content-Type: application/json

Parameters:

• amount (string, ✅ Required): Amount to be paid (e.g., "100.00")
• currency (string, ✅ Required): Currency code (e.g., "LYD")
• return_url (string, ✅ Required): Redirect URL upon success
• cancel_url (string, ✅ Required): Redirect URL upon cancellation or failure
• custom (string, ❌ Optional): Custom identifier for the order (e.g., your system's order ID)
• full_name (string, ❌ Optional): Customer's full name (to auto-fill the form)
• email (string, ❌ Optional): Customer's email
• phone (string, ❌ Optional): Phone number (Libyan format will be auto-formatted)
• payment_gateway (string, ❌ Optional): To pre-select the payment gateway (Alias)

Simple Request Example

{
    "amount": "100.00",
    "currency": "LYD",
    "return_url": "https://yourstore.com/payment/success",
    "cancel_url": "https://yourstore.com/payment/cancel",
    "custom": "ORDER_12345"
}

Success Response (200 OK)

{
    "message": {
        "code": 200,
        "success": ["CREATED"]
    },
    "data": {
        "token": "ABC123XYZ789",
        "payment_url": "https://mypay.ly/pay/v1/user/payment/preview/ABC123XYZ789"
    },
    "type": "success"
}

Redirect the customer to payment_url to complete the payment process.

Advanced Features

1. Auto-fill Customer Data

You can improve the user experience by sending their data in advance, which will auto-fill the payment form fields.

{
    "amount": "100.00",
    ...
    "full_name": "Ahmed Mohamed",
    "email": "ahmed@example.com",
    "phone": "0912345678"
}

2. Pre-select Payment Gateway

You can redirect the customer directly to a specific payment gateway, bypassing the gateway selection page.

Gateway Aliases:

• yasr-pay: Yasr Pay
• masrafi-pay: Masrafi Pay
• sahary-pay: Sahary Pay
• moamalat: Moamalat
• edfali: Edfali

Example:

{
    "amount": "100.00",
    ...
    "payment_gateway": "moamalat"
}

[!TIP] When sending all data (Name, Email, Phone, and Gateway), the Auto-Submit feature will be activated, where the customer is redirected to the bank page immediately after a brief summary.

Result Handling (Redirects)

On Success

The customer is redirected to the return_url with the following parameters:

GET https://yourstore.com/payment/success?type=success&token=ABC123XYZ789

On Cancellation/Failure

The customer is redirected to the cancel_url:

GET https://yourstore.com/payment/cancel?type=cancel&token=ABC123XYZ789