Query historical payment links, filter by payment status (Paid, Unpaid, Expired), filter by date range or retail branch, and retrieve associated customer details.
POST /payment_links/{store_id}/list Parameter Type Required Description store_idString (UUID) Yes Your unique Store ID retrieved from the Merchant Portal (e.g. f24267bd-79f4-433f-a9f2-485c171301e4).
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.
{ "page" : 1 , "limit" : 20 , "status" : "Paid" , "from_date" : "2026-01-01T00:00:00Z" , "to_date" : "2026-06-30T23:59:59Z" , "branch" : "RIYADH-001" , "sort_by" : "created_at" , "sort_order" : "desc" } Field Type Required Description pageInteger No Page number for pagination. Default: 1. limitInteger No Number of records to return per page (max 100). Default: 20. statusString No Filter by link status. Allowed values: Paid, Unpaid, Expired. from_dateString (ISO 8601) No Filter records created on or after this UTC timestamp (e.g. 2026-01-01T00:00:00Z). to_dateString (ISO 8601) No Filter records created on or before this UTC timestamp (e.g. 2026-06-30T23:59:59Z). branchString No Filter records by physical retail branch code or cashier location (e.g. RIYADH-001). sort_byString No Field to sort results by. Allowed values: created_at, amount. Default: created_at. sort_orderString No Sorting order. Allowed values: asc (ascending), desc (descending). Default: desc.
{ "total" : 142 , "page" : 1 , "limit" : 20 , "data" : [ { "payment_link_id" : "550e8400-e29b-41d4-a716-446655440000" , "amount" : 1200.00 , "currency" : "SAR" , "status" : "Paid" , "title" : "Order #8921" , "description" : "Electronics purchase - 6 Month Installment" , "single_use" : true , "branch_name" : "RIYADH-001" , "created_at" : "2026-05-14T11:18:49Z" , "customer" : { "first_name" : "Ahmed" , "last_name" : "Al-Rashid" , "email" : "ahmed@example.com" , "phone" : "+966501234567" }, "url" : "https://pay.sa.amwal.tech/payment-link/550e8400-e29b-41d4-a716-446655440000" } ] } Field Type Description totalInteger Total number of payment links matching the query filters. pageInteger Current page index returned. limitInteger Number of items per page. dataArray of Objects List of payment link records matching the search criteria.
Field Type Description payment_link_idString (UUID) Unique payment link identifier. amountNumber Total authorized amount in SAR. currencyString ISO currency code (e.g. SAR). statusString Current link state: Paid, Unpaid, or Expired. titleString Title displayed on the checkout page. descriptionString / Null Order or invoice description. single_useBoolean Whether the payment link expires upon first successful checkout. branch_nameString / Null Associated retail store branch or POS terminal identifier. created_atString (ISO 8601) Timestamp when the payment link was created in UTC. customerObject Customer contact details associated with the link. customer.first_nameString / Null Customer first name. customer.last_nameString / Null Customer last name. customer.emailString / Null Customer email address. customer.phoneString / Null Customer mobile phone in international format. urlString (URI) Direct checkout URL for the payment link.
Status Code Error Code Description 400 Bad Requestinvalid_parametersInvalid date range (from_date after to_date) or invalid page/limit values. 401 Unauthorizedauthentication_failedMissing or invalid Secret Key in the Authorization header. 404 Not Foundstore_not_foundThe specified store_id does not exist or does not belong to the authenticated account.
