Purchase

Use the Purchase API to process a purchase transaction securely.

POSTbaseUrl/api/v1/transactions/purchase

Headers

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

Parameters

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)
terminalId	string	No	Required when authenticating using a Merchant Token. Not required when using a Cashier Token, as the terminal associated with the authenticated cashier is automatically used.

Example Request

{
  "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	Current transaction status. See Transaction Status Values below.
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.

Transaction Status Values

The status field represents the current state of the transaction.

Value	Status	Description
0	INITIALIZED	The transaction has been created and is waiting to be sent to the payment terminal.
1	PENDING	The transaction is currently being processed. Customer action or host processing may still be in progress.
2	APPROVED	The transaction was successfully authorized and completed.
3	CANCELED	The transaction was canceled before completion by the user or system.
4	DECLINED	The issuer or payment network declined the transaction.
5	NO_TERMINAL	No connected or available payment terminal could be found for processing the transaction.
6	TERMINAL_MISCONF	The assigned terminal is incorrectly configured or not properly registered.
7	TIMEOUT	The transaction exceeded the allowed processing or customer confirmation time.
8	ERROR	An unexpected system or processing error occurred while executing the transaction.
9	FAILED	The transaction failed to reach terminal and could not be completed.

Example Response

{
    "transactionId": 714749,
    "refNumber": "testone",
    "status": "APPROVED",
    "message": "Approved",
    "receipt": {
        "id": 599163,
        "merchantNameAr": "313233343536",
        "merchantNameEn": "RAJB Testing NeoLeap",
        "addressAr": "333231",
        "addressEn": "KAFD",
        "startDate": "23/07/2026",
        "startTime": "20:31:05",
        "startDateTime": "23/07/2026 20:31:05",
        "endDateTime": "23/07/2026 20:31:05",
        "acquirerCode": "RAJB",
        "merchantId": "803000000324   ",
        "terminalId": "1560127620231203",
        "merchantCategoryCode": "3014",
        "stan": "004668",
        "appVersion": "1.2.63",
        "rrn": "620420004668",
        "cardSchemeId": "P1",
        "cardSchemeAr": "مدى",
        "cardSchemeEn": "mada",
        "applicationLabelAr": null,
        "applicationLabelEn": "mada",
        "pan": "442463******9008",
        "cardExpiration": "27/02",
        "transactionTypeAr": "شراء",
        "transactionTypeEn": "Purchase",
        "amountAuthorized": "1.00",
        "amountAuthorizedAr": "مبلغ الشراء",
        "amountAuthorizedEn": "PURCHASE AMOUNT",
        "statusMessageAr": "مقبولة",
        "statusMessageEn": "APPROVED",
        "verificationMethodAr": "لا يتطلب التحقق",
        "verificationMethodEn": "NO VERIFICATION REQUIRED",
        "approvalCodeAr": "رمز الموافقة",
        "approvalCodeEn": "Approval Code",
        "approvalCode": "U5MUZ5",
        "endTime": "20:31:05",
        "endDate": "23/07/2026",
        "entryMode": "CONTACTLESS",
        "switchResponseCode": "000",
        "applicationIdentifier": "A0000002282010",
        "terminalVerificationResult": "0000000000",
        "transactionStateInformation": "0000",
        "cardholderVerificationResult": null,
        "cryptogramInformationData": null,
        "applicationCryptogram": "80",
        "kernelId": "03",
        "paymentAccountReference": null,
        "thanksMessageAr": "شكرا لاستخدامكم مدى",
        "thanksMessageEn": "Thank you for using mada",
        "saveReceiptMessageAr": "يرجى الاحتفاظ بالفاتورة",
        "saveReceiptMessageEn": "please retain receipt",
        "providerResponseCode": "00",
        "ecrToken": null
    }
}

Error Handling

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

Example Error

{
  "status": "timeout",
  "msg": "Transaction confirmation timed out"
}

Error Scenario	API Response Message	HTTP Status
Customer does not confirm the transaction before the timeout period expires	Transaction confirmation timed out.	504 Gateway Timeout
Cashier account attempts a purchase without a configured payment provider	Transaction declined. Payment provider is not configured for this merchant.	403 Forbidden
Transaction amount contains a decimal value	Invalid amount. Only whole numbers are allowed.	400 Bad Request
Request is sent to an incorrect or unsupported API endpoint	Endpoint not found. Check the API URL or version.	404 Not Found
Invalid, missing, or expired access token	Authentication failed. Invalid or expired token.	401 Unauthorized

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").