get https://sandbox.juspay.in/customers//mandates
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)
| Parameter | Type | Description |
|---|---|---|
| objectwwwtww | String | "list" |
| list: [{...},{...},..] | Array | An array of Mandate Objects (see table below) |
| total | Int | Total mandates set against customer_id |
| offset | Int | Offset from start (default is 0) |
| count | Int | Count 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)
(click to view)
Note:
Mandate Object includes two extra parameters in this instance:
mandate_debit_token and description| Field | Type | Description |
|---|---|---|
| status | String | Current 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:
| Field | Type | Description |
|---|---|---|
| payment_method_type | String | Payment method type used when creating the mandate. Must be either CARD, NB, WALLET, or UPI. |
| payment_method | String | Payment method used when creating the mandate. Found in the given tables for the corresponding Payment API and transaction type. |
| auth-type | String | Type 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:
| Field | Type | Description |
|---|---|---|
| payer_vpa | String | Payer 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:
| Field | Type | Description |
|---|---|---|
| using_saved_card | Boolean | True if using a saved card |
| saved_to_locker | Boolean | True if card has been saved to locker |
| last_four_digits | String | Last four digits of card number |
| name_on_card | String | Card holder name. Should contain alphabetical characters only. |
| expiry_year | String | Expiry year of the card (Format: "yyyy") |
| expiry_month | String | Expiry month of the card (Format: "mm") |
| card_type | String | "CREDIT" or "DEBIT" |
| card_issuer | String | Code for bank that issued the card (Example: "HDFC Bank") |
| card_isin | String | International Securities Identification Number for card (Example: "545721") |
| card_brand | String | Brand 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:
| Field | Type | Description |
|---|---|---|
| object | String | "bank_account" |
| id | String | Bank account ID generated by Juspay |
| customer_id | String | Customer ID sent in request. (Customer ID is provided by juspay or is the object reference ID given by merchant during customer creation.) |
| date_created | String | Date that account was created |
| bank_name | String | **Name of bank |
| account_number | String | Bank account number |
| beneficiary_name | String | Name of the customer in a given bank account |
| ifsc | String | IFSC code for a bank branch |
| validation_amount | String | Amount that account is validated for |
| currency | String | Type of currency |
| validation_status | String | Status of account (CREATED, PENDING, or ACTIVE) |
| last_validated | String | Time/date of most recent validation |
| metadata: {param1, param2, ....} | String | Custom key-value sets sent in previous request |
NOTE:
Only those parameters in bold were shown in the response for this API.
| mandate_id | String | Mandate 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_token | String | One time token for recurring mandate execution. Allows a charge without a 2nd factor. | ||||||
| mandate_token | String | Mandate 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_amountwwwwwi | String | Maximum amount of mandate set while creating a mandate. Mandatory only if mandate.amount_rule = VARIABLE. | ||||||
| currency | String | ISO string of the currency. Default value: INR (Indian Rupee). Among other accepted values are EUR, USD, GBP. | ||||||
| activated_at | String | Time stamp of mandate activation | ||||||
| start_date | String | Mandate 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_date | String | Mandate 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_rule | String | Data 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-- | String | EMANDATE in case of UPI/NB/Wallet payment MANDATE in case of Card payment | ||||||
| revokable_by_customer | Boolean | If 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_fund | Boolean | Set 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. | ||||||
| frequency | String | Defines the frequency of mandate execution, or how often a customer should be charged.Description for mandate.frequencyPossible values (ENUM format):ONETIME, DAILY, WEEKLY, FORTNIGHTLY, MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTEDDefault: ASPRESENTEDCheck below for additional rules on this value. | ||||||
| rule_type | String | ON / BEFORE / AFTER For Razorpay, rule_type will be updated to BEFORE. For Paytm, rule_type will be updated to AFTER | ||||||
| rule_value | Integer | Determines the day of week or month that a mandate will be executed, depending on the mandate.frequency.Description for rule.valuePossible values (Integer format):
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. | ||||||
| description | String | Short description for the order such as product name, plan name. |
Mandate Status Mapping - Mandate status codes and meaning:
| Status | Description |
|---|---|
| CREATED | Mandate has been created, but awaiting status from PG. |
| ACTIVE | When 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). |
| PAUSED | Customer has an option to pause the mandate. Status changes to PAUSED when customer exercises this option. |
| REVOKED | Mandate is revoked by either the customer or the merchant. Revoked is a terminal state, once Revoked, the status cannot be changed. |
| FAILURE | Mandate creation was unsuccessful. This is a terminal state, the merchant has to create a new mandate if failed. |
| EXPIRED | Mandate 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 thefirst 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 mandateshould 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, thenthe mandate will execute on the 30th.
3. If the mandate start date is 29th January and the value is ‘17’, then thefirst debit will be on 17th February.