Get Payment Link Details

Retrieve detailed information about a generated installment payment link, including its current status (Paid, Unpaid, Expired), customer attributes, pagination, and the complete array of associated transaction records.

Endpoint Details

Attribute	Details
Method	`POST` / `GET`
URL	`https://backend.sa.amwal.tech/payment_links/{payment_link_id}/details`
Path Parameter	`payment_link_id` (string, required) — Unique payment link UUID.
Authentication	Secured (`Authorization` + `X-Amwal-Key` headers)
Content-Type	`application/json`

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`.

Example cURL Request

curl -s -X POST "https://backend.sa.amwal.tech/payment_links/c63608d3-7c6d-4ae3-8678-b2003601ee97/details" \
  -H "Authorization: YOUR_SECRET_KEY" \
  -H "X-Amwal-Key: sandbox-amwal-xxx" \
  -H "Content-Type: application/json" \
  -d '{}'

Response Payload (`200 OK`)

Below is an example response payload returned by the Amwal API:

{
  "payment_link": {
    "id": "c63608d3-7c6d-4ae3-8678-b2003601ee97",
    "amount": "1255.00000",
    "title": "Amwal installment charge for Order #109f4d52",
    "description": "Amwal installment charge for Order #109f4d52",
    "single_use": true,
    "enabled": false,
    "expiry_date": "2026-09-01T14:53:25.159000+03:00",
    "created_at": "2026-09-01T14:48:25.313434+03:00",
    "merchant_business_name": "Example Retail Store",
    "merchant_english_business_name": null,
    "merchant_country_code": "SA",
    "merchant_id": "87ccc829-xxxx-xxxx-xxxx-8ea454688db7",
    "created_by_username": "Admin User",
    "created_by_email": "admin@example.com",
    "status": "Paid",
    "client_first_name": "Ahmed",
    "client_last_name": "Al-Mansoor",
    "full_name": "Ahmed Al-Mansoor",
    "client_email": "customer@example.com",
    "client_phone_number": "+966500000000",
    "address_required": false,
    "has_customer_details": true,
    "has_address_details": false,
    "only_show_bank_installments": true,
    "only_show_pay_in_full": false,
    "passkey_enabled": true,
    "is_expired": false,
    "environment_type": "SANDBOX",
    "order_id": "109f4d52-c593-4e8e-9df7-90cdd4b0490a",
    "callback_url": "https://merchant-store.com/checkout/callback?trackId=track-eaa52cb2&chargeId=charge-amwal-ec15aaab",
    "metadata": {
      "trackId": "track-eaa52cb2-4fb9-4ac8-8e6b-adb4cecb70e2"
    }
  },
  "transactions": [
    {
      "id": "618f07c5-1d40-4b9e-bd40-f733936be163",
      "amount": "1255.00000",
      "total_amount": "1255.00",
      "payment_amount": "1291.09",
      "refunded_amount": "1255.00",
      "amwal_fee": "18.82",
      "amwal_tax_vat": "2.82",
      "brand_percentage": "1.50",
      "brand_static_fee": "0.00",
      "merchant_payout": "1233.35",
      "merchant_business_name": "Example Retail Store",
      "merchant_country_code": "SA",
      "merchant_id": "87ccc829-xxxx-xxxx-xxxx-8ea454688db7",
      "merchant_key": "sandbox-amwal-xxxx-xxxx-xxxx-5a54dc815fcd",
      "paymentBrand": "VISA",
      "payment_method": "Card",
      "payment_option": "Installment",
      "number": "411111xxxxxx1111",
      "bank_name": "RAJHI",
      "installment_duration": "3",
      "installment_status": "Approved",
      "installment_tracker": {
        "id": "287436",
        "status": "A",
        "message": "Operation Successful"
      },
      "installment_fee": "0.00",
      "installment_fee_vat": "0.00",
      "murabha_fee": "31.38",
      "murabha_fee_vat": "4.71",
      "payment_link_id": "c63608d3-7c6d-4ae3-8678-b2003601ee97",
      "payment_link_callback_url": "https://merchant-store.com/checkout/callback?trackId=track-eaa52cb2&chargeId=charge-amwal-ec15aaab",
      "payment_link_description": "Amwal installment charge for Order #109f4d52",
      "payment_link_passkey_enabled": true,
      "payment_link_only_show_bank_installments": true,
      "payment_link_only_show_pay_in_full": false,
      "payment_link_show_shipping": false,
      "billing_address_required": false,
      "supports_stc_pay": false,
      "client_first_name": "Ahmed",
      "client_last_name": "Al-Mansoor",
      "client_email": "customer@example.com",
      "client_phone_number": "+966500000000",
      "address_details": {
        "name": "Riyadh, Saudi Arabia"
      },
      "order_details": {
        "order_id": "109f4d52-c593-4e8e-9df7-90cdd4b0490a",
        "payment_link_metadata": {
          "trackId": "track-eaa52cb2-4fb9-4ac8-8e6b-adb4cecb70e2"
        }
      },
      "refund_tracker": [
        {
          "id": "5059",
          "status": "R",
          "amount": "1255.00",
          "gateway_transaction_id": "2026001835",
          "gateway_key_type": "RefundReference",
          "rrn": "624411293930",
          "idempotency_key": "a6861821-e90e-42d4-b501-9f144e4cc01a",
          "order_refund_id": "8f6cae9f-3d65-4696-aa91-11080088c4ce"
        }
      ],
      "status": "refunded",
      "type": "SANDBOX",
      "created_at": "2026-09-01T14:48:30.097180+03:00",
      "trx_lang": "ar",
      "is_refundable": false
    }
  ],
  "pagination": {
    "count": 1,
    "next": false,
    "previous": false,
    "page": 1,
    "page_size": 10,
    "total_pages": 1
  }
}

Response Parameter Breakdown

1. Payment Link Object (`payment_link`)

Field	Type	Description
`id`	`string` (UUID)	Unique identifier of the payment link.
`status`	`string`	Link lifecycle state: `Unpaid`, `Paid`, or `Expired`.
`amount`	`string`	Order total amount in SAR.
`title`	`string`	Display title on the checkout page.
`description`	`string`	Itemized invoice or cart description.
`single_use`	`boolean`	If `true`, the link closes upon the first successful payment.
`enabled`	`boolean`	Whether the link is active and accepting payment attempts.
`expiry_date`	`string` (ISO 8601)	Timestamp when the payment link automatically expires.
`created_at`	`string` (ISO 8601)	Timestamp when the link was created.
`environment_type`	`string`	Environment context (`SANDBOX` or `LIVE`).
`order_id`	`string`	Merchant internal order identifier.
`full_name`	`string`	Customer's full name.
`client_email`	`string`	Customer's email address.
`client_phone_number`	`string`	Customer's phone number in E.164 format.
`passkey_enabled`	`boolean`	Whether 1-click biometric Passkeys are active for this checkout.
`only_show_bank_installments`	`boolean`	If `true`, checkout only presents 0% bank installment plans.
`callback_url`	`string`	Redirect destination URL upon payment completion.
`metadata`	`object`	Custom metadata dictionary passed during creation.

2. Nested Transactions Array (`transactions[]`)

Field	Type	Description
`id`	`string` (UUID)	Unique Amwal transaction identifier.
`status`	`string`	Transaction lifecycle status (`success`, `fail`, `partially refunded`, `refunded`).
`amount`	`string`	Gross amount authorized in SAR.
`refunded_amount`	`string`	Cumulative refunded amount in SAR.
`amwal_fee`	`string`	Gateway MDR processing fee in SAR.
`amwal_tax_vat`	`string`	15% VAT on the Amwal gateway fee.
`merchant_payout`	`string`	Net settlement amount scheduled for merchant corporate IBAN.
`paymentBrand`	`string`	Card network (`VISA`, `MASTERCARD`, `MADA`, `AMEX`).
`payment_option`	`string`	Checkout mode (`Installment` or `Pay In Full`).
`number`	`string`	Masked card number (e.g. `411111xxxxxx1111`).
`bank_name`	`string`	Partner bank providing 0% installments (e.g. `RAJHI`, `SNB`, `RIBL`, `INMA`).
`installment_duration`	`string`	Selected tenure duration in months (`3`, `6`, `12`, `24`).
`installment_status`	`string`	Bank loan approval status (`Approved`).
`installment_tracker`	`object`	Bank loan facility tracking object (contains `id`, `status: "A"`, and `message`).
`refund_tracker`	`array`	Complete list of all refund attempts, gateway IDs, and bank `rrn` numbers.

3. Installment Tracker Object (`installment_tracker`)

Field	Type	Description
`id`	`string`	Unique installment loan facility tracking ID assigned by the partner bank.
`status`	`string`	Bank underwriting status code: `A` (Approved), `R` (Rejected), or `P` (Pending).
`message`	`string`	Status confirmation message returned by the partner bank.

4. Refund Tracker Object (`refund_tracker[]`)

Field	Type	Description
`id`	`string`	Internal refund execution identifier.
`status`	`string`	Gateway settlement status: `R` (Settled / Refunded) or `P` (Pending).
`amount`	`string`	Refund amount in SAR for this specific refund event.
`gateway_transaction_id`	`string`	Bank gateway refund reference number.
`rrn`	`string`	Bank Retrieval Reference Number (`RRN`) used for cardholder bank tracing.
`idempotency_key`	`string`	Idempotency UUID preventing duplicate executions.
`order_refund_id`	`string`	Internal order refund reference identifier.

5. Pagination Object (`pagination`)

Field	Type	Description
`count`	`integer`	Total number of transactions recorded for this payment link.
`page`	`integer`	Current results page number.
`page_size`	`integer`	Maximum number of transaction items per page (default: `10`).
`total_pages`	`integer`	Total available pagination pages.
`next`	`boolean`	`true` if subsequent pages exist.
`previous`	`boolean`	`true` if preceding pages exist.

Create Installment Link

Generate hosted checkout sessions and dynamic QR codes.

Get Transaction Details

Query transaction authorization data and fee breakdowns.

Create Installment Link

Get Transaction Details

On this page