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://api.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://api.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"
}'

❗️
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.

Response Example

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

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

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.

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.
The total refunded amount must not exceed the original transaction amount.
Each partial refund request must include a valid refund amount.

❗️
Important Considerations

Always ensure the remaining refundable amount is calculated correctly before submitting a partial refund.

Ensure each partial refund is properly logged and tracked to avoid conflicts or duplicate refund attempts.

Always verify that the transaction is captured before initiating a partial refund.

Only one refund is allowed per transaction. Once a refund is initiated, additional refund attempts for the same transaction are not permitted.