Partial Refund

The Partial Refund API allows merchants to refund a portion of the amount of a previously successful and settled transaction through the EdfaPay payment gateway. This enables returning a specified partial amount back to the customer’s original payment method, while the remaining transaction amount stays captured.

Endpoint

POST https://apidev.edfapay.com/payment/refund

Content-Type: application/json

Request Body

Field	Type	Required	Description
gwayId	string	Yes	Unique transaction ID returned by Edfapay (payment gateway transaction ID)
order_id	string	Yes	Order ID from the merchant's system
edfa_merchant_id	string	Yes	Merchant key provided by Edfapay
hash	string	Yes	Security hash generated to authorize the request
payer_ip	string	Yes	IP address of the payer in IPv4 format.
amount	string	Yes	The partial amount of the original transaction

Example Request

curl --location 'https://apidev.edfapay.com/payment/refund' \
--header 'Content-Type: application/json' \
--data '{
    "gwayId": "12345678", 
    // The original transaction ID of the sale
    "order_id": "1000", 
    // The original order ID of the sale
    "edfa_merchant_id": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "hash": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "payer_ip": "176.44.76.222",
    "amount": "1.00"
}'

curl --location 'https://apidev.edfapay.com/payment/refund' \
--header 'Content-Type: application/json' \
--data '{
    "gwayId": "12345678", 
    // The original transaction ID of the sale
    "order_id": "1000", 
    // The original order ID of the sale
    "edfa_merchant_id": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "hash": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "payer_ip": "176.44.76.222",
    "amount": "2.00"
}'

curl --location 'https://apidev.edfapay.com/payment/refund' \
--header 'Content-Type: application/json' \
--data '{
    "gwayId": "12345678", 
    // The original transaction ID of the sale
    "order_id": "1000", 
    // The original order ID of the sale
    "edfa_merchant_id": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "hash": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "payer_ip": "176.44.76.222",
    "amount": "3.00"
}'

curl --location 'https://apidev.edfapay.com/payment/refund' \
--header 'Content-Type: application/json' \
--data '{
    "gwayId": "12345678", 
    // The original transaction ID of the sale
    "order_id": "1000", 
    // The original order ID of the sale
    "edfa_merchant_id": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "hash": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "payer_ip": "176.44.76.222",
    "amount": "4.00"
}'

❗️
Important Note — Hash Generation
The hash parameter included in the request body is dynamically generated for each request and must not be hardcoded.
The hash value is calculated using specific request parameters combined with your merchant secret key. Any change in the request data requires regenerating the hash before sending the request.
🔗 For detailed steps and the exact formula used to generate the hash, refer to the Hash Generation Section.

Hash Calculation

To secure the API call from unauthorized access, the hash parameter must be computed using the following formula:

Formula:

hash = SHA1(MD5(UPPERCASE(gwayId+ amount+ merchant_password)))

JavaScript Example using CryptoJS

var to_md5 = gwayId + amount + merchant.pass;

var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());

var result = CryptoJS.enc.Hex.stringify(hash);

Note

merchant.pass is the shared secret provided by Edfapay for secure communication.

You can obtain the gwayId from the Dashboard on the Transaction page, where it appears as Payment ID.

Alternatively, it can be retrieved from the Webhook (callback) response using the trans_id parameter.

Success Response

{
    "statusCode": 200,
    "responseBody": {
        "result": "accepted",
        "payment_id": "XXXXXXXXXXXXXXXXXXX"
    }
}

Each transaction has its own unique payment_id; however, for partial refunds, all refund operations must be performed under the same order_id of the original sale transaction.

Error Response

{
    "statusCode": 400,
    "responseBody": {
        "message": "Refund is already initiated."
    }
}

Partial Refund Rules and Guidelines

Refund Eligibility

A partial refund can only be initiated if the original transaction was successful and captured.

Partial Refund Conditions

The refund amount must be less than the original transaction amount.
Multiple partial refunds are allowed on the same transaction.
The total refunded amount must not exceed the original transaction amount.
Each partial refund request must include a valid refund amount.

❗️
Important Considerations

Partial refunds should be processed carefully, as multiple refund attempts may increase the risk score and could trigger issuer or fraud monitoring checks.

Always ensure that the remaining amount after partial refunds is calculated correctly.

Verify that the transaction is captured before initiating any partial refund.

Track and log each partial refund attempt to avoid duplicate or conflicting refunds.

The total amount of multiple partial refunds must not exceed the total amount of the original capture transaction.