Refund

Overview

When a customer buys an item and wants to return it, then you can easily refund their payment. You can use the Geidea merchant portal or our Refund API to refund money to your customers either fully or partially.

🚧
You can refund a payment only for payments that have been completed i.e. the Pay API has been executed successfully or the Authorise and Capture APIs have been executed successfully.

👍
You can refund a transaction for the full amount or a partial amount. You can refund multiple times for the same payment. The Geidea payment gateway ensures that you do not refund a cumulative amount that is more than the payment received by the merchant

📘
Refunds can only be initiated for captured or paid or settled transactions, while you can use the Void operation for pre-authorized and uncaptured transactions only.

Using the dashboard in the merchant portal

You can easily refund a transaction from the dashboard by the following steps:

Open the transactions screen.
Search for the transaction to be refunded.
Click on this transaction.
Click the Refund button against the transaction.
To initiate a partial refund, select the Partial Refund option, and enter the amount in the pop-up.
The Refund or Partial Refund button is enabled only if transaction status is either Paid or Captured

Using the API

To initiate a Refund API call, you will need to provide the following required fields.

Parameter	Datatype	Description	Mandatory
`orderId`	string	This is a unique identifier for this order to discern it from the other orders you created. If orderId is not sent with the request, an orderId is created by the server and returned in the response. The orderid can be used to refer to this order in subsequent transactions and in retrieving metadata about the order. The orderId must always be unique for every order created under your merchant profile. This must be a valid GUID.	Yes
`callbackURL`	string	The URL where the response containing order details will be returned. Must be a valid URL and must have an HTTPS protocol.	No
`refundAmount`	float	The amount of refund. The amount must be greater than 0.01. Must not have more than 2 digits after the decimal point.	Yes
`timestamp`	string	The timestamp of the moment at which the refund request has been initiated.	No
`signature`	string	A parameter to ensure the security and authenticity of API communications. It involves generating a signature using the contents of the API request and secret keys, which is then sent along with the request.	Yes

You can find a complete list of parameters which can be used with the Refund API here.

Signature creation for Refund

We have a signature parameter in the Refund API to have an additional layer of security during payment processing. To generate the signature, follow the steps below:

Concatenate the string of {TimeStamp, MerchantPublicKey, RefundAmount, OrderID)
Hash (SHA-256) this Concatenated string by (Merchant_API_Password)
Convert Hashed Value to Base64Str

Below is an example of executing a Refund API call with the mandatory parameters.

curl --location 'https://api.merchant.geidea.net/pgw/api/v2/direct/refund' \
--header 'accept: text/plain' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YTA4N2Y0Y2EtOTg5MC00MDdiLTljMmYtNzYzMDgzNmNjMDIwOmRmMGZjNjg3LTc4M2ItNDA1OC1hZjYzLTllODc2NDQ0YjM1Nw==' \
--data '{
  "orderId": "47bbd481-fdc0-44e2-5dda-08db15bcae4b",
  "callbackUrl": "https://www.callmeback.com",
  "refundAmount": 102,
  "timestamp": "3/18/2024 5:16:48 AM",
  "signature": "1KeVT7QumxpsWY8SnWN8WzTBlKdwz1EGBaANIEoh5mg="
}'

