Integrate

Payment intents

One payment for one order: its fields, statuses and expiry.

The customer can try many times, with any method. An intent succeeds at most once.

Fields

Field	Type	Description
`uuid`	string (UUID)	The ID. Store it with your order.
`reference`	string	Short reference on the customer’s receipt.
`merchant_reference`	string	Yours; unique per application (Idempotency).
`amount`	integer	Minor units: `5000` is 5.000 LYD. Minimum `1000`.
`currency`	string	`LYD`
`status`	string	See Statuses.
`description`	string	Shown on the checkout.
`customer.external_id`	string or null	Your customer ID.
`return_url`	string or null	Where the customer comes back.
`metadata`	object or null	Up to 20 keys (40 chars), string values up to 255.
`expires_at`	string (ISO 8601)	No new payments after this.
`checkout_url`	string (URL)	The hosted checkout.
`created_at`, `updated_at`	string (ISO 8601)	Timestamps.

Statuses

Status	Meaning	What to do
`requires_payment_method`	New, or the last try failed.	Wait.
`processing`	A payment is under way, or Ethaq is confirming an unclear answer.	Wait. Not a failure.
`succeeded`	Paid. Final.	Fulfil, once.
`canceled`	Expired unpaid. Not final.	See late payments.

There is no failed status and no webhook for a declined try.

requires_payment_method ⇄ processing ──→ succeeded
          │                   │              ↑
          └──────→ canceled ←─┘              │
                      └──── late payment ────┘

Expiry

expires_at: 5 minutes to 31 days ahead; default 24 hours.

After expires_at:

No new payment can start; one under way may still finish.
Within a few minutes of nothing being under way, the intent becomes canceled.
Fanak sends payment_intent.canceled.

Late payments

A verified payment confirmed after cancellation still wins: the intent becomes succeeded and payment_intent.succeeded follows the earlier payment_intent.canceled.

To charge the same order again, use a new merchant_reference (order-1042-2); the old one returns the canceled intent.

Retrieving an intent

GET /payment-intents/{uuid} is the source of truth: call it on every webhook and return. See the API reference.