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) orcancel_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://sela.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