Create Installment Link

Generate a hosted payment link or dynamic in-store QR code for 0% bank installment checkout.

Endpoint

POST /payment_links/{store_id}/create

Path Parameters

Parameter	Type	Required	Description
`store_id`	String (UUID)	Yes	Your unique Store ID retrieved from the Merchant Portal (e.g. `f24267bd-79f4-433f-a9f2-485c171301e4`).

Request Headers

Authorization: YOUR_SECRET_KEY
X-Amwal-Key: sandbox-amwal-xxx
Content-Type: application/json

Header	Type	Required	Description
`Authorization`	String	Yes	Your Amwal Secret Key (e.g. `d9ccf8bc-ed63-44ad-a54c-9d8fee63df6b`). Used for server-side REST requests.
`X-Amwal-Key`	String	No	Your merchant publishable API Key or sandbox identifier (e.g. `sandbox-amwal-b87482f2-xxx`).
`Content-Type`	String	Yes	Must be set to `application/json`.

Request Body

{
  "amount": 299.99,
  "title": "Premium Service Invoice #INV-2024-001",
  "description": "Payment for premium headphones - 6-month installment",
  "order_id": "ORD-9876",
  "singleUse": true,
  "selectedDate": "2026-12-31T23:59:59Z",
  "client_first_name": "Ahmed",
  "client_last_name": "Al-Rashid",
  "client_email": "customer@example.com",
  "client_phone_number": "+966501234567",
  "client_street1": "123 King Fahd Road",
  "client_street2": "Suite 100",
  "client_city": "Riyadh",
  "client_state": "Riyadh Province",
  "client_country": "SA",
  "client_postcode": "12345",
  "address_required": false,
  "language": "en",
  "send_sms": true,
  "sms_language": "ar",
  "passkey_enabled": true,
  "only_show_bank_installments": false,
  "only_show_pay_in_full": false,
  "callback_url": "https://yourstore.com/webhook/payment-complete",
  "branch": "RIYADH-001",
  "metadata": {
    "order_id": "ORD-9876",
    "customer_id": "CUST-12345",
    "terminal_id": "POS-001"
  }
}

Request Parameters

Order & General Settings

Field	Type	Required	Description
`amount`	Number	Yes	Total order amount in SAR. Minimum order amount for 0% bank installments is 300 SAR (Al Rajhi) or 1,000 SAR (SNB). Must be > 0. Example: `299.99`.
`title`	String	Yes	Short title displayed to the customer on the hosted checkout page (max 200 characters). Example: `"Premium Service Invoice #INV-2024-001"`.
`description`	String	No	Detailed order or invoice description (max 500 characters).
`order_id`	String	No	External merchant order identifier.
`singleUse`	Boolean	No	If `true` (default), the link automatically expires upon the first successful authorization. Default: `true`.
`selectedDate`	String	No	Expiration timestamp in ISO 8601 UTC format (e.g. `2026-12-31T23:59:59Z`).
`callback_url`	String (URI)	No	URL to redirect customer upon payment completion or cancellation.
`branch`	String	No	Physical retail branch or POS terminal identifier (e.g. `RIYADH-001`).
`metadata`	Object	No	Custom merchant key-value dictionary echoed back in webhooks and transaction queries.

Customer Details

Field	Type	Required	Description
`client_first_name`	String	No	Customer's first name (pre-populates checkout fields).
`client_last_name`	String	No	Customer's last name.
`client_email`	String (Email)	No	Customer's email address for digital receipts and notifications.
`client_phone_number`	String	No	Customer mobile number in E.164 international format (e.g. `+966501234567`).

Billing & Shipping Address

Field	Type	Required	Description
`client_street1`	String	No	Primary street address line.
`client_street2`	String	No	Secondary address line (apartment, suite, unit).
`client_city`	String	No	City (e.g. `Riyadh`, `Jeddah`, `Dammam`).
`client_state`	String	No	State or Province (e.g. `Riyadh Province`).
`client_country`	String	No	2-letter ISO 3166-1 alpha-2 country code. Default: `SA`.
`client_postcode`	String	No	Postal code / ZIP code.
`address_required`	Boolean	No	If `true`, customer must provide delivery address during checkout. Default: `false`.

Checkout & Display Preferences

Field	Type	Required	Description
`language`	String	No	Payment page locale: `"ar"` (Arabic, default) or `"en"` (English).
`send_sms`	Boolean	No	Whether to send an automated SMS with the payment URL to `client_phone_number`. Default: `true`.
`sms_language`	String	No	Language for automated SMS notification: `"ar"` (default) or `"en"`.
`passkey_enabled`	Boolean	No	Enable biometric passkey 1-click checkout for returning customers. Default: `true`.
`only_show_bank_installments`	Boolean	No	If `true`, hides regular card payment and only shows 0% bank installment plans. Default: `false`.
`only_show_pay_in_full`	Boolean	No	If `true`, hides installment plans and only shows full debit/credit card payment. Default: `false`.

Response (`200 OK`)

{
  "order_id": null,
  "payment_link_id": "0601db47-8944-4572-b4e9-339e636b5ba2",
  "url": "https://pay.sa.amwal.tech/payment-link/0601db47-8944-4572-b4e9-339e636b5ba2",
  "environment": "SANDBOX"
}

Response Parameters

Field	Type	Description
`order_id`	String / Null	External merchant order identifier echoed from the request, or `null` if not provided.
`payment_link_id`	String (UUID)	Unique payment link identifier generated for this checkout session.
`url`	String (URI)	Hosted payment checkout URL to redirect the customer to or share via SMS/WhatsApp/email.
`environment`	String	Target gateway environment: `"SANDBOX"` or `"PRODUCTION"`.

Error Responses

Status Code	Error Code	Description
`400 Bad Request`	`invalid_request`	Missing required fields (`amount`, `title`) or malformed JSON body.
`401 Unauthorized`	`authentication_failed`	Missing or invalid Secret Key in the `Authorization` header.
`404 Not Found`	`store_not_found`	The `store_id` UUID in the path does not exist or does not belong to your merchant account.
`422 Unprocessable`	`validation_error`	Order amount is below the minimum threshold (e.g. < 100.00 SAR) or invalid date format.

422 Validation Error Example

{
  "error": "validation_error",
  "message": "Amount must be at least 100.00 SAR for bank installment checkout.",
  "status_code": 422
}

On this page