Mandate Subscription API

The Mandate Subscription API allows merchants to create a subscription (active mandate instance) for a specific customer and order. The subscription can reference an existing plan (using planId) or define a new plan inline within the request body. This API ties a mandate plan to a specific order, defines the billing start parameters, and initiates the mandate registration process

Request Type : POST
Endpoint : /payments/mandate/subscription

Request Attributes

These are the request attributes of the Subscription API

Fields	Datatype	Mandatory	Description
planDetails	Object	Y	Contains the mandate plan information. Can reference an existing plan using planId or define a new plan inline by providing name, frequency, amount, and description. When planId is provided, it takes priority and other plan fields are ignored.
orderId	String	Y	A unique order identifier generated by the merchant. Used to track and associate this subscription with a specific transaction. Example: "ORDERID_123". Must be unique per subscription request.
firstDebitAmount	Number	Y	The amount to be charged for the first debit transaction. This can differ from the plan's recurring amount (e.g., a discounted first payment or a penny drop amount). Must be a positive number greater than 0. Example: 100.
isPennyDrop	Boolean	Y	Indicates whether the first transaction should be a penny drop (small verification debit) to validate the customer's bank account. Set to true to enable penny drop verification, false to skip it. Example: false.
debitDay	Number	Y	The day of the billing cycle on which the recurring debit should occur. For Monthly frequency, this represents the day of the month (1–28). For other frequencies, this defines the recurring trigger day. Example: 15 (debit on the 15th of each month).
endDate	String	Y	The expiry date of the mandate subscription. After this date, no further debits will be initiated. Format: YYYY-MM-DD. Example: "2026-03-19". Must be a future date.

Response Attributes

These are the response Attributes of the Subscription API

Fields	Datatype	Description
Success	Boolean	Indicates the overall status of the API request. true if the request was processed successfully, false if an error occurred.
data	object	Contains the detailed response payload.

Checksum Calculation

Create a concatenated string using the request parameters as given below. Checksum string will create based on the request parameters which are posted to Zaakpay in the same order as given in below string.
Now, Calculate the checksum using the HMAC SHA-256 algorithm using the string as data and your generated secret key.

{"planDetails":{"planId":"PLAN_XXXXXXXX894"},"orderId":"ORDERID_123","firstDebitAmount":
100,"isPennyDrop":false,"debitDay":15,"endDate":"2026-03-19"}

Sample Request & Response

For reference, below are the sample CURL request and Response of API . It takes all required attributes to initiate a Mandate Subscription.

cURL

curl --location 'https://zaakstaging.zaakpay.com/api/payments/mandate/subscription' \
--header 'checksum: 1e07XXXXXXXXXc767d0607a4678bXXXXXXXXXad9c45cd039447' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: e27c6XXXXXXXXXXX93319242e' \
--data '{
  "planDetails": {
    "planId": "PLAN_XXXXXXX8894",
    "name": "",
    "frequency": "Monthly",
    "amount": -1,
    "description": ""
  },
  "orderId": "ORDERID_123",
  "firstDebitAmount": 100,
  "isPennyDrop": false,
  "debitDay": 15,
  "endDate": "2026-03-19"
}
'

Sample Request

{
  "planDetails": {
    "planId": "PLAN_XXXXXXXX8894", // priority will be for planid , just this field required when plan is already created
    "name": "",
    "frequency": "Monthly",
    "amount": -1,
    "description": ""
  },
  "orderId": "ORDERID_123",
  "firstDebitAmount": 100,
  "isPennyDrop": false,
  "debitDay": 15,
  "endDate": "2026-03-19"
}

Sample Response

{
    "success": true,
    "data": {
        "planId": "PLAN_XXXXXXXX697",
        "subscriptionId": "SUB_XXXXXXX2547",
        "responseCode": "1201",
        "responseDescription": "Mandate subscription created successfully"
    }
}

{
    "success": false,
    "data": {
        "responseCode": "180",
        "responseDescription": "Checksum received with request is not equal to what we calculated."
    }
}