API reference
Create a payment intent
const url = 'https://pay.fanak.ly/api/v1/payment-intents';const options = { method: 'POST', headers: { 'X-API-Key': '<X-API-Key>', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"merchant_reference":"order-1042","amount":5000,"currency":"LYD","customer":{"external_id":"cust_981"},"description":"Order #1042","return_url":"https://shop.example.com/orders/1042/return","metadata":{"order_id":"1042"},"expires_at":"2026-10-10T18:00:00+02:00"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://pay.fanak.ly/api/v1/payment-intents \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <X-API-Key>' \ --data '{ "merchant_reference": "order-1042", "amount": 5000, "currency": "LYD", "customer": { "external_id": "cust_981" }, "description": "Order #1042", "return_url": "https://shop.example.com/orders/1042/return", "metadata": { "order_id": "1042" }, "expires_at": "2026-10-10T18:00:00+02:00" }'Creates an intent in requires_payment_method and returns its checkout_url. Redirect the customer there
to pay.
merchant_reference is the idempotency key. Creating an intent again with a reference this application
already used returns the existing intent with 200, unchanged and whatever its state, instead of a new one
with 201. The other fields of the repeated request are ignored, so compare the returned amount with
your order. A repeated request must still pass validation.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Your own unique reference for this payment, such as an order number. It is the idempotency key:
creating an intent again with a reference this application already used returns the existing
intent unchanged (200) instead of creating a new one (201).
The amount in the currency’s minor unit, as an integer. LYD has 3 decimal places, so
5000 is 5.000 LYD. The minimum is 1000 (1.000 LYD), the maximum 1000000000 (1,000,000.000 LYD).
ISO 4217 currency code. Currently LYD.
object
Your identifier for the customer, echoed back as customer.external_id.
What the customer is paying for. Shown on the hosted checkout.
Where the hosted checkout sends the customer back after paying (and offers a link back from an expired checkout). Nothing is appended to it: include your own order identifier in the URL.
Up to you: key-value pairs stored with the intent and returned as-is. At most 20 keys of up to 40 characters; values must be strings of up to 255 characters.
When the checkout stops taking payments (ISO 8601). It must be more than 5 minutes and less than 31 days ahead; without it the intent expires 24 hours after creation. The window is checked only when an intent is created, so a retried create still returns the existing intent.
Responses
Section titled “Responses”An intent with this merchant_reference already existed; it is returned unchanged.
object
object
The intent’s ID. Store it with your order: you need it to retrieve the intent.
A short Fanak reference, shown to the customer on the checkout receipt (in capitals).
The merchant_reference you created the intent with.
The amount in the currency’s minor unit (5000 = 5.000 LYD).
ISO 4217 currency code
The intent’s state.
requires_payment_method: waiting for the customer to pay (or to try again after a failed attempt).
processing: a payment attempt is under way. succeeded: paid; final. canceled: expired unpaid;
a verified late payment can still move it to succeeded. Fulfil the order on succeeded only.
What the customer is paying for.
object
Your identifier for the customer, if you sent one.
Where the hosted checkout sends the customer back, if you set one.
The key-value pairs you sent, returned as-is.
When the checkout stops taking payments (ISO 8601).
The hosted checkout page. Redirect the customer here to pay; append ?lang=en for English
(Arabic is the default).
Example
{ "data": { "reference": "c5pk2mfgmv167awg", "currency": "LYD", "status": "requires_payment_method" }}The intent was created.
object
object
The intent’s ID. Store it with your order: you need it to retrieve the intent.
A short Fanak reference, shown to the customer on the checkout receipt (in capitals).
The merchant_reference you created the intent with.
The amount in the currency’s minor unit (5000 = 5.000 LYD).
ISO 4217 currency code
The intent’s state.
requires_payment_method: waiting for the customer to pay (or to try again after a failed attempt).
processing: a payment attempt is under way. succeeded: paid; final. canceled: expired unpaid;
a verified late payment can still move it to succeeded. Fulfil the order on succeeded only.
What the customer is paying for.
object
Your identifier for the customer, if you sent one.
Where the hosted checkout sends the customer back, if you set one.
The key-value pairs you sent, returned as-is.
When the checkout stops taking payments (ISO 8601).
The hosted checkout page. Redirect the customer here to pay; append ?lang=en for English
(Arabic is the default).
Example
{ "data": { "reference": "c5pk2mfgmv167awg", "currency": "LYD", "status": "requires_payment_method" }}Missing or invalid credentials. A missing or invalid access token returns message; a missing or unknown API key returns error.
An error
object
Error overview.
Example
{ "message": "Conflict creating payment intent."}Validation error
object
Errors overview.
A detailed description of each field that failed validation.
object
Example generated
{ "message": "example", "errors": { "additionalProperty": [ "example" ] }}