Purchase

Use the Purchase API to process a purchase transaction securely.

Endpoint

Method: POST
URL: baseUrl/api/v1/transactions/purchase

Headers

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

Request Body

Send a JSON object with the following fields:

Field	Type	Required	Description
amount	string	Yes	The amount to be processed. Must be a whole number, no decimals are allowed.
refNumber	string	Yes	A unique reference number for tracking (ECR reference number)

Example:

{
  "amount": "12000",
  "refNumber": "refNumber"
}

Response

A successful transaction returns a JSON object with the following fields:

Key Attributes

Field	Type	Description
transactionId	integer	Unique identifier for the transaction.
status	string	Overall transaction status. Usually "APPROVED" or "DECLINED".
message	string	Human-readable message related to the status.
receipt.id	integer	Unique identifier for the transaction receipt.
merchantNameEn	string	Merchant name in English.
merchantNameAr	string	Merchant name in Arabic.
addressEn	string	Merchant location address in English.
terminalId	string	Unique ID of the payment terminal.
merchantId	string	Unique merchant ID from acquirer (host/bank).
stan	string	System Trace Audit Number (STAN) for the transaction.
rrn	string	Retrieval Reference Number used for tracking transactions.
amountAuthorized	string	Authorized transaction amount in smallest currency unit (e.g., halalas).
cardSchemeEn	string	Card scheme used (e.g., "Mada", "Visa", "MasterCard").
pan	string	Masked Primary Account Number (PAN) of the card.
cardExpiration	string	Card expiration date (MM/YY).
transactionTypeEn	string	Type of transaction (e.g., "PURCHASE", "REFUND").
entryMode	string	How the card was read (e.g., "CONTACTLESS", "CHIP", "MAGSTRIPE").
approvalCode	string	Approval code returned from the issuer/bank.
switchResponseCode	string	Response code from the card switch. "000" usually indicates success.
startDate	string	Date when the transaction started (dd/mm/yyyy).
startTime	string	Time when the transaction started (hh:mm:ss).
endDate	string	Date when the transaction ended.
endTime	string	Time when the transaction ended.
statusMessageEn	string	Status description in English (e.g., "Approved", "Declined").
verificationMethodEn	string	Cardholder verification method (e.g., PIN, Contactless Auth).
thanksMessageEn	string	Thank you message shown on the receipt.
saveReceiptMessageEn	string	Instruction to retain receipt.
applicationIdentifier	string	AID – Identifies the card application used for the transaction.
applicationCryptogram	string	Cryptographic code generated by the card for security/authentication.
kernelId	string	Identifier of the EMV kernel used for the transaction.
paymentAccountReference	string	Unique reference for linking payments to digital wallets or services.

Example:

{
    "transactionId": 1797, 
    "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
    }
}

Error Handling

If the transaction fails, you may receive an error response.

Example:

{
  "status": "failed",
  "msg": "Insufficient Funds"
}

Error Scenario	Possible Message	Action Required
Invalid Token	Unauthorized	Re-authenticate to obtain a valid token.
Insufficient Balance	Insufficient Funds	Verify the user’s account balance.
Missing Fields	Bad Request	Ensure all required fields are included.

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 Numbers:
   • Use unique refNumber values for each transaction to prevent duplicate processing.
3. Transaction Amount: Verify that the amount field is formatted as a string (e.g., "12000").