Refund API

This API allows merchants to initiate refunds for previously successful transactions processed through Zaakpay. It supports full or partial refunds and returns standardized response codes along with status details.

REFUND API

Purpose : This API can be used to initiate refunds on a transaction.

Request Type : POST

Endpoint : /api/payments/v1/refund

Request Attributes

These are the Request Attributes of Refund API

FIELD	DataType	Mandatory	DESCRIPTION
merchantIdentifier	String	Y	Unique identifier of Zaakpay
orderId	String	Y	Merchant’s order Id
refundType	String	Y	Possible Values : F - Full refund P - Partial refund
refundAmount	String	Y	Refund amount in paisa
merchantRefundId	String	Y	Merchant generated unique refund id for every refund request

Response Attributes

These are the Response Attributes of Refund API.

Field	Type	Description
status	Boolean	Indicates the overall result of the API request. true if the refund was processed successfully, false if an error occurred.
message	Object	Contains response code and description.
data	Object	Contains transaction-related information (if applicable).

Checksum Calculation

Calculate the checksum using the HMAC SHA-256 algorithm using the data json as string and your generated secret key.

Sample Request and Response

For reference, below are the sample cURL Request and Response of API . It takes all required attributes to initiate a Refund of transaction.

cURL

curl -X POST https://api.zaakpay.com/api/payments/v1/refund \
-H "Content-Type: application/json" \
-H "checksum: <calculated-checksum-here>" \
-d '{
  "merchantIdentifier": "03efXXXXXXXXXXXXXXXXX060c35f",
  "merchantRefundId": "REFXXXXXXX33b",
  "orderId": "ORDER98765",
  "refundType": "F",
  "refundAmount": 5000
}'

Sample Request

{
  "merchantIdentifier": "03efXXXXXXXXXXXXXXXXX060c35f",
  "orderId": "ORDER98765",
  "refundType": "F",
  "refundAmount": 5000,
  "merchantRefundId": "REFXXXXXXX33b"
}

Sample Response

{
  "status": true,
  "message": {
    "code": 100,
    "text": "The transaction was completed successfully."
  },
  "data": {
    "merchantIdentifier": "03efXXXXXXXXXXXXXXXXX060c35f",
    "merchantRefundId": "REFXXXXXXX33b",
    "refundAmount": "5000",
    "refundStatus": "PENDING"
  }
}

{
  "status": false,
  "message": {
    "code": 216,
    "text": "Order Id not found."
  },
  "data": {}
}

Refund API Response codes

Code	Text	Refund Status	Retry
100	The transaction was completed successfully.	PENDING	N
110	MerchantIdentifier field missing or blank.		Y
111	MerchantIdentifier not valid.		Y
129	OrderId field missing or blank.		Y
160	Transaction amount validation has failed.		Y
180	Checksum received with request is not equal to what we calculated		Y
190	OrderId either not processed or rejected.		Y
200	Transaction already refunded.		Y
216	Order Id not found.		Y
801	Merchant reference ID was not valid.		Y
802	Refund for this unique merchant refund id already processed		Y
1036	Something went wrong		Y ( Retry with same merchantRefundId to check if it exists or not)
1049	Refund type in request is not valid		Y
4001	Refund amount not valid with the provided refund type		Y