For some purchases, customers have the option to make payments that are either one time or recurring in nature, for e.g. utility bills payment, insurance premium etc. If the recurring method is chosen, a mandate can be created that includes mechanisms for billing frequency, pre-notifications, start/end date, rules for debit amount, pause, revoke, modify, etc. Mandates can be initiated by either the payer or payee. If initiated by payee, payer has the option of approving or rejecting the mandate request. Once a mandate is created, it will allow the user’s account to be debited as per the agreed terms and conditions, without requiring the user to authenticate the transaction every time.
The following Mandate APIs will handle all mandate-related interactions and transactions on the Juspay server. These APIs are similar to Order APIs, except that a Mandate Object is included that contains a Mandate ID, and rules for debit amount , frequency, etc.
Flow diagrams for Mandate APIs:
Brief description of each Mandate API:
Order:

Order Status:

Registration:


Status:

Execution:
mandate_id, merchant_id, format
notification_id,
display_invoice_number, execution_date
)


mandate_id, command = "pause", merchant_id
pause_start_date, pause_end_date

mandate_id, command = "resume", merchant_id
resume_date

Request Parameters for Mandate APIs
Field | Type | * | Description |
---|---|---|---|
order_id | String |
* |
Required only for the Get Mandate Order Status API. - Unique Identifier for the order. |
mandate_id | String |
* |
Required only for the Notification API, and the Revoke, Pause, and Resume Mandate APIs. - The Mandate ID sent by Juspay after mandate creation. Mandate ID will be available in the mandate JSON block of Get Mandate Order Status API response. |
customer_id | String |
* |
Required only for the List Mandate API. - Unique ID for a customer. |
object_reference_id | String |
* |
Required only for the Notification Status API. - This is the merchant's unique Identifier for the notification request, and is available in the response body of the Notification API. |
Field | Type | * | Description |
---|---|---|---|
x-merchantid | String |
* |
Required only for the Create Mandate Order, Get Mandate Order Status, Revoke Mandate, Pause Mandate, and Resume Mandate APIs. - Merchant ID which would have been issued while registering with Juspay |
Mandate Object Parameters:- Used only for the Create Mandate Order API.
Field | Type | Description | |||||||
---|---|---|---|---|---|---|---|---|---|
max_amount | * | String | Maximum amount for a mandate. Mandatory only if mandate.amount_rule = VARIABLE. | ||||||
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 | |||||||
start_date | * | String | Mandate start date in UNIX EPOCH timestamp (UTC timezone). 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), from when a mandate will move to EXPIRED state and recurring mandate will not be allowed. Mandatory only for UPI Mandate. | ||||||
block_funds | 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 here for additional rules on this value. | |||||||
rule_value | String | 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 here 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 |
revokable_by_customer | Boolean | If FALSE, the mandate cannot be revoked by the customer once set. Applicable only for UPI mandate. It should be TRUE for Recurring and TRUE/FALSE for ONETIME. By default, value will be TRUE |
Metadata Object Parameters:- Used only for the Create Mandate Order API.
Field | Type | Description | |
---|---|---|---|
bank_account_number | w | String | Bank account number of VPA used. Used only if downstream supports third party validation. |
bank_ifsc | String | IFSC code for a given bank. | |
PAYTM_V2: SUBSCRIPTION_GRACE_DAYS | String | Number of days after renewal cycle start date for which merchant can send renewal request. By default 0 for DAILY and ASPRESENTED and 7 for remaining frequencies. | |
PAYTM_V2: SUBSCRIPTION_RETRY_COUNT | String | Applicable only for Paytm. By default 2 for UPI mandate. | |
PAYTM_V2: GATEWAY_REFERENCE_ID | String | Customized PAYTM_V2 parameter for the payment aggregators. This was found in request, but not in parameter list. |
Options Object Parameter:- Used only for the Create Mandate Order API.
Field | Type | Description | |
---|---|---|---|
create_mandate | * | String | Merchants who want to set up mandates can pass this as either “REQUIRED” or “OPTIONAL”. “REQUIRED” means that the transaction for this order has to be definitely converted to a mandate. “OPTIONAL” means that the final decision of conversion of the transaction lies at the /txns api call with the flag “should_create_mandate” |
Source Info Object Parameters:- Used only for the Notification API.
Field | Type | Description | |
---|---|---|---|
amount | * | String | Amount for which notification is to be sent to customer I.e. "100.00" |
txn_date | * | String | Date on which debit is intended to happen in UNIX EPOCH timestamp (UTC timezone) format |
Parameter Groups:
Order Info Parameters Parameters:- Used only for the Create Mandate Order and Mandate Execution API.
Field | Type | Description | |
---|---|---|---|
order_id | * | String | Unique Identifier for the order. You can pass your native order ID here. |
amount | * | String | Amount that the customer has to pay. Will accept double values with upto two decimal places. For example, 100.15 is valid, but 100.1532 is not valid. |
order_type | String | Set to “TPV_PAYMENT” if using Third-Party Validation. | |
currency | * | String | ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR |
customer_id | * | String | Unique ID for a customer that you get after running the Create Customer API (Check Customer section for more details) |
customer_email | * | String | Email address of the customer. This field is mandatory if gateway requires it. |
customer_phone | String | Mobile number or fixed line number of the customer. This field is mandatory if gateway requires it. | |
description | String | Short description for the order. We send this information to the gateways whenever there is a provision for this. | |
return_url | String | A fully qualified URL such as http://shop.merchant.com/ to which the customer will be redirected after payment completion. This URL shouldn’t contain any query parameters. This URL takes higher precedence over the common return URL configured in your account settings. | |
product_id | String | An identifier for the product. Fits well for impulse purchase usecases. | |
gateway_id | String | Specify your preferred gateway for this order. Complete mapping for “gateway_id” can be found here: Gateway mapping |
Billing/Shipping Address Parameters:- Used only for the Create Mandate Order and Mandate Execution API.
Field | Type | Description |
---|---|---|
billing_address_first_name | String | First name in the billing address |
billing_address_last_name | String | Last name in the billing address |
billing_address_line1 | String | Line1 in the billing address |
billing_address_line2 | String | Line2 in the billing address |
billing_address_line3 | String | Line3 in the billing address |
billing_address_city | String | Billing address city |
billing_address_state | String | Billing address state |
billing_address_country | String | Billing address country |
billing_address_postal_code | String | Billing address postal code or zip code |
billing_address_phone | String | Mobile or phone number in the billing address |
billing_address_country_code_iso--- | String | ISO Country code (Default value: IND) |
shipping_address_first_name | String | First name in the shipping address |
shipping_address_last_name | String | Last name in the shipping address |
shipping_address_line1 | String | Line1 in the shipping address |
shipping_address_line2 | String | Line2 in the shipping address |
shipping_address_line3 | String | Line3 in the shipping address |
shipping_address_city | String | Shipping address city |
shipping_address_state | String | Shipping address state |
shipping_address_country | String | Shipping address country |
shipping_address_postal_code | String | shipping address postal code or zip code |
shipping_address_phone | String | Mobile or phone number in the shipping address |
shipping_address_country_code_iso | String | ISO Country code (Default value: IND) |
UDF Parameters:- Used only for the Create Mandate Order and Mandate Execution API.
Field | Type | Description |
---|---|---|
udf1 | String | User Defined Field |
udf2 | String | |
udf3 | String | |
udf4 | String | |
udf5 | String | |
udf6 | String | |
udf7 | String | |
udf8 | String | |
udf9 | String | |
udf10 | String |
Payment Method Parameters:- Used only for the Mandate Registration API.
Field | Type | Description | |
---|---|---|---|
order_id | * | String | Unique Identifier for the order. |
merchant_id | * | String | ID of the merchant_account that you hold with us. |
payment_method_type | * | String | Payment method type of transaction. Possible values: UPI / NB / CARD / WALLET / AADHAAR For eNACH, authentication verification can be done via CARD, NB & AADHAAR (Note: NB eMandate supports only NB login authentication. Banks live with NB eMandate are HDFC (Register + Debit), ICICI (Register + Debit), SBI (Register only) and Axis (Register only)) Banks live with eNACH for NB, CARD and AADHAAR authentication https://www.npci.org.in/PDF/nach/live-members-e-mandates/Live-Banks-in-API-E-Mandate.pdf |
payment_method | * | String | Payment method of transaction. COLLECT - For UPI Collect transaction. PAY - For UPI_PAY transaction. For card mandate - One of VISA/MASTERCARD/MAESTRO/AMEX/RUPAY. This is usually inferred from the card number itself and we will take care of this if you are unable to provide this from your end. Please refer to /paymentmethods API https://developer.juspay.in/reference/payment-methods for EMANDATE payment_method values. |
redirect_after_payment | * | Boolean | We recommend that you set this to true and use the redirection flow.If set to true , then the user is redirected to the return_url configured for the order.If set to false , then the user will be stopped at the response page from the gateway.Your client should be able to read the page/title to infer that the user has completed the transaction. |
format | * | String | If it is set to JSON, then the response will be HTTP 200 with a JSON formatted text. Otherwise, the response is HTTP 302 with the Location attribute having the destination URL. |
Bank Details Parameters:- Used only for the Mandate Registration API.
Field | Type | Description | |
---|---|---|---|
bank_name | String | Name of bank that is holding the account | |
bank_account_number | * | String | Bank account number. Required for emandate/e-NACH, or when mandate_type = EMANDATE. |
bank_beneficiary_name | String | Account holder name. Should contain alphabetical characters only. Required for emandate/e-NACH, or when mandate_type = EMANDATE. | |
bank_ifsc | String | Bank IFSC. Required for emandate/e-NACH, or when mandate_type = EMANDATE. |
Card Data Parameters:- Used only for the Mandate Registration API.
Field | Type | Description | |
---|---|---|---|
card_token | * | string | A valid card token obtained using /card/list API. If you send this parameter, then card_number, name_on_card, card_exp_year, and card_exp_month fields are not required.If the token is generated using the /card/tokenize API, card_number, name_on_card, card_exp_year, card_exp_month, and card_security_code fields are not required. Can only be used when mandate_type = MANDATE for a stored card. |
card_number | String | A valid credit/debit card number. Required when mandate_type = MANDATE for a new card transaction. | |
card_exp_year | String | Represent the expiry year of the card as YY (two digits only). Required when mandate_type = MANDATE for a new card transaction. | |
card_exp_month | String | Represent the expiry month of the card as MM (two digits only). Required when mandate_type = MANDATE for a new card transaction. | |
card_security_code | String | CVV of the card. Usually three digits. Required when mandate_type = MANDATE for a new card transaction. | |
name_on_card | String | Card holder name. Should contain alphabetical characters only. Required when mandate_type = MANDATE for a new card transaction. | |
save_to_locker | String | This is a boolean variable and accepts true/false. If set to true, then the card will be saved in locker when the transaction is successful. Else, the card will not be saved. |
Other request parameters for the Mandate Registration API:
Parameter | Type | Description | |
---|---|---|---|
upi_vpa | * | String | VPA to which the collect request must be sent |
mandate type | * | String | EMANDATE in case of UPI/NB/Wallet. MANDATE in case of card. |
should_create_mandate | Boolean | This is a customer’s consent flag. This should be always be TRUE in case of a mandate transaction. |
Other request parameters for the Notification API:
Parameter | Type | Description | |
---|---|---|---|
command | * | String | Set to “pre_debit_notify” for sending notification before execute mandate. |
object_reference_id | * | String | Merchants unique Identifier for the request. |
description | * | String | Reason for debit that will be sent to user. Max Length: 50 |
metadata | String | For future use case | |
mandate: {display_invoice_number} | Object String | If merchant wants to generate invoice display number, this needs to be passed in notification call. If not passed, Juspay will create a unique invoice number and pass it to downstream system. It should be alphanumeric and length upto 25 characters. (Applicable only for cards SI) |
Other request parameters for the Mandate Execution API:
Parameter | Type | Description | |
---|---|---|---|
mandate_id | * | String | Mandate ID sent by Juspay after mandate creation. |
merchant_id | * | String | The username you hold at Juspay |
format | * | String | The format of the response. Should be passed as json . |
mandate.notification_id | Object String 1 | [CONDITIONAL] The object_reference_id which was sent in notification API call. Applicable only for merchants calling Notification and Execution APIs separatly. | |
mandate.display_invoice_number | Object String 2 | Applicable only for cards SI. If merchant wants to generate invoice display number, but wants Juspay to handle pre-debit notification, this needs to be sent. | |
mandate.execution_date | Object String 3 | Applicable only for merchants enabled for mandate workflow (notification + execution flow).UNIX EPOCH timestamp format. Default execution happens at 25th hour of successful notification. If a merchant wants to execute mandate at custom time anytime after 25th hour, send execution_date. |
Other request parameters for the Revoke Mandate API:
Parameter | Type | Description | |
---|---|---|---|
command | * | String | To be set as "revoke" to revoke an existing mandate |
Other request parameters for the Pause Mandate API:
Parameter | Type | Description | |
---|---|---|---|
command | * | String | To be set as "pause", to pause an active mandate |
pause_start_date | String | Date in UNIX EPOCH timestamp (UTC timezone) format, when the mandate will be paused. Default value can be the current date. | |
pause_end_date | String | Date in UNIX EPOCH timestamp (UTC timezone) format, when the mandate status will be automatically changed to ACTIVE. Default value can be set to mandate_end_date. |
Other request parameters for the Resume Mandate API:
Parameter | Type | Description | |
---|---|---|---|
command | * | String | To be set as "resume" to resume a paused mandate |
resume_date | String | [Optional] Date in UNIX EPOCH timestamp (UTC timezone) format, when the mandate needs to be set active. Default value will be the current date. |
Response Parameters for Mandate APIs:
Status, Redirect Info Object- Response for the Create Mandate Order API.
Parameter | Type | Description |
---|---|---|
id | String | Unique ID generated by Juspay for the given order. |
order_id | String | Given order ID. |
status | String | Status of the order. If you receive “NEW”, then the mandate is successfully created. See Appendix below for status mapping. If you invoke this API with an order_id which already has a mandate created, then this API will return the result of the Get Mandate Order Status API. |
status_id | Integer | Status ID is a numeric ID corresponding to the status value. See Appendix below for code meaning. |
payment_links:wwwwwwni {web, mobile, iframe} | Object String | Three links for a Desktop , Mobile, and iFrame checkout screen for the given order (Parameters listed in table below - click to open) |
Payment Links Object Parameters:
Field | Type | Description |
---|---|---|
web | String | Link to checkout page that is optimized for Desktop for the given order. |
mobile | String | Link to Mobile optimized checkout page for the given order. |
iframe | String | Link to iFrame checkout screen. This is typically embedded inside of your own page. |
Order create response now has payment links for web, mobile & iFrame. These links can directly be emailed or messaged to your customers. They will be redirected using a link to enter payment information. If you wish to use your own branding, then you can embed the iframe link into your page. Note that, these links are not valid perpetually. As soon as your order expires (this can be changed via our dashboard), the link will cease to work.
Status | ID | Meaning |
---|---|---|
NEW | 10 | Newly created mandate |
PENDING_VBV | 23 | Authentication is in progress. The customer has to approve the mandate through the PSP App of their choice. |
CHARGED | 21 | Successful transaction. The subscription cost of the period has been charged. |
AUTHENTICATION_FAILED | 26 | User did not complete authentication |
AUTHORIZATION_FAILED | 27 | User completed authentication, but bank refused the transaction |
JUSPAY_DECLINED | 22 | User input is not accepted by the underlying PG |
AUTHORIZING | 28 | Transaction status is pending from bank |
Order Object, which includes a Mandate Object- Response for the Get Mandate Order Status
Parameter | Type | Description |
---|---|---|
mandate:wwwwwwwwwwwn {param1, param2, ....} | Object String | Object containing mandate details. (Parameters listed in table below - click to open) |
Mandate Object Parameters:
Field | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
mandate_id | String | Mandate ID is a unique identifier generated and sent by Juspay after mandate creation. Must be sent with Notification, Revoke Mandate, and Mandate Execution APIs. | ||||||
mandate_token | String | Mandate token is a unique identifier generated and sent by Juspay after mandate creation for one-time use. This is a 32 digit alphanumeric unique value. Allows a charge without a 2nd factor. | ||||||
mandate_status | String | Current status of the mandate. Must be one of the states listed in this table: (ENUM format) CREATED / ACTIVE / PAUSED / REVOKED / FAILURE / PENDING / EXPIRED | ||||||
mandate_type | String | EMANDATE in case of UPI/NB/Wallet payment MANDATE in case of Card payment | ||||||
max_amount | String | Maximum amount for 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 This should be included also. | ||||||
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 here for additional rules on this value. | ||||||
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 | ||||||
start_date | String | Mandate start date in UNIX EPOCH timestamp (UTC timezone). 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), from when a mandate will move to EXPIRED state and recurring mandate will not be allowed. Mandatory only for UPI Mandate. | ||||||
block_funds | 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. | ||||||
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 here 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 |
revokable_by_customer | Boolean | If FALSE, the mandate cannot be revoked by the customer once set. Applicable only for UPI mandate. It should be TRUE for Recurring and TRUE/FALSE for ONETIME. By default, value will be TRUE |
bank_details:wwwwnwww {param1, param2,...} | Object String | Bank details. (This object was also found in the "Card" response for the List Mandate API.) |
Bank Details Object Parameters:
Field | Type | Description |
---|---|---|
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 |
payment_links:wwwwwwwwii {web, mobile, iframe} | Object String | Three links for a Desktop , Mobile, and iFrame checkout screen for the given order (Parameters listed in table below - click to open) |
Payment Links Object Parameters:
Field | Type | Description |
---|---|---|
web | String | Link to checkout page that is optimized for Desktop for the given order. |
mobile | String | Link to Mobile optimized checkout page for the given order. |
iframe | String | Link to iFrame checkout screen. This is typically embedded inside of your own page. |
Payment Links
These links can directly be emailed or messaged to your customers. They will be redirected using a link to enter payment information. If you wish to use your own branding, then you can embed the iframe link into your page. Note that, these links are not valid perpetually. As soon as your order expires (this can be changed via our dashboard), the link will cease to work.
txn_detail:wwwwwnnwwwww {param1, param2, ....} | Object String | Object containing transaction details wwww |
Transaction Detail Object Parameters:
Field | Type | Description | Example |
---|---|---|---|
txn_uuid | String | Transaction UUID (available in Order Status API response) | "eulneT9JkaAPa1uv" |
txn_object_type | String | Transaction object type | "EMANDATE_REGISTER" |
txn_id | String | Transaction ID | "11327833" |
txn_amount | String | Amount of transaction | 1 |
tax_amount | String | Amount of tax applied | null |
surcharge_amount | String | Extra fee charged by merchant on payment | null |
status | String | Status of the order (see Status Mapping table below.) | "CHARGED" |
source_object_id | String | ID of source object | "91887" |
source_object | String | Set to "MANDATE" | "MANDATE" |
redirect | boolean | If true, the user is redirected to the return_url configured for the order. | false |
order_id | String | Unique Identifier for the order. | "145678234" |
net_amount | String | Net amount of order | 1 |
gateway_id | String | Unique numeric identifier for your preferred gateway. (Refer to "Gateway Mapping" table.) | 19 |
gateway | String | Name or your preferred gateway | "PAYTM_V2" |
express_checkout | boolean | True if using Express Checkout | false |
error_message | String | Bank error message | "" |
error_code | String | Numeric code of bank error message | "" |
currency | String | ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR | "INR" |
created | Date- Time | Date time (ISO representation) when order was created | "2020-04-28T06:31:37Z" |
payment_gateway_response:i {param1, param2, ....} | Object String | Object containing payment gateway details (Parameters listed in table below - click to open) |
Payment Gateway Response Object Parameters:
Field | Type | Description | Example |
---|---|---|---|
txn_id | String | Transaction ID | "11327833" |
rrn | String | Authorization Retrieval Reference Number | "502913366745" |
resp_message | String | Result of API action | "Payment Successful" |
resp_code | String | Numeric code of response message | "0" |
epg_txn_id | String | Electronic Payment Gateway transaction ID | "1532690566017" |
created | Date- Time | Date time (ISO representation) when order was created | "2020-04-28T06:31:37Z" |
auth_id_code | String | Authorization ID Code | "475926" |
card:wwwwwwwwwwwwwwt {param1, param2, ....} | Object String | Object containing credit/debit card details |
Card Object Parameters:
Field | Type | Description |
---|---|---|
using_token | Boolean | True if using a token |
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_reference | String | Unique reference ID for card (if any) |
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_fingerprint | String | Card fingerprint |
card_brand | String | Brand of card ("MASTERCARD", "VISA", etc.) |
merchant_id | String | Unique identifier for the merchant. |
order_id | String | Unique Identifier for the order. It is suggested to keep the order id length at a maximum of 21 characters irrespective of payment methods and gateways. |
id | String | Unique ID generated by Juspay for the given order. |
customer_id | String | Customer Identifier against which a mandate should be created. This has to be unique for a customer |
customer_email | String | Email address of the customer. Must be present if backend gateway requires it. |
customer_phone | String | Mobile number or fixed line number of the customer. Must be present if backend gateway requires it. |
product_id | String | An identifier for the product on the Lender side for which the payment is being done. This field is just echoed back in the response so that Lender can differentiate on their side. Fits well for impulse purchase usecases. |
status | String | Status of the order. If you receive “NEW”, then the order is successfully created. See Appendix for status mapping. |
status_id | Integer | Status ID is a numeric id corresponding to the status value. See Appendix for code meaning. |
amount | Double | This is the amount that a customer will be charged in this transaction. Will accept double values with up to two decimal places. For example, 100.15 is valid input but 100.1532 is not valid. |
effective_amount | Double | Amount that the customer actually pays |
currency | String | ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR |
refunded | Boolean | Boolean value that determines if the amount was refunded or not. |
amount_refunded | Double | Amount that has been refunded so far for this order. |
date_created | Date- Time | Date-time of mandate order creation |
return_url | String | A fully qualified URL such as http://shop.merchant.com/ to which the customer will be redirected after payment completion. This URL shouldn’t contain any query parameters. This URL takes higher precedence over the common return URL configured in your account settings. |
udf1 | String | udf1 to udf10 - User defined field which will be echoed back in the response from Juspay with a Max character limit of 255. |
udf2 | String | |
udf3 | String | |
udf4 | String | |
udf5 | String | |
udf6 | String | |
udf7 | String | |
udf8 | String | |
udf9 | String | |
udf10 | String | |
txn_id | String | Transaction ID |
txn_uuid | String | Transaction UUID |
gateway_id | String | Unique numeric identifier for your preferred gateway. (Refer to "Gateway Mapping" table.) |
gateway_reference_id | String | Alphabetic reference to the payment gateway used |
bank_pg | String | Payment gateway for bank. |
metadata: {param1, param2,...} | Object | Used for sending custom parameters to the payment aggregators, irrespective of default parameters. Check here for parameter list. |
offers: [{...},{...},...] | Array of Objects | The mechanism of running offers is the responsibility of merchants in collaboration with PG/Banks. |
bank_error_code | String | Bank Error Code |
bank_error_message | String | Bank Error Message |
payment_method_type | String | Must be either CARD, NB, WALLET, or UPI. Entered when creating the order or mandate |
payment_method | String | Entered when creating the order or mandate. Found in the given tables for the corresponding API and transaction type. |
payer_vpa | String | Payer VPA used during setting up mandate |
auth_type | String | Type of authentication used |
Refunds: [{...},{...},..] wwwwwwwwwwww | Array of Objects | An array of Refund Objects with details of each refund (returned with the Refund Order API). Should be returned if refunded is set to true in response. |
Parameters for each object in the Refunds array:
Field | Type | Description |
---|---|---|
unique_request_id | String | The unique request ID that is passed during refund initiation. Do not pass any special characters. |
status | String | The status of the refund initiated. Initial status will always be PENDING Status codes and meaningSUCCESS This means that the refund has been successfully executed. PENDING This would mean that the refund has been queued withJusPay or with the downstream system. FAILURE We were unable to process the refund successfully. You have to try again with a new unique_request_id .MANUAL_REVIEW This would mean that the refund request was sent an ambigious response from the payment gateway and the merchant has to manually reconcile it with the payment gateway to get the proper response. Also, any refunds which are in pending for more than 10 days are sent for manual review. |
sent_to_gateway | Boolean | The flag denotes if the refund was initiated to gateway. The initial status is always false, as refunds are queued at Juspay for a maximum of 15 minutes. |
refund_type | String | The type of refund. Values can be STANDARD or INSTANT |
refund_source | String | The name of gateway |
ref | String | The refund ID provided by the PG |
initiated_by | String | The source of initiation |
id | String | The reference ID provided by PG, if not available then its mapped to the unique request ID. |
error_message | String | The error message provided by the PG |
error_code | String | The error code provided by the PG |
amount | Integer | The refund amount passed in the request |
created | Time- stamp | The timestamp when refund was created |
Payment Status Object- Response for the Mandate Registration and Mandate Execution API.
Parameter | Type | Description |
---|---|---|
order_id | String | Unique Identifier for the order. |
txn_id | String | Transaction ID for the payment attempt. |
txn_uuid | String | Transaction UUID |
status | String | Status of the transaction. See Appendix below for status mapping. PENDING_VBV indicates that the transaction requires authentication to complete. |
payment:wwiw {{...},{...}} | Object | Contains authentication object:{ method, url, params }(also sdk_params object for UPI Intent) |
Parameters for the payment
object:
{click to open)
authentication: {method, url, params} | Object | Authentication parametersww |
Parameters for the authentication
object:
(click to open)
Parameter | Type | Description |
---|---|---|
method | String | HTTP Method for authentication. Can be one of GET or POST. (For redirection instructions, see the "Handling the Redirection Method" section.) |
url | String | URL to which the user has to be taken to for completing the authentication |
params | String | Present only when the method is POST. Parameter map that has to be sent along with the URL for authentication. Do not hardcode the params in your client * Never assume that you will receive param “x” or param “y”. This is completely dynamic and will vary on a case by case basis. |
sdk_params: {{...},...} | Object | SDK parameterswwwwww (Used only for UPI Intent) |
Parameters the sdk_params
object:
(click to open)
scheme | String | Should be "mandate" | |
uri_params: {param1, param2,...} | Object | URI parameterswwwwtwww |
Parameters for the uri_params
object:
(click to open)
Parameter | Type | Example | |
---|---|---|---|
validitystart | String | "eulcEPzPd244hfrGShFpH" | |
validityend | String | "24082037" | |
tr | String | "PAYTMSUBS202206203480824046791145" | |
tn | String | "Amount%20to%20be%20paid%20now%20is%20Rs%201.00" | |
tid | String | "PYTM20220620937257791803424" | |
recur | String | "ASPRESENTED" | |
purpose | String | "14" | |
pn | String | "test" | |
pa | String | "[email protected]" | |
orgid | String | "00000" | |
mode | String | "00" | |
mn | String | "Subscription%20for%20testaccount" | |
mc | String | "5811" | |
cu | String | "INR" | |
amrule | String | "MAX" | |
am | String | "1000.00" |
offer_details:wi { offers: [...]} | Array in Object | The mechanism of running offers is the responsibility of merchants in collaboration with PG/Banks (used only for UPI Intent). |
Status | ID | Meaning |
---|---|---|
NEW | 10 | Newly created order |
PENDING_VBV | 23 | Authentication is in progress |
CHARGED | 21 | Successful transaction |
AUTHENTICATION_FAILED | 26 | User did not complete authentication |
AUTHORIZATION_FAILED | 27 | User completed authentication, but bank refused the transaction |
JUSPAY_DECLINED | 22 | User input is not accepted by the underlying PG |
AUTHORIZING | 28 | Transaction status is pending from bank |
Notification Status Object- Response for the Notification and Notification Status API.
Parameter | Type | Description |
---|---|---|
id | String | Unique identifier provided by Juspay. i.e. "1957069" |
source_object | String | Source object for notification. i.e. “MANDATE” |
source_object_id | String | Source object for notification. mandate_id in this case.i.e. "92025" |
object | String | Must be set to "notification" |
object_reference_id | String | Unique Identifier passed in the request. I.e. "1234578" |
provider_name | String | Name of the provider. Gateway name in this case I.e. "PAYTM_V2" |
notification_type | String | Type of notification. I.e. “SMS” |
description | String | Reason for debit passed in the request |
status | String | Status of Notification. Must be one of these four states: CREATED - Notification created in Juspay System, but not yet initiated to gateway PENDING - Initiated to the Payment Gateway, and awaiting the notification status from gateway SUCCESS - Success from gateway FAILURE - Failed from gateway |
date_created | String | Date-time of notification created in UNIX EPOCH timestamp (UTC timezone) format. i.e. "1598960071" |
last_updated | String | Date-time of notification updated in UNIX EPOCH timestamp (UTC timezone) format. i.e. "1598960071" |
metadata | String | Metadata passed in the request |
mandate: {mandate_id} | Object String | Mandate ID provided in the request: i.e. "4rKxSj3bNXs7RQcdtajAkb" |
source_info: {param1, param2,...} | Object | JSON block of source info provided in the request. |
Parameters for the source_info
object:
(click to open)
amount | String | Amount passed in the request. i.e. "100.00"< |
txn_date | String | txn_date passed in the request.Format: UNIX EPOCH timestamp (UTC timezone). i.e. "1634057114" |
mandate.display_invoice_number | String | The display invoice number that was passed in the request. i.e. "INVN67Mzd6wMX4xPVBC" |
provider_response: {param1, param2} | Object | JSON block of response from gateway. |
Parameters for the provider_response
object:
(click to open)
provider_ref_id | String | Reference Number provided by downstream gateway. i.e. "IN0DF815118772" |
notification_date | String | Date on which notification was sent by downstream gateway. I.e. "1634057114" Specific to PAYTM_V2 |
An array of Mandate Objects, each of which includes a Payment Info Object:- Response for the List Mandate API.
Parameter | Type | Description |
---|---|---|
object | 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.
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 |
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 | ||||||
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. |
revokable_by_customer | Boolean | If FALSE, the mandate cannot be revoked by the customer once set. Applicable only for UPI mandate. It should be TRUE for Recurring and TRUE/FALSE for ONETIME. By default, value will be TRUE |
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)
mandate.rule_value
when mandate.frequency
is set to 'FORTNIGHTLY' or 'MONTHLY'. "mandate_id", "mandate_status"- Response for the Revoke Mandate API.
Parameter | Type | Description |
---|---|---|
mandate_id | String | Unique identifier for the mandate sent by Juspay after mandate creation. mandate_id can be obtained from the List Mandate API response. |
*mandate_status | String | Current status of the mandate. Must be one of the states listed in this table: (ENUM format) CREATED / ACTIVE / PAUSED / REVOKED / FAILURE / PENDING / EXPIRED |