Refund Mandate

Refund Mandate API

Purpose : This API is used to refund a specific transaction that was previously debited under a mandate. It supports both Full Refunds and Partial Refunds.

Environment details:

Staging Server: https://zaakstaging.zaakpay.com
Live Server: https://api.zaakpay.com

Request Type : Post

Endpoint : /api/v2/updateTransaction

Request Attributes

These are the Request Attributes of Refund Mandate API

Fields	DataType	Mandatory	Description
merchantIdentifier	String	Y	Zaakpay’s unique alphanumeric merchant identifier. You can get it from Zaakpay dashboard.
orderId	String	Y	It is a unique mandate transaction order identifier for merchant.
Mode	String	Y	1 digit only, numeric, Allowed value is 0.
updateDesired	String	Y	Code indicating the type of refund: • 14 : Full Refund • 22 : Partial Refund
updateReason	String	Y	Description of the reason for update. min 5, max 30 alphanumeric characters. no special characters or dashes.
Amount	String	Y - In case of Partial-Refund	Refund Amount, which needs to be refunded in case of partial refunds. In case of full refund this can be omitted. For E.g. Rs 1 is 100 paisa, Rs 777.50 is 77750 paisa.
merchantRefId	String	N	Unique refund transaction id sent by merchant.
Checksum	String	Y	Checksum Calculated on all above request parameters.

Response Attributes

These are the Response Attributes of the Refund Mandate API.

Refund Response Attributes

Fields	Description
merchantIdentifier	Zaakpay’s unique alphanumeric merchant identifier.
orderId	Unique transaction identifier for the order.
responseCode	Zaakpay’s response code for the refund.
responseDescription	Description of the refund response code.
merchantRefId	Merchant's reference ID for tracking the refund.

Sample Request

For reference, below are the sample CURL request of API . It takes all required attributes to hit the Refund Mandate API.

cURL Request

We have created a sample request of Refund Mandate API with all required attributes and their values, in the order in which they’ll be sent to the API.

The resulting checksum calculated should be posted to the Zaakpay API along with other required attributes.

curl --location 'https://zaakstaging.zaakpay.com/updateTxn' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: JSESSIONID=3253388BCF7BF29453346258402DBC3E; JSESSIONID=DCAA163F07B1059473CF320670097D62; JSESSIONID=FB68D3733DE355D732259D5D18101B9E; JSESSIONID=B0F7B5A19FD5501E3F7073E86154550E.163.156' \
--data-urlencode 'data={"merchantIdentifier":"fbXXXXXXXXXXXXXXXXXXXX71a4","orderDetail":{"orderId":"ZPLXXXXXXXX2375","productDescription":"Refund Mandate"},"mode":"0","updateDesired":"14","updateReason":"Refund","merchantRefId":"TXXXXXXXX3"}' \
--data-urlencode 'checksum=5d8d79XXXXX23a13e5dd3dXXXXX93b4f0fca4f569'

Sample Request

{
  "merchantIdentifier": "fbXXXXXXXXXXXXXXXX71a4",   // MID
  "orderDetail": {
    "orderId": "ZPLXXXXXXXX2375",   // MandateTransactionOrderId
    "productDescription": "Refund Mandate"
  },
  "mode": "0",
  "updateDesired": "14",
  "updateReason": "Refund",
  "merchantRefId": "TXXXXXXXX3"
}

Sample Response

{
    "merchantIdentifier": "fbXXXXXXXXXXXXXXXX71a4",
    "orderDetail": {
        "orderId": "ZPLXXXXXXXX2375"
    },
    "responseCode": "230",
    "responseDescription": "Transaction Refund Initiated",
    "merchantRefId": "TXXXXXXXX3"
}

{
    "merchantIdentifier": "fbXXXXXXXXXXXXXXXX71a4",
    "orderDetail": {
        "orderId": "ZPLXXXXXXXX2375"
    },
    "responseCode": "180",
    "responseDescription": "Checksum received with request is not equal to what we calculated.",
    "merchantRefId": "REFXXXXXXXXX224;
}

Checksum Calculation

Create a string(JSON) using the request attributes as given below. Checksum string will create based on the request attributes which are posted to Zaakpay as same as given in the string below.

Now, Calculate the checksum using the HMAC SHA-256 algorithm using the string as data and your generated secret key. The resulting checksum calculated should be posted to the Zaakpay API along with other data.

The Checksum string will be:

Secret Key used: 0678056d96914a8583fb518caf42828a

{"merchantIdentifier":"fbXXXXXXXXXXXXXXXXXXXX71a4","orderDetail":{"orderId":"ZPLXXXXXXXX2375","productDescription":"Refund Mandate"},"mode":"0","updateDesired":"14","updateReason":"Refund","merchantRefId":"TXXXXXXXX3"}

5d8d79fed472ad1e8123a13e5dd3d84b8865b4fff319facdbe93b4f0fca4f569