Retrieve detailed information about a generated installment payment link, including its current status (Paid, Unpaid, Expired), customer details, and associated transaction records.
POST /payment_links/{payment_link_id}/details Parameter Type Required Description payment_link_idString (UUID) Yes The unique identifier of the payment link (e.g. d0901e69-02ec-499f-ba5c-9c7ef95ad062).
Authorization : YOUR_SECRET_KEY X-Amwal-Key : sandbox-amwal-xxx Content-Type : application/json Header Type Required Description AuthorizationString Yes Your Amwal Secret Key (e.g. d9ccf8bc-ed63-44ad-a54c-9d8fee63df6b). X-Amwal-KeyString No Merchant publishable API Key or sandbox identifier. Content-TypeString Yes Must be set to application/json.
No request body is required. An empty JSON object {} may be passed.
{ "payment_link" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "store_id" : "f24267bd-79f4-433f-a9f2-485c171301e4" , "status" : "Paid" , "amount" : 299.99 , "currency" : "SAR" , "title" : "Premium Service Invoice #INV-2024-001" , "description" : "Payment for premium headphones - 6-month installment" , "single_use" : true , "enabled" : true , "expiry_date" : "2026-12-31T23:59:59Z" , "created_at" : "2026-05-14T11:18:49Z" , "metadata" : { "order_id" : "ORD-9876" , "customer_id" : "CUST-12345" } }, "transactions" : [ { "id" : "60b43176-5991-4475-8ef6-c73c2417c805" , "status" : "success" , "amount" : 299.99 , "currency" : "SAR" , "bank_name" : "Al Rajhi Bank" , "payment_option" : "Installment" , "installment_duration" : 6 , "installment_status" : "Approved" , "installment_fee" : 0.00 , "monthly_installment" : 50.00 , "paymentBrand" : "VISA" , "number" : "411111xxxxxx1111" , "refunded_amount" : 0.00 , "refund_tracker" : null , "installment_tracker" : { "id" : "275460" , "status" : "A" , "message" : "Operation Successful" }, "failure_reason" : null , "created_at" : "2026-05-14T11:22:10Z" } ] } Field Type Description idString (UUID) Unique identifier of the payment link. store_idString (UUID) Store ID associated with this payment link. statusString Overall payment link status: Unpaid, Paid, or Expired. amountNumber Order total amount in SAR. currencyString ISO 4217 Currency code (SAR). titleString Display title configured on the payment link. descriptionString / Null Order or invoice description. single_useBoolean Whether the payment link expires upon first successful checkout. enabledBoolean Whether the link is currently active for payments. expiry_dateString (ISO 8601) / Null Expiration timestamp in UTC. created_atString (ISO 8601) Timestamp when the payment link was generated. metadataObject Custom key-value merchant metadata dictionary.
Field Type Description idString (UUID) Unique Amwal transaction identifier. statusString Authorization lifecycle state: pending, success, fail, partially refunded, or refunded. amountNumber Transaction authorization amount in SAR. currencyString Currency code (SAR). bank_nameString Partner bank processing the installment (e.g. Al Rajhi Bank, SNB, Alinma Bank, Riyad Bank). payment_optionString Payment method category: Installment or Pay In Full. installment_durationInteger / Null Selected installment tenure in months (3, 6, 12, 24). installment_statusString / Null Status of bank installment approval: Approved, Pending, or Declined. installment_feeNumber Merchant / bank installment financing fee. monthly_installmentNumber Monthly installment billing amount charged to the cardholder. paymentBrandString Card network: VISA, MASTERCARD, MADA, etc. numberString Masked card number (e.g. 411111xxxxxx1111). refunded_amountNumber Total cumulative refund amount accepted for this transaction. refund_trackerArray of Objects / Null List of individual refund attempts and their gateway settlement status (P = Pending, R = Settled). installment_trackerObject / Null Bank installment verification tracking object with approval code (A = Approved). failure_reasonString / Null Detailed decline message from issuing bank if status is fail. See Transaction Failed Reasons . created_atString (ISO 8601) Timestamp of transaction authorization in UTC.
Field Type Description idString Internal refund tracker identifier. statusString Gateway settlement status: "P" (Pending settlement at gateway) or "R" (Settled/Reconciled). amountNumber / String Refund amount in SAR for this specific refund event. gateway_transaction_idString Payment gateway transaction / refund reference number. rrnString / Null Bank Retrieval Reference Number populated once settled (status: "R").
payment_link.status reverts to Unpaid after ANY refund
Once a refund — even a small partial one — is applied to a transaction on
this link, payment_link.status reverts to Unpaid. This makes a
refunded link indistinguishable from one nobody has ever paid if
you only look at payment_link.status.
payment_link.status is not a reliable "was this order paid" check on
its own. For the true state, read each entry in transactions[].status
instead (success, partially refunded, refunded — see
Transaction Status ), and check
transactions[].refund_tracker for the settlement state of any refunds
(see Refund an Installment ).
Status Code Error Code Description 401 Unauthorizedauthentication_failedMissing or invalid Secret Key in the Authorization header. 404 Not Foundpayment_link_not_foundThe payment_link_id UUID does not exist or does not belong to your merchant account.