{
    "order": {
        "orderId": "47bbd481-fdc0-44e2-5dda-08db15bcae4b",
        "amount": 123.21,
        "tipAmount": 0.00,
        "convenienceFeeAmount": 0.00,
        "totalAmount": 123.21,
        "settleAmount": 123.21,
        "currency": "SAR",
        "settleCurrency": "SAR",
        "language": "en",
        "detailedStatus": "PartiallyRefunded",
        "status": "Success",
        "threeDSecureId": "b6ca1e21-a72b-4fe6-c8e9-08db15bca2ed",
        "merchantId": "e80ece7e-fb2a-4c0b-de94-08d8a29a107b",
        "merchantPublicKey": "a087f4ca-9890-407b-9c2f-7630836cc020",
        "parentOrderId": null,
        "merchantReferenceId": null,
        "mcc": null,
        "callbackUrl": "https://www.callmeback.com",
        "customerEmail": null,
        "billingAddress": null,
        "shippingAddress": null,
        "returnUrl": "https://someurl.com",
        "cardOnFile": false,
        "tokenId": null,
        "initiatedBy": "Internet",
        "agreementId": null,
        "agreementType": null,
        "paymentOperation": "Pay",
        "custom": null,
        "paymentIntent": null,
        "restrictPaymentMethods": false,
        "paymentMethods": null,
        "platform": null,
        "statementDescriptor": null,
        "description": null,
        "createCustomer": false,
        "setDefaultPaymentMethod": false,
        "customerReferenceId": null,
        "customerId": null,
        "recurrence": null,
        "transactions": [
            {
                "transactionId": "7862b7d2-83be-4964-73ae-08db103ef15a",
                "type": "Pay",
                "status": "Success",
                "amount": 123.21,
                "currency": "SAR",
                "source": "DirectAPI",
                "authorizationCode": "124112",
                "rrn": "305907124112",
                "stan": "124112",
                "paymentMethod": {
                    "type": "Card",
                    "brand": "mastercard",
                    "cardholderName": "test",
                    "maskedCardNumber": "512345******2346",
                    "wallet": null,
                    "expiryDate": {
                        "month": 1,
                        "year": 39
                    },
                    "sameBank": false,
                    "issuingCountry": null,
                    "fundingType": null,
                    "issuingBank": null,
                    "cardCategory": null
                },
                "codes": {
                    "acquirerCode": "00",
                    "acquirerMessage": "Approved",
                    "responseCode": "000",
                    "responseMessage": "Success",
                    "detailedResponseCode": "000",
                    "detailedResponseMessage": "The operation was successful"
                },
                "authenticationDetails": null,
                "postilionDetails": null,
                "terminalDetails": null,
                "meezaDetails": null,
                "bnplDetails": null,
                "bankInstallmentDetails": null,
                "correlationId": "f7aa158a-5c58-48b5-b7c2-b59675c69dc3",
                "parentTransactionId": null,
                "paymentAttemptId": "c5a0b8fc-eace-4c82-9e00-24f232495720",
                "acquirer": {
                    "additionalResponseData": null,
                    "batch": 20230228,
                    "customData": null,
                    "date": "0228",
                    "id": "RIYADBANK_S2I",
                    "merchantId": "3000000023",
                    "settlementDate": "2023-02-28T00:00:00",
                    "time": null,
                    "timeZone": "+0300",
                    "transactionId": "123456789"
                },
                "authorizationResponse": {
                    "autoExpiry": null,
                    "avsCode": null,
                    "cardLevelIndicator": null,
                    "cardSecurityCodeError": "M",
                    "cardSecurityCodePresenceIndicator": null,
                    "commercialCard": "888",
                    "commercialCardIndicator": "3",
                    "financialNetworkCode": "777",
                    "financialNetworkDate": null,
                    "marketSpecificData": null,
                    "merchantAdviceCode": null,
                    "paySvcData": null,
                    "posData": "1025100006600",
                    "posEntryMode": "812",
                    "posEntryModeChanged": null,
                    "processingCode": "003000",
                    "responseCode": "00",
                    "date": null,
                    "responseMessage": null,
                    "returnAci": null,
                    "time": null,
                    "timeZone": null,
                    "trackQuality": null,
                    "transactionIdentifier": "123456789",
                    "transactionIntegrityClass": null,
                    "validationCode": null,
                    "vpasResponse": null
                },
                "madaDetails": null,
                "createdDate": "2023-02-28T07:33:48.0190366",
                "createdBy": "PGW",
                "updatedDate": "2023-02-28T07:33:49.3330056",
                "updatedBy": "PGW"
            },
            {
                "transactionId": "b6ca1e21-a72b-4fe6-c8e9-08db15bca2ed",
                "type": "Authentication",
                "status": "Failed",
                "amount": 123.21,
                "currency": "SAR",
                "source": "DirectAPI",
                "authorizationCode": null,
                "rrn": null,
                "stan": null,
                "paymentMethod": {
                    "type": "Card",
                    "brand": "mastercard",
                    "cardholderName": "test",
                    "maskedCardNumber": "512345******2346",
                    "wallet": null,
                    "expiryDate": {
                        "month": 1,
                        "year": 39
                    },
                    "sameBank": false,
                    "issuingCountry": null,
                    "fundingType": null,
                    "issuingBank": null,
                    "cardCategory": null
                },
                "codes": {
                    "acquirerCode": null,
                    "acquirerMessage": null,
                    "responseCode": "000",
                    "responseMessage": "Success",
                    "detailedResponseCode": "010",
                    "detailedResponseMessage": "User changed payment method"
                },
                "authenticationDetails": {
                    "acsEci": "02",
                    "authenticationToken": null,
                    "paResStatus": null,
                    "veResEnrolled": null,
                    "xid": null,
                    "accountAuthenticationValue": null,
                    "proofXml": null,
                    "threeDSecureServerTransactionId": "0e3aa75f-261f-4b17-bda2-8d0fb4e6ca55",
                    "acsTransactionId": "0fa3c8a9-a4a1-4da4-a1d9-9ab669b4b448",
                    "directoryServerId": "A999999999",
                    "dsTransactionId": "653be1d7-7350-4578-b064-97d7919da0bc",
                    "methodCompleted": false,
                    "methodSupported": "SUPPORTED",
                    "protocolVersion": "2.1.0",
                    "requestorId": "MAS00001_INT_MPGS_MTTESTENDAVA",
                    "requestorName": "Endava",
                    "transactionStatus": "Y",
                    "statusReasonCode": null
                },
                "postilionDetails": null,
                "terminalDetails": null,
                "meezaDetails": null,
                "bnplDetails": null,
                "bankInstallmentDetails": null,
                "correlationId": "5d21f723-8599-4c9e-8bde-4e3ce7e710dc",
                "parentTransactionId": null,
                "paymentAttemptId": "c5a0b8fc-eace-4c82-9e00-24f232495720",
                "acquirer": {
                    "additionalResponseData": null,
                    "batch": null,
                    "customData": null,
                    "date": null,
                    "id": null,
                    "merchantId": "3000000023",
                    "settlementDate": null,
                    "time": null,
                    "timeZone": null,
                    "transactionId": null
                },
                "authorizationResponse": {
                    "autoExpiry": null,
                    "avsCode": null,
                    "cardLevelIndicator": null,
                    "cardSecurityCodeError": null,
                    "cardSecurityCodePresenceIndicator": null,
                    "commercialCard": null,
                    "commercialCardIndicator": null,
                    "financialNetworkCode": null,
                    "financialNetworkDate": null,
                    "marketSpecificData": null,
                    "merchantAdviceCode": null,
                    "paySvcData": null,
                    "posData": null,
                    "posEntryMode": null,
                    "posEntryModeChanged": null,
                    "processingCode": null,
                    "responseCode": null,
                    "date": null,
                    "responseMessage": null,
                    "returnAci": null,
                    "time": null,
                    "timeZone": null,
                    "trackQuality": null,
                    "transactionIdentifier": null,
                    "transactionIntegrityClass": null,
                    "validationCode": null,
                    "vpasResponse": null
                },
                "madaDetails": null,
                "createdDate": "2023-02-28T07:33:12.3555742",
                "createdBy": "PGW",
                "updatedDate": "2023-02-28T07:33:49.4847948",
                "updatedBy": "PGW"
            },
            {
                "transactionId": "bb7333ee-ba04-4246-c8ed-08db15bca2ed",
                "type": "Refund",
                "status": "Success",
                "amount": 102.00,
                "currency": "SAR",
                "source": "DirectAPI",
                "authorizationCode": null,
                "rrn": "305907125202",
                "stan": "124112",
                "paymentMethod": {
                    "type": "Card",
                    "brand": "mastercard",
                    "cardholderName": "test",
                    "maskedCardNumber": "512345******2346",
                    "wallet": null,
                    "expiryDate": {
                        "month": 1,
                        "year": 39
                    },
                    "sameBank": false,
                    "issuingCountry": null,
                    "fundingType": null,
                    "issuingBank": null,
                    "cardCategory": null
                },
                "codes": {
                    "acquirerCode": "00",
                    "acquirerMessage": null,
                    "responseCode": "000",
                    "responseMessage": "Success",
                    "detailedResponseCode": "000",
                    "detailedResponseMessage": "The operation was successful"
                },
                "authenticationDetails": null,
                "postilionDetails": null,
                "terminalDetails": null,
                "meezaDetails": null,
                "bnplDetails": null,
                "bankInstallmentDetails": null,
                "correlationId": "67f43afa-1fc8-4cad-8251-dc64a2c01bbe",
                "parentTransactionId": "7862b7d2-83be-4964-73ae-08db103ef15a",
                "paymentAttemptId": null,
                "acquirer": {
                    "additionalResponseData": null,
                    "batch": 20230228,
                    "customData": null,
                    "date": "0228",
                    "id": "RIYADBANK_S2I",
                    "merchantId": "3000000023",
                    "settlementDate": "2023-02-28T00:00:00",
                    "time": null,
                    "timeZone": "+0300",
                    "transactionId": "123456789"
                },
                "authorizationResponse": {
                    "autoExpiry": null,
                    "avsCode": null,
                    "cardLevelIndicator": null,
                    "cardSecurityCodeError": "M",
                    "cardSecurityCodePresenceIndicator": null,
                    "commercialCard": "888",
                    "commercialCardIndicator": "3",
                    "financialNetworkCode": "777",
                    "financialNetworkDate": null,
                    "marketSpecificData": null,
                    "merchantAdviceCode": null,
                    "paySvcData": null,
                    "posData": "1025100006600",
                    "posEntryMode": "812",
                    "posEntryModeChanged": null,
                    "processingCode": "203000",
                    "responseCode": "00",
                    "date": null,
                    "responseMessage": null,
                    "returnAci": null,
                    "time": null,
                    "timeZone": null,
                    "trackQuality": null,
                    "transactionIdentifier": "123456789",
                    "transactionIntegrityClass": null,
                    "validationCode": null,
                    "vpasResponse": null
                },
                "madaDetails": null,
                "createdDate": "2023-02-28T07:34:21.1632596",
                "createdBy": "PGW",
                "updatedDate": "2023-02-28T07:34:21.7952972Z",
                "updatedBy": "PGW"
            }
        ],
        "orderItems": [],
        "isTokenPayment": false,
        "paymentMethod": {
            "type": "Card",
            "brand": "mastercard",
            "cardholderName": "test",
            "maskedCardNumber": "512345******2346",
            "wallet": null,
            "expiryDate": {
                "month": 1,
                "year": 39
            },
            "sameBank": false,
            "issuingCountry": null,
            "fundingType": null,
            "issuingBank": null,
            "cardCategory": null
        },
        "totalAuthorizedAmount": 123.21,
        "totalCapturedAmount": 123.21,
        "totalRefundedAmount": 102.00,
        "orderSource": "GeideaGateway",
        "paymentBrands": [
            "mastercard"
        ],
        "multiCurrency": {
            "authCurrency": "SAR",
            "authAmount": 123.21,
            "settleCurrency": "SAR",
            "settleAmount": 123.21,
            "exchangeRate": null,
            "exchangeFeePercentage": null,
            "exchangeFeeAmount": null
        },
        "isTest": true,
        "cashOnDelivery": false,
        "amountToCollect": null,
        "isDownPayment": false,
        "exchangeRate": null,
        "exchangeFeePercentage": null,
        "exchangeFeeAmount": null,
        "deviceId": "14b90417-2522-4479-4b5b-08da6a10e762",
        "gatewayDecision": "ContinueToPay",
        "subscriptionId": null,
        "subscriptionOccurrenceId": null,
        "customerPhoneNumber": null,
        "customerPhoneCountryCode": null,
        "createdDate": "2023-02-28T07:33:12.3555742",
        "createdBy": "PGW",
        "updatedDate": "2023-02-28T07:33:49.3330056",
        "updatedBy": "PGW"
    },
    "responseMessage": "Success",
    "detailedResponseMessage": "The operation was successful",
    "language": "en",
    "responseCode": "000",
    "detailedResponseCode": "000"
}

Frequently Asked Questions (FAQ)

👍

How long does it take for customers to receive the refund amount?
Your customers will receive the amount in their account, according to the time set by their bank and country regulations. It usually takes anywhere between 3 to 7 days.

What transactions can be refunded?

Any transaction whose order status is either Captured or Paid.

The transaction must not have been fully refunded.

The transaction must not have exceeded the allowed expiry days for the refund.

Can I refund the amount to another card?

No, a refund can only be made to the card from which the transaction has originated.

The customer card's issuer has the capability to handle the refund made to an expired or cancelled card by crediting this amount to a replacement card.