Get Transaction Details

Retrieve complete transaction authorization data, partner bank approval details, installment tenure duration, fees, net merchant payout, and the refund_tracker array for a specific transaction ID.

Endpoint Details

Attribute	Details
Method	`GET`
URL	`https://backend.sa.amwal.tech/transactions/{transaction_id}`
Path Parameter	`transaction_id` (string, required) — Unique transaction UUID.
Authentication	Secured (`Authorization` + `X-Amwal-Key` headers)
Response 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
Accept: application/json

Header	Type	Required	Description
`Authorization`	String	Yes	Your Amwal Secret Key (e.g. `d9ccf8bc-ed63-44ad-a54c-9d8fee63df6b`).
`X-Amwal-Key`	String	Yes	Merchant Public Key (`sandbox-amwal-xxx` in Sandbox, `prod-amwal-xxx` in Production).
`Accept`	String	Yes	Must be set to `application/json`.

Example cURL Request

curl -s "https://backend.sa.amwal.tech/transactions/618f07c5-1d40-4b9e-bd40-f733936be163" \
  -H "Authorization: YOUR_SECRET_KEY" \
  -H "X-Amwal-Key: sandbox-amwal-xxx" \
  -H "Accept: application/json"

Response Payload (`200 OK`)

Below is an example response payload for an approved 0% bank installment transaction:

{
  "id": "618f07c5-1d40-4b9e-bd40-f733936be163",
  "status": "refunded",
  "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"
    }
  ],
  "created_at": "2026-09-01T14:48:30.097180+03:00",
  "trx_lang": "ar",
  "type": "SANDBOX",
  "is_refundable": false
}

Response Parameter Breakdown

1. Transaction Core & Status

Field	Type	Description
`id`	`string` (UUID)	Unique identifier of the transaction.
`status`	`string`	Transaction lifecycle status (`success`, `fail`, `partially refunded`, `refunded`).
`type`	`string`	Environment context (`SANDBOX` or `LIVE`).
`created_at`	`string` (ISO 8601)	Timestamp of payment authorization in UTC.
`trx_lang`	`string`	Language selected during checkout (`ar` or `en`).
`is_refundable`	`boolean`	`true` if remaining balance is eligible for refund; `false` once fully refunded or expired.

2. Financial & Fee Breakdown

Field	Type	Description
`amount` / `total_amount`	`string`	Gross purchase amount authorized in SAR.
`payment_amount`	`string`	Total amount charged including bank Murabaha financing fees.
`refunded_amount`	`string`	Cumulative amount refunded across all refund requests.
`amwal_fee`	`string`	Gateway MDR fee charged for transaction processing in SAR.
`amwal_tax_vat`	`string`	15% VAT on the Amwal gateway fee in SAR.
`brand_percentage`	`string`	Card scheme percentage interchange fee (e.g. `1.50%`).
`merchant_payout`	`string`	Net amount scheduled for settlement to merchant's corporate IBAN (`amount - amwal_fee - amwal_tax_vat`).
`murabha_fee`	`string`	Bank Murabaha financing fee charged by the issuing bank.
`murabha_fee_vat`	`string`	15% VAT on the bank financing fee.

3. Payment Method & Installments

Field	Type	Description
`paymentBrand`	`string`	Card network (`VISA`, `MASTERCARD`, `MADA`, `AMEX`).
`payment_method`	`string`	Payment channel (`Card`).
`payment_option`	`string`	Checkout mode (`Installment` or `Pay In Full`).
`number`	`string`	Masked card number (e.g. `411111xxxxxx1111`).
`bank_name`	`string`	Partner bank providing the 0% installment plan (e.g. `RAJHI`, `SNB`, `RIBL`, `INMA`).
`installment_duration`	`string`	Selected tenure in months (`3`, `6`, `12`, `24`).
`installment_status`	`string`	Bank loan approval status (`Approved`).
`installment_tracker`	`object`	Bank loan booking reference object (detailed below).

4. 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 message returned directly from the partner bank gateway (e.g. `Operation Successful`).

5. Refund Tracker (`refund_tracker[]`)

Field	Type	Description
`id`	`string`	Unique identifier for this refund execution.
`status`	`string`	Settlement status: `R` (Settled / Refunded) or `P` (Pending).
`amount`	`string`	Amount refunded 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.

6. Customer & Order Metadata

Field	Type	Description
`client_first_name`	`string`	Customer's first name.
`client_last_name`	`string`	Customer's last name.
`client_email`	`string`	Customer's email address.
`client_phone_number`	`string`	Customer's mobile phone number (E.164 format).
`order_details.order_id`	`string`	Merchant's internal order reference identifier.
`order_details.payment_link_metadata`	`object`	Custom metadata dictionary passed during payment link creation.
`payment_link_id`	`string` (UUID)	Associated Amwal payment link identifier.
`payment_link_callback_url`	`string`	Merchant redirect URL after checkout completion.

Status Fields & Lifecycle Reference

The transaction details endpoint returns several status properties representing different stages of payment authorization, bank underwriting, and refund reconciliation:

1. Transaction Lifecycle Status (`status`)

Status Value	Meaning & Actionable Guidance
`success`	The transaction was authorized and captured successfully. Merchant can proceed to order fulfillment.
`pending`	Transaction initiated and awaiting customer 3DS/Passkey authentication or bank processing.
`fail`	Payment declined by issuing bank or gateway (e.g. insufficient funds, 3DS authentication failure, expired session).
`partially refunded`	One or more partial refunds have been settled on the card network, leaving a positive balance remaining.
`refunded`	The full transaction amount (`100%`) has been completely refunded back to the cardholder.

2. Bank Installment Underwriting Status (`installment_status` / `installment_tracker.status`)

Status Code	Value	Meaning & Bank Workflow
`A`	`Approved`	The partner bank has approved the 0% installment loan, booked the credit facility with the cardholder, and guaranteed 100% upfront settlement to the merchant via SARIE.
`R`	`Rejected`	The bank declined the installment loan underwriting (e.g. cardholder credit limit exceeded, card not enrolled in 0% program, or order amount below bank minimum).
`P`	`Pending`	Installment underwriting review is in progress with the issuing bank.

3. Refund Tracker Settlement Status (`refund_tracker[].status`)

Status Code	Meaning	Behavioral Context
`R`	`Refunded` (Settled)	The refund was successfully processed by the payment switch and credited back to the customer's card.
`P`	`Pending`	When multiple partial refund requests are submitted for the same transaction ID within a 1-hour window, the first request is marked `R` (Refunded) and subsequent requests are marked `P` (Pending) pending manual finance team review.

Refund an Installment

Submit full or partial refund requests against this transaction ID.

Cards BIN Lookup

Query issuing bank and installment eligibility before initiating checkout.

Refund an Installment

Cards BIN Lookup

On this page