Create invoice

Creates an invoice and returns the hosted payment_url you send the buyer to.

Do this

Call this when the customer is ready to pay (not at cart browse time unless you
accept unused invoices).

Pass your order id in external_reference so webhooks can map back to the order.

Pass webhook_url (HTTPS in production). Without it you will not get events.

Pass success_url / cancel_url if you want the hosted page to send the buyer
back to your store after a terminal outcome.

Save invoice.id on the order before redirecting. This POST is not
idempotent — a retry creates another invoice.

Confirm

HTTP 201 with payment_url and invoice.status of pending.

invoice.amount is a string ("100.00"), even though you sent a number.

You did not send provider or sender identity. The buyer picks the rail
on the hosted page.

If it fails

403 account_not_ready — dashboard setup incomplete.

422 with errors.amount — below 20, above 70000, or more than 2 decimals.

422 No active payment numbers configured — add VF/InstaPay in the dashboard.

422 invalid_fees — customer-pays-fee flags are not viable for this merchant.

Requires merchant status = active and at least one active payment number.

Request

Authorization

API Key

Add parameter in header

X-API-Key

Example:

X-API-Key: ********************

API Key

Add parameter in header

X-API-Secret

Example:

X-API-Secret: ********************

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

curl --location '/api/v1/invoices' \ --header 'X-API-Key: <api-key>' \ --header 'X-API-Secret: <api-key>' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": 100, "currency": "EGP", "customer_name": "Ahmed Ali", "customer_email": "customer@example.com", "customer_phone": "01012345678", "customer_metadata": { "order_id": "1001" }, "external_reference": "ORD-1001", "success_url": "https://merchant.example/orders/1001/success", "cancel_url": "https://merchant.example/orders/1001/cancel", "webhook_url": "https://merchant.example/webhooks/autopay", "expires_in_hours": 48 }'

{ "invoice": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "amount": "100.00", "currency": "EGP", "status": "pending", "customer_email": "customer@example.com", "customer_name": "Ahmed Ali", "customer_phone": "01012345678", "customer_metadata": { "order_id": "1001" }, "external_reference": "ORD-1001", "success_url": "https://merchant.example/orders/1001/success", "cancel_url": "https://merchant.example/orders/1001/cancel", "webhook_url": "https://merchant.example/webhooks/autopay", "expires_at": "2026-08-19T10:00:00+00:00", "completed_at": null, "cancelled_at": null, "created_at": "2026-08-17T10:00:00+00:00", "updated_at": "2026-08-17T10:00:00+00:00" }, "payment_url": "https://autopayeg.com/payment/7c9e6679-7425-40de-944b-e07fc1f90ae7" }

Request

Responses