Get Transaction By RefNumber

Use this endpoint to retrieve transaction details using refNumber aka reference number as a query parameter. This is the value specified in the purchase request and should match the one provided in the purchase request exactly. This helps fetch transaction-specific data for auditing, reconciliation, support, or record-keeping purposes.

Endpoint

Method: GET
URL: baseUrl/api/v1/transactions/

Query Parameters

You can use refNumber as a query parameter to fetch the transaction:

Parameter	Type	Required	Description
refNumber	string	No	The unique reference number for the transaction

Headers

• Authorization: Bearer {{accessToken}} (Include the token obtained from the Authentication API)
• Content-Type: application/json

Example Requests

By Reference Number:

GET /api/v1/transactions/?refNumber=abc011
HTTP/1.1
Authorization: Bearer {{accessToken}}
Content-Type: application/json

Response

A successful response returns a JSON object with the same structure as the Purchase API response:

{
    "status": "APPROVED",
    "message": "Approved",
    "receipt": {
        "id": 496,
        "merchantNameAr": "Bab Merchant Ar",
        "merchantNameEn": "Bab Merchant",
        "addressAr": "الرياض",
        "addressEn": "Riyadh",
        "startDate": "27/05/2025",
        "startTime": "13:21:51",
        "startDateTime": null,
        "endDateTime": null,
        "acquirerCode": "INMA",
        "merchantId": "100000000000001",
        "terminalId": "0210046200100462",
        "merchantCategoryCode": "0763",
        "stan": "000059",
        "appVersion": "1.0.0",
        "rrn": "514713000747",
        "cardSchemeId": "P1",
        "cardSchemeAr": "مدى",
        "cardSchemeEn": "Mada",
        "applicationLabelAr": null,
        "applicationLabelEn": null,
        "pan": "5069 68** **** 9140",
        "cardExpiration": "29/02",
        "transactionTypeAr": "شراء",
        "transactionTypeEn": "PURCHASE",
        "amountAuthorized": "1000",
        "amountAuthorizedAr": "مبلغ الشراء",
        "amountAuthorizedEn": "PURCHASE AMOUNT",
        "statusMessageAr": "مقبولة",
        "statusMessageEn": "Approved",
        "verificationMethodAr": "تم التحقق من هوية حامل الجهاز ",
        "verificationMethodEn": "DEVICE OWNER IDENTITY VERIFIED",
        "approvalCodeAr": "رمز الموافقة",
        "approvalCodeEn": "Approval Code",
        "approvalCode": "519030",
        "endTime": "13:21:53",
        "endDate": "27/05/2025",
        "entryMode": "CONTACTLESS",
        "switchResponseCode": "000",
        "applicationIdentifier": "A0000002281010",
        "terminalVerificationResult": "0080008000",
        "transactionStateInformation": "0000",
        "cardholderVerificationResult": "640300",
        "cryptogramInformationData": "80",
        "applicationCryptogram": "AB621EA892D7072B",
        "kernelId": "2d",
        "paymentAccountReference": "23R0380GI98ZLTVEDGWQSUTKYVMDD",
        "thanksMessageAr": "شكرا لاستخدامكم مدى",
        "thanksMessageEn": "Thank you for using mada",
        "saveReceiptMessageAr": "يرجى الاحتفاظ بالفاتورة",
        "saveReceiptMessageEn": "please retain receipt",
        "providerResponseCode": null
    }
}

For a full list of response fields and their descriptions, see the Purchase API documentation.

Error Handling

If the transaction is not found or another error occurs, you may receive an error response:

{
  "status": "failed",
  "msg": "Transaction not found"
}

Usage Tips

1. Token Authorization: Always ensure your token is valid before making a request. Include it in the Authorization header in the format: Authorization: Bearer <accessToken>.
2. Reference Number: Should match the one passed during the original purchase request.
3. Reference: For more details on the response fields, refer to the Purchase API.