Payments

This section explains how to create and manage payment transactions.

Payment Flow

Authentication: Obtain an Access Token (see Authentication section).
Create Transaction: Send payment details to the API.
Redirect Customer: Redirect the customer to the payment URL received in the response.
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.

[!NOTE] The payment_url path depends on the API environment you used:

Production: https://mypay.ly/pay/v1/user/payment/preview/{token}

Sandbox: https://mypay.ly/pay/sandbox/v1/user/payment/preview/{token}

When calling the Sandbox API base URL (/pay/sandbox/api/v1/), the returned payment_url includes /sandbox/ in the path.

Access Token and Retry Behavior

First payment/create: Initializes the payment (order status moves to pending).
Identical retry (same access_token and same request body): Returns 200 OK with the same token and payment_url (idempotent).
Changed payload on the same token: Returns 409 Conflict.

409 Conflict example:

{
    "message": {
        "code": 409,
        "error": ["Payment already initialized for this access token. Request a new authentication token for each order."]
    },
    "data": {},
    "type": "error"
}

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
sadad: SADAD
mobicash: Mobicash
prepaid-card: Prepaid card redemption (merchant must have prepaid card checkout enabled)

[!NOTE] If prepaid card checkout is not enabled for your merchant account, payment/create with payment_gateway: "prepaid-card" returns 400 Bad Request.

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

← Core Features

Webhooks →