Creates an order up-front (AwaitingCheckout) and returns a hosted checkout URL —
no server-side checkout integration needed. Two channels:

• Link (default): requires phone; the customer receives the link by SMS (plus push
  notification and an IVR call).
• Qr: returns a URL you render as a QR code for the customer to scan.

language picks the language the customer is contacted in — "ar" (default) or "en". It sets the
SMS wording, the IVR script and voice, the push notification, and the language the hosted /pay
page opens in. Omit it and the request's Accept-Language decides, falling back to Arabic.

If orderReferenceId is omitted, one is generated (YYDDDNNNNN — the UTC year and day of year, then five digits, e.g. 2628041980).
ejarContractNumber — the Ejar platform contract the order finances — is required for a
real-estate merchant and ignored for any other merchant; it is returned on every read of the
link and order.
Links expire after 2 hours; poll GET /merchant/checkout-links/{id} for status.

Return URLs (optional): merchantUrl { success, failure, cancel, notification } — where the
hosted checkout sends the customer afterwards. Each URL must be absolute, at most 1024 characters
and carry no fragment; https, http only on localhost / 127.0.0.1, or a custom app scheme
(myshop://…) for a mobile app. success and failure go together; cancel defaults to
failure; notification is reserved and refused. The page appends orderId, orderReferenceId
and status (confirmed on success; declined, expired or failed on failure; cancelled) to
the URL's own query string. A return is a navigation, not a proof — confirm with
GET /merchant/orders/{orderId} before treating the order as paid.

Example request:

{ "amount": 250.00, "channel": "Link", "phone": "+9665XXXXXXXX", "language": "ar", "orderReferenceId": "MERCHANT-ORDER-12345" }

Real-estate merchant:

{ "amount": 18000.00, "channel": "Link", "phone": "+9665XXXXXXXX", "ejarContractNumber": "EJ-2026-000123" }

Idempotency: send an Idempotency-Key header (a fresh UUID v4 per order attempt) and reuse it
on retries — a retry replays the original answer (Idempotent-Replay: true) instead of creating a
second order. 409 REQUEST_IN_PROGRESS while the first attempt is still running (retry shortly);
422 IDEMPOTENCY_KEY_REUSED if the same key is sent with a different body.

Errors: 400 INVALID_AMOUNT / PHONE_REQUIRED / EJAR_CONTRACT_NUMBER_REQUIRED /
INVALID_EJAR_CONTRACT_NUMBER, 404 MERCHANT_NOT_FOUND, 409 MERCHANT_SUSPENDED.