Refund

Use the Refund API to process a refund transaction securely. This API can be used to refund the full or partial amount of the original transaction.

Endpoint

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

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.
transactionId	string	Yes	The unique identifier of the original transaction to be refunded.
refNumber	string	Yes	A unique reference number for tracking (ECR reference number)

Note: The transactionId field value can be found on the original transaction purchase api response. The refNumber field should be a new, unique value generated by the user to track the refund transaction.

Example:

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

Response

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

Key Attributes

Field	Type	Description
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:

{
    "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. Match Original Transaction: Ensure the transactionId provided maps to an existing transaction eligible for refund.
2. Reference Number: Use unique refNumber values for each transaction to prevent duplicate processing.
3. Transaction Id: Use the integer value with the same name retrieved from the purchase api response of the original transaction.