Resolve Installment Link

Resolve an existing payment link ID into a direct, browser-ready checkout session with full merchant branding, installment tenure options, and partner bank availability.

Endpoint

POST /payment_links/{payment_link_id}/resolve

Path Parameters

Parameter	Type	Required	Description
`payment_link_id`	String (UUID)	Yes	The unique payment link identifier to resolve (e.g. `550e8400-e29b-41d4-a716-446655440000`).

Request Headers

Pass your merchant public key in the required X-Amwal-Key header:

Sandbox: X-Amwal-Key: sandbox-amwal-xxx
Production: X-Amwal-Key: prod-amwal-xxx

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. `<YOUR_SECRET_KEY_UUID>`).
`X-Amwal-Key`	String	Yes	Merchant Public Key (`sandbox-amwal-xxx` in Sandbox, `prod-amwal-xxx` in Production).
`Content-Type`	String	Yes	Must be set to `application/json`.

Request Body

No request body is required. An empty JSON object {} may be passed.

Response (`200 OK`)

{
  "status": "valid",
  "payment_link_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 299.99,
  "currency": "SAR",
  "merchant_name": "Amwal Electronics Store",
  "supported_banks": [
    "Al Rajhi Bank",
    "Saudi National Bank (SNB)",
    "Alinma Bank",
    "Riyad Bank"
  ],
  "installment_tenures": [3, 6, 12, 24],
  "expires_at": "2026-12-31T23:59:59Z"
}

Response Parameters

Field	Type	Description
`status`	String	Validation state of the checkout link: `"valid"`, `"expired"`, or `"already_paid"`.
`payment_link_id`	String (UUID)	Unique identifier of the resolved payment link.
`amount`	Number	Order total amount in SAR.
`currency`	String	ISO 4217 currency code (e.g. `SAR`).
`merchant_name`	String	Merchant or store display name shown to the buyer on the checkout interface.
`supported_banks`	Array of Strings	List of partner Saudi banks offering 0% installment plans for this checkout session (e.g. `["Al Rajhi Bank", "Saudi National Bank (SNB)", "Alinma Bank", "Riyad Bank"]`).
`installment_tenures`	Array of Integers	Available installment duration options in months (e.g. `[3, 6, 12, 24]`). Note: SNB requires ≥1,000 SAR and offers 3, 6, 12 months; Al Rajhi requires ≥300 SAR and offers 3, 6, 12, 24 months.
`expires_at`	String (ISO 8601)	Expiry timestamp in UTC after which payment attempts are rejected.

Error Responses

Status Code	Error Code	Description
`401 Unauthorized`	`authentication_failed`	Missing or invalid Secret Key in the `Authorization` header.
`404 Not Found`	`payment_link_not_found`	The payment link ID does not exist or has expired.

On this page