Hey! These docs are for version 3.2, which is no longer officially supported. Click here for the latest version, 1.0!

List Mandate API

A merchant can call this API to get the list of all the mandates that a customer has with them. The list will also include all revoked, expired, and failed mandates.

  Response Parameters for the List Mandate API:         (click to view)
ParameterTypeDescription
objectwwwtwwString"list"
list: [{...},{...},..]ArrayAn array of Mandate Objects     (see table below)
totalIntTotal mandates set against customer_id
offsetIntOffset from start (default is 0)
countIntCount of mandate objects to be included in response
Default is same as total
Mandate Objects:  The elements returned in the list array are Mandate Objects, each of which includes a Payment Info Object. This provides details of all mandates a customer has (or had) with a merchant.
(click to view)
Note:
Mandate Object includes two extra parameters in this instance: mandate_debit_token and description
FieldTypeDescription
statusStringCurrent status of the mandate. Must be one of the states listed below.
ENUM format:
/ CREATED / ACTIVE / PAUSED / REVOKED / FAILURE / EXPIRED /
payment_info:wwwwwi
   {param1, param2,...}
Object
nStringn
This contains the payment instrument details entered when the mandate was created
(Parameters listed in table below - click to open)
  Payment Info Object Parameters:
FieldTypeDescription
payment_method_typeStringPayment method type used when creating the mandate. Must be either CARD, NB, WALLET, or UPI.
payment_methodStringPayment method used when creating the mandate. Found in the given tables for the corresponding Payment API and transaction type.
auth-typeStringType of authentication used. This parameter is returned only with the "Card" and "NB" response".
upi_details:wwwwwwi
      {payer_vpa}
Object
String
UPI details related to customer.
Currently just one parameter:
payer_vpa
    UPI Details Object Parameter:
FieldTypeDescription
payer_vpaStringPayer VPA used during setting up mandate.
card:wwwwwwwwwiww
    {param1, param2,...}
Object
String
Card details. This parameter is included as shown in the "Card" response".
    Card Object Parameters:
FieldTypeDescription
using_saved_cardBooleanTrue if using a saved card
saved_to_lockerBooleanTrue if card has been saved to locker
last_four_digitsStringLast four digits of card number
name_on_cardStringCard holder name. Should contain alphabetical characters only.
expiry_yearStringExpiry year of the card (Format: "yyyy")
expiry_monthStringExpiry month of the card (Format: "mm")
card_typeString"CREDIT" or "DEBIT"
card_issuerStringCode for bank that issued the card
(Example: "HDFC Bank")
card_isinStringInternational Securities Identification Number for card    (Example: "545721")
card_brandStringBrand of card ("MASTERCARD", "VISA", etc.)
bank_details:wwwnwww
      {param1, param2,...}
Object
String
This block will be available for only NB / CARD and mandate_type = EMANDATE mandate flows.
    Bank Details Object Parameters:
FieldTypeDescription
objectString"bank_account"
idStringBank account ID generated by Juspay
customer_idStringCustomer ID sent in request. (Customer ID is provided by juspay or is the object reference ID given by merchant during customer creation.)
date_createdStringDate that account was created
bank_nameString**Name of bank
account_numberStringBank account number
beneficiary_nameStringName of the customer in a given bank account
ifscStringIFSC code for a bank branch
validation_amountStringAmount that account is validated for
currencyStringType of currency
validation_statusStringStatus of account (CREATED, PENDING, or ACTIVE)
last_validatedStringTime/date of most recent validation
metadata:
   {param1, param2, ....}
StringCustom key-value sets sent in previous request
NOTE:
Only those parameters in bold were shown in the response for this API.
mandate_idStringMandate ID is a unique identifier generated and sent by Juspay after mandate creation. Must be sent with the Mandate Execution, Notification, and Revoke Mandate APIs.
mandate_debit_tokenStringOne time token for recurring mandate execution. Allows a charge without a 2nd factor.
mandate_tokenStringMandate token is a unique identifier generated and sent by Juspay after mandate creation for one-time use. Allows a charge without a 2nd factor.
max_amountwwwwwiStringMaximum amount of mandate set while creating a mandate. Mandatory only if mandate.amount_rule = VARIABLE.
currencyStringISO string of the currency. Default value: INR (Indian Rupee). Among other accepted values are EUR, USD, GBP.
activated_atStringTime stamp of mandate activation
start_dateStringMandate start date in UNIX EPOCH timestamp (UTC timezone) format. In case of UPI mandate, the start date has to be today’s date. Mandatory only for UPI Mandate
end_dateStringMandate end date in UNIX EPOCH timestamp (UTC timezone) format, when a mandate will move to EXPIRED state, and recurring mandate execution will not be allowed. Mandatory only for UPI Mandate.
amount_ruleStringData type ENUM
Possible values: FIXED, VARIABLE.
By Default, it is considered as VARIABLE.
In case of FIXED, max amount will be equal to amount
mandate_type--StringEMANDATE in case of UPI/NB/Wallet payment
MANDATE in case of Card payment
revokable_by_customerBooleanIf FALSE, the mandate cannot be revoked by the customer once set. It should be TRUE for Recurring and TRUE/FALSE for ONETIME. By default, value will be TRUE
block_fundBooleanSet to TRUE if funds have to be blocked while a mandate is being created. Should be TRUE for ONETIME and FALSE for Recurring. By default, value will be TRUE for ONETIME and FALSE for Recurring.
frequencyStringDefines the frequency of mandate execution, or how often a customer should be charged.
 Description for mandate.frequency
Possible values (ENUM format):
ONETIME, DAILY, WEEKLY, FORTNIGHTLY, MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
Default:     ASPRESENTED
Check below for additional rules on this value.
rule_typeStringON / BEFORE / AFTER
For Razorpay, rule_type will be updated to BEFORE.
For Paytm, rule_type will be updated to AFTER
rule_valueIntegerDetermines the day of week or month that a mandate will be executed, depending on the mandate.frequency.
 Description for rule.value
Possible values (Integer format):
1-7when frequency is WEEKLY. In weekly, serial numbers start from Monday. Monday represents 1 and Sunday represents 7.
1-16when frequency is FORTNIGHTLY. This mandate is executed twice a month. First day of the month is represented by value ‘1’ and ends with ‘15’ on 15th day of the month. Then again starts with ‘1’ for 16th of the month and ends with the last day of the month.
1-31when frequency is MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, orYEARLY.
Not required when frequency is ONETIME, DAILY, or ASPRESENTED. For Razorpay, rule_value will be considered as the last date of the week/month/year. For Paytm, rule_value will be considered as today’s date/day.
Check below for additional rules on this value.
descriptionStringShort description for the order such as product name, plan name.
  Mandate Status Mapping   - Mandate status codes and meaning:
StatusDescription
CREATEDMandate has been created, but awaiting status from PG.
ACTIVEWhen PG accepts the chosen mode of payment, the mandate is set to the active state. The state remains ACTIVE (except when PAUSED temporarily) until terminated (either when mandate expires or customer/merchant decides to revoke the mandate).
PAUSEDCustomer has an option to pause the mandate. Status changes to PAUSED when customer exercises this option.
REVOKEDMandate is revoked by either the customer or the merchant. Revoked is a terminal state, once Revoked, the status cannot be changed.
FAILUREMandate creation was unsuccessful. This is a terminal state, the merchant has to create a new mandate if failed.
EXPIREDMandate validity has expired. This is a terminal state.
Special considerations for certain values of the mandate.rule_value / mandate.frequency parameters:         (click to view)
Calculating the day of mandate exectution for certain values of mandate.rule_value when mandate.frequency is set to 'FORTNIGHTLY' or 'MONTHLY'.
mandate.frequency = FORTNIGHTLY:
1. If the value is ‘14’, ‘15’, or ‘16’, and falls on the latter half of February
(16th to 28th), then the mandate shall execute on the last day of
February.
2. If the mandate start date is 24th January 2018 with value ‘16’, then the
first debit will be on 31st January, followed by 15th February, 28th
February,15th March, 31st March, and so on.
3. If the value is ‘16’, and the month has only 30 days, then the mandate
should execute on 30th.
4. If the mandate start date is 29th January, and the value is ‘4’,
then the first debit will be on 4th February, followed by 19th February,
4th March, and so on.

mandate.frequency = MONTHLY:
1. If the value is ‘29’, ‘30’, or ‘31’, and falls in February, then the mandate
shall execute on the last day of February.
2. If the value is ‘31’, and the next executable month has 30 days, then
the mandate will execute on the 30th.
3. If the mandate start date is 29th January and the value is ‘17’, then the
first debit will be on 17th February.
Language
Authentication
Basic
base64
:
Click Try It! to start a request and see the response here!