Overview of the Mandates APIs

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:

MandateFlow2MandateFlow2

Brief description of each Mandate API:

Create Mandate   
Order:  
Use this API to create a mandate for your existing customers with subscription specific details like amount, subscription frequency, duration of the mandate, etc. Use mandate_id from the response of this API to call the Mandate Registration API. Prerequisite for creating a mandate is to have the customer already registered/created with you.
  POST     https://api.juspay.in/orders
Get Mandate   
Order Status:  
This is very similar to the Get Order Status API, except that it includes a Mandate Object in the response, which provides order status and details of a mandate.
  GET     https://api.juspay.in/orders/:order_id
Mandate   
Registration:  
Use this API to choose the preferred mode of payment for the mandate. Supported payment method types include UPI, Card, Wallet and Net banking. Flow diagrams for the COLLECT and PAY payment methods are shown below. The same API will also validate the payment method specific data like UPI, VPA, etc. Share the URL that you get in the response body with your end customer, for whom this mandate is being initiated. They will have to run the same to authorize the collect request from their UPI App.
  POST     https://api.juspay.in/txns
Notification:  
Notification API is required for merchants to notify users. Sends a notification to the customer before the mandate transaction is exercised. A notification must be sent to the user 24 to 48 hours before a Mandate Execution API for recurring mandates. Mandate is executed only if notification is successful.
  POST     https://api.juspay.in/mandates/:mandate_id
Notification   
Status:  
Merchants can call this API to check whether a notification has been sent to a customer or not. References a previous notification by  object_reference_id.
  GET     https://api.juspay.in/notifications/:object_reference_id
Mandate   
Execution:  
After the Mandate is successful, Merchant will receive a  mandate_token from Juspay that should be stored against a customer at their end. From the subsequent charge transactions, Merchant is supposed to pass a combination of  customer_id and  mandate_token / mandate_id to do a charge without a 2nd factor. This API will create the order and will charge it based on the  mandate_token or  mandate_id passed by the merchant. Must be sent after 24 hours and before 48 hours once a successful notification response is received.
  GET     https://api.juspay.in/txns
Get Mandate   
Execution Status:  
This is the same as the Get Order Status API, except that it also provides mandate details in the response (Mandate Object). This gives the status against a previously initiated execution of a mandate.
  GET     https://api.juspay.in/v2/orders/:order_id/
List Mandate:  
A merchant can call this API to get a detailed list of all the mandates that a customer has with them. The list will also include all revoked, expired, and failed mandates.
  GET     https://api.juspay.in/customers/:customer_id/mandates
Revoke Mandate:  
Use this API to revoke/cancel an already existing mandate by passing the  mandate_id.
  POST     https://api.juspay.in/mandates/:mandate_id

Request Parameters for Mandate APIs

URL Embedded (Path) Parameters:

Field Type * Description
order_id String *

Required only for the Get Mandate Order Status and Get Mandate Execution Status APIs.
- Unique Identifier for the order.
mandate_id String *




Required only for the Notification and Revoke 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.
* = Required only for the specified APIs
Header:

Field Type * Description
x-merchantid String *



Required only for the Create Mandate Order, Get Mandate Order Status, Get Mandate Execution Status, and Revoke Mandate APIs.
- Merchant ID which would have been issued while registering with Juspay
* = Required only for the specified APIs

 Objects and Parameter Groups used for Mandate API requests:
(Open tables to view parameters.)

 Objects:
  Mandate Object Parameters:
- Used only for the Create Mandate Order API.
FieldTypeDescription
max_amount*StringMaximum amount for a mandate. Mandatory only if mandate.amount_rule = VARIABLE.
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
start_date*StringMandate 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*StringMandate 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_fundsBooleanSet 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 here for additional rules on this value.
rule_valueStringDetermines 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 here 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
revokable_by_customerBooleanIf 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
* = Required
  Metadata Object Parameters:
- Used only for the Create Mandate Order API.
FieldTypeDescription
bank_account_numberwStringBank account number of VPA used. Used only if downstream supports third party validation.
bank_ifscStringIFSC code for a given bank.
PAYTM_V2:
SUBSCRIPTION_GRACE_DAYS
StringNumber 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
StringApplicable only for Paytm. By default 2 for UPI mandate.
PAYTM_V2:
GATEWAY_REFERENCE_ID
StringCustomized PAYTM_V2 parameter for the payment aggregators. This was found in request, but not in parameter list.
* = Required
  Options Object Parameter:
- Used only for the Create Mandate Order API.
FieldTypeDescription
create_mandate*StringMerchants 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”
* = Required
  Source Info Object Parameters:
- Used only for the Notification API.
FieldTypeDescription
amount*StringAmount for which notification is to be sent to customer
I.e. "100.00"
txn_date*StringDate on which debit is intended to happen in UNIX EPOCH timestamp (UTC timezone) format
* = Required

 Parameter Groups:

  Order Info Parameters Parameters:
- Used only for the Create Mandate Order and Mandate Execution API.
FieldTypeDescription
order_id*StringUnique Identifier for the order. You can pass your native order ID here.
amount*StringAmount 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.
currency*StringISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR
customer_id*StringUnique ID for a customer that you get after running the Create Customer API (Check Customer section for more details)
customer_email*StringEmail address of the customer.
This field is mandatory if gateway requires it.
customer_phoneStringMobile number or fixed line number of the customer.
This field is mandatory if gateway requires it.
descriptionStringShort description for the order. We send this information to the gateways whenever there is a provision for this.
return_urlStringA 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_idStringAn identifier for the product. Fits well for impulse purchase usecases.
gateway_idStringSpecify your preferred gateway for this order. Complete mapping for “gateway_id” can be found here: Gateway mapping
* = Required
  Billing/Shipping Address Parameters:
- Used only for the Create Mandate Order and Mandate Execution API.
FieldTypeDescription
billing_address_first_nameStringFirst name in the billing address
billing_address_last_nameStringLast name in the billing address
billing_address_line1StringLine1 in the billing address
billing_address_line2StringLine2 in the billing address
billing_address_line3StringLine3 in the billing address
billing_address_cityStringBilling address city
billing_address_stateStringBilling address state
billing_address_countryStringBilling address country
billing_address_postal_codeStringBilling address postal code or zip code
billing_address_phoneStringMobile or phone number in the billing address
billing_address_country_code_iso---StringISO Country code
(Default value: IND)
shipping_address_first_nameStringFirst name in the shipping address
shipping_address_last_nameStringLast name in the shipping address
shipping_address_line1StringLine1 in the shipping address
shipping_address_line2StringLine2 in the shipping address
shipping_address_line3StringLine3 in the shipping address
shipping_address_cityStringShipping address city
shipping_address_stateStringShipping address state
shipping_address_countryStringShipping address country
shipping_address_postal_codeStringshipping address postal code or zip code
shipping_address_phoneStringMobile or phone number in the shipping address
shipping_address_country_code_isoStringISO Country code
(Default value: IND)

  UDF Parameters:
- Used only for the Create Mandate Order and Mandate Execution API.

udf1 to udf10 - Optional user defined fields which will be echoed back in the response from Juspay with a Max character limit of 255. These fields may be used to pass any additional information that is required to be stored at Juspay for any analysis or other operations. In some cases, these UDFs are passed to the downstream gateways as well.

FieldTypeDescription
udf1StringUser Defined Field
udf2String
udf3String
udf4String
udf5String
udf6String
udf7String
udf8String
udf9String
udf10String

  Payment Method Parameters:
- Used only for the Mandate Registration API.
Note:
These are the same Payment Method Parameters used in the Payments API requests.
FieldTypeDescription
order_id*StringUnique Identifier for the order.
merchant_id*StringID of the merchant_account that you hold with us.
payment_method_type*StringPayment method type of transaction. UPI for UPI Autopay payments. The other possible values are CARD, NB, WALLET.
payment_method*StringPayment method of transaction.
COLLECT - For UPI Collect transaction.
PAY - For UPI_PAY transaction.
Only COLLECT is supported for now.
redirect_after_payment*BooleanWe 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*StringIf 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.
* = Required
  Bank Details Parameters:
- Used only for the Mandate Registration API.
FieldTypeDescription
bank_nameStringName of bank that is holding the account
bank_account_number*StringBank account number. Required for emandate/e-NACH, or when mandate_type= EMANDATE.
bank_beneficiary_nameStringAccount holder name. Should contain alphabetical characters only. Required for emandate/e-NACH, or when mandate_type= EMANDATE.
bank_ifscStringBank IFSC. Required for emandate/e-NACH, or when mandate_type= EMANDATE.

  Card Data Parameters:
- Used only for the Mandate Registration API.
Note:
These are the same Card Data Parameters used in the Payments API requests.
FieldTypeDescription
card_token*stringA 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.   Required for MANDATE mandate_type for stored card.
card_numberStringA valid credit/debit card number. Required when mandate_type= MANDATE for a new card transaction.
card_exp_yearStringRepresent the expiry year of the card as YY (two digits only). Required when mandate_type= MANDATE for a new card transaction.
card_exp_monthStringRepresent the expiry month of the card as MM (two digits only). Required when mandate_type= MANDATE for a new card transaction.
card_security_codeStringCVV of the card. Usually three digits. Required when mandate_type= MANDATE for a new card transaction.
name_on_cardStringCard holder name. Should contain alphabetical characters only. Required when mandate_type= MANDATE for a new card transaction.
save_to_lockerStringThis 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 (Form) Parameters sent by Mandate APIs, but not included in an Object or Parameter Group:
Other request parameters for the Mandate Registration API:
Field * 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.
* = Required
Other request parameters for the Notification API:
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
* = Required
Other request parameters for the Mandate Execution API:
mandate_tokenwwwt * String Mandate token sent by Juspay after mandate creation.
NOTE: This is a unique identifier generated by Juspay. Either  mandate_id or   mandate_token is mandatory.
mandate_id * String Mandate ID sent by Juspay after mandate creation.
Either  mandate_id or   mandate_token is mandatory.
* = Only one of these two parameters is required
Other request parameters for the Revoke Mandate API:
commandwwwwwwwt * String To be set as "revoke", to revoke an existing mandate
* = Required

Response Parameters for Mandate APIs

(Click to open tables.)

  Status, Redirect Info Object
- Response for the Create Mandate Order API.
Note:
Response parameters are the same as for the Create Order API (Status, Redirect Info), except that the unique ID is generated for the mandate instead of order (mandate_id).
ParameterTypeDescription
mandate_idStringUnique ID generated by Juspay for the given mandate.
Identifier for the new mandate should be returned, not just "id".
order_idStringGiven order ID.
statusStringStatus of the order. If you receive “NEW”, then the mandate order 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_idIntegerStatus ID is a numeric ID corresponding to the status value. See Appendix below for code meaning.
payment_links.webStringLink to Desktop optimized checkout page for the given order.
payment_links.mobileStringLink to Mobile optimized checkout page for the given order.
payment_links.iframeStringLink to iFrame checkout screen. This is typically embedded inside of your own page.

    APPENDIX   - Order status codes and meaning:

StatusIDMeaning
NEW10Newly created mandate order
PENDING_VBV23Authentication is in progress. The customer has to approve the mandate through the PSP App of their choice.
CHARGED21Successful transaction. The subscription cost of the period has been charged.
AUTHENTICATION_FAILED26User did not complete authentication
AUTHORIZATION_FAILED27User completed authentication, but bank refused the transaction
JUSPAY_DECLINED22User input is not accepted by the underlying PG
AUTHORIZING28Transaction status is pending from bank

  Order Object, which includes a Mandate Object
- Response for the Get Mandate Order Status and Get Mandate Execution Status API.
ParameterTypeDescription
mandate:wwwwwwwwwn
      {param1, param2, ....}
Object
String
Object containing mandate details wwwwwwnw
    Mandate Object Parameters:
FieldTypeDescription
mandate_idStringMandate ID is a unique identifier generated and sent by Juspay after mandate creation. Must be sent with Notification and Revoke Mandate APIs. For the Mandate Execution API, either mandate_id or mandate_token can be used.
mandate_tokenStringMandate token is another unique identifier generated and sent by Juspay after mandate creation. This is a 32 digit alphanumeric unique value. Can can be sent with the Mandate Execution API along with customer_id. Allows a charge without a 2nd factor.
mandate_statusString---Current status of the mandate. Must be one of the states listed in this table.
mandate_type--StringEMANDATE in case of UPI/NB/Wallet payment
MANDATE in case of Card payment
max_amountStringMaximum amount for 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. This should be included also.
activated_atStringTime stamp of mandate activation
This should be included also.
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 here for additional rules on this value.
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
start_dateStringMandate 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_dateStringMandate 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_fundsBooleanSet 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_valueStringDetermines 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 here for additional rules on this value.
revokable_by_customerBooleanIf 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
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:
FieldTypeDescription
webStringLink to checkout page that is optimized for Desktop for the given order.
mobileStringLink to Mobile optimized checkout page for the given order.
iframeStringLink to iFrame checkout screen. This is typically embedded inside of your own page.
payment_gateway_response:
      {param1, param2, ....}
Object
String
Object containing payment gateway response details
    Payment Gateway Response Object Parameters:
FieldTypeDescriptionExample
txn_idStringTransaction ID"11327833"
rrnStringAuthorization Retrieval Reference Number"502913366745"
resp_messageStringResult of API action"Payment Successful"
resp_codeStringNumeric code of response message"0"
epg_txn_idStringElectronic Payment Gateway transaction ID"1532690566017"
createdStringDate time (ISO representation) when order was created"2020-04-28T06:31:37Z"
auth_id_codeStringAuthorization ID Code"475926"
txn_detail:wwwiwwwww
      {param1, param2, ....}
Object
String
Object containing transaction details wwww
    Transaction Detail Object Parameters:
FieldTypeDescriptionExample
txn_uuidStringTransaction UUID"eulneT9JkaAPa1uv"
txn_idStringTransaction ID"11327833"
txn_amountDoubleAmount of transaction1
tax_amountDoubleAmount of tax appliednull
surcharge_amountStringExtra fee charged by merchant on paymentnull
statusStringStatus of the order (see Status Mapping table.)"CHARGED"
redirectBooleanIf true, the user is redirected to the return_url configured for the order.false
order_idStringUnique Identifier for the order."145678234"
net_amountDoubleNet amount of order1
gateway_idIntegerUnique numeric identifier for your preferred gateway. See "Gateway Mapping".19
gatewayStringName or your preferred gateway"PAYTM_V2"
express_checkoutBooleanTrue if using Express Checkoutfalse
error_messageStringBank error message""
error_codeStringNumeric code of bank error message""
currencyStringISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR"INR"
createdStringDate time (ISO representation) when order was created"2020-04-28T06:31:37Z"
card:wwwwwwwwwwwwwww
      {param1, param2, ....}
Object
String
Object containing credit/debit card details
Note:   This is found in the Order Object (response) for Order APIs, but is not found in response for this API.
    Card Object Parameters:       (This probably won't be needed.)
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.)
merchant_idwwwwwwwwwwiStringUnique identifier for the merchant.
order_idStringUnique 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.
idStringUnique ID generated by Juspay for the given order.
customer_idStringString that uniquely identifies the customer. Generated by Juspay when you created customer object.
customer_emailStringEmail address of the customer. Must be present if backend gateway requires it.
customer_phoneStringMobile number or fixed line number of the customer. Must be present if backend gateway requires it.
product_idStringAn 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.
statusStringStatus of the order. If you receive “NEW”, then the order has been successfully created (see Status Mapping table).
status_idIntegerStatus ID is a numeric id corresponding to the status value (see Status Mapping table).
amountDoubleThis 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.
currencyStringISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR
refundedBooleanTrue if the order has been completely refunded. Will be false for partial refunds or if the order doesn’t have any refunds.
amount_refundedDoubleAmount which has been refunded so far for this order.
date_createdStringDate-time of mandate or order creation
return_urlStringA 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.
udf1Stringudf1 to udf10 - User defined field which will be echoed back in the response from Juspay with a Max character limit of 255.
udf2String
udf3String
udf4String
udf5String
udf6String
udf7String
udf8String
udf9String
udf10String
txn_idStringTransaction ID
txn_uuidStringTransaction UUID
gateway_idIntegerUnique numeric identifier for your preferred gateway. (Refer to "Gateway Mapping" table.)
gateway_reference_idStringAlphabetic reference to the payment gateway used
bank_error_codeStringBank Error Code
bank_error_messageStringBank Error Message
payment_method_typeStringMust be either CARD, NB, WALLET, or UPI. Entered when creating the order or mandate
payment_methodStringEntered when creating the order or mandate. Found in the given tables for the corresponding API and transaction type.
payer_vpaStringPayer VPA used during setting up mandate
auth_typeStringType of authentication used



  Payment Status Object
- Response for the Mandate Registration and Mandate Execution API.
Note:
This is the same as the Payment Status Object returned for Payments API requests.

In the redirect response, webhook, and check status API, mandate data will be passed additionally from the current parameters.

ParameterTypeConstraintsDescription
order_idStringUnique Identifier for the order.
txn_idStringTransaction ID for the payment attempt.
statusStringStatus of the transaction. See Appendix below for status mapping. PENDING_VBV indicates that the transaction requires authentication to complete.
payment.authentication.methodStringHTTP Method for authentication. Can be one of GET or POST. (For redirection instructions, see the "Handling the Redirection Method" section.)
payment.authentication.urlStringURL to which the user has to be taken to for completing the authentication
payment.authentication.paramsStringPresent 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.

APPENDIX   - Transaction status codes and meaning:

StatusIDMeaning
NEW10Newly created order
PENDING_VBV23Authentication is in progress
CHARGED21Successful transaction
AUTHENTICATION_FAILED26User did not complete authentication
AUTHORIZATION_FAILED27User completed authentication, but bank refused the transaction
JUSPAY_DECLINED22User input is not accepted by the underlying PG
AUTHORIZING28Transaction status is pending from bank

  Notification Status Object
- Response for the Notification and Notification Status API.
ParameterTypeDescription
idStringUnique identifier provided by Juspay.   i.e. “18"
source_objectStringSource object for notification.   i.e. “MANDATE”
source_object_idStringSource object for notification. mandate_id in this case.
i.e. "92025"
objectStringMust be set to "notification"
object_reference_idStringUnique Identifier passed in the request.   I.e. "1234578"
provider_nameStringName of the provider. Gateway name in this case
I.e. "PAYTM_V2"
notification_typeStringType of notification.   I.e. “SMS”
descriptionStringReason for debit passed in the request
statusStringStatus of Notification. Must be one of these four states:
CREATED - Created and not yet initiated to gateway
PENDING - Initiated to gateway
SUCCESS - Success from gateway
FAILURE - Failed from gateway
date_createdStringDate-time of notification created in UNIX EPOCH timestamp (UTC timezone) format.
i.e. "1598960071"
last_updatedStringDate-time of notification updated in UNIX EPOCH timestamp (UTC timezone) format.
i.e. "1598960071"
metadataStringMetadata passed in the request
mandate:
   {mandate_id}
Object
String
 Same as mandate id provided in the request:
 i.e. "mandate_id": "92025"
source_info:wwiwww
   {amount, txn_date}
Object
String
 Same as amount and txn_date passed in the request
 i.e. "amount": "100.00",'txn_date": "2020-07-15 15:00"
provider_response:
   {provider_ref_id,
   notificationDate}
Object
String
String
provider_ref_id: Reference Number provided by
 downstream gateway   i.e. "provider_ref_id": "31413"
notificationDate: Date on which notification was sent.
 I.e. "notificationDate": "2020-07-15 15:00"
 Specific to PAYTM_V2

Note:
Dates for txn_date and notificationDate are formatted as: YYYY-MM-DD HH:MM
  An array of Mandate Objects, each of which includes a Payment Info Object:
- Response for the List Mandate API.
ParameterTypeDescription
objectString"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.
FieldTypeDescription
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_typewiStringPayment 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 should be included as shown in the "Card" response".
upi_details:wwwwwwwi
      {payer_vpa}
Object
String
UPI details related to customer.
Payer VPA used during setting up mandate. wwt
    UPI Details Object Parameter:
FieldTypeDescription
payer_vpaStringPayer VPA used during setting up mandate.
card:wwwwwwwwwwww
      {param1, param2,...}
Object
String
Card details. This parameter should be 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:wwwwwww
      {param1, param2,...}
Object
String
Bank details. This parameter should be included as shown in the "Card" response".
    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_statuswwwwtnStringnCurrent status of the mandate. Must be one of the states listed in this table:
(CREATED / ACTIVE / PAUSED / REVOKED / FAILURE / PENDING / EXPIRED)
mandate_idStringMandate ID is a unique identifier generated and sent by Juspay after mandate creation. Must be sent with Notification and Revoke Mandate APIs. For the Mandate Execution API, either mandate_id or mandate_token can be used.
mandate_tokenStringMandate token is a unique identifier generated and sent by Juspay for one-time use. This is a 32 digit alphanumeric unique value. Can can be sent with the Mandate Execution API along with customer_id for recurring mandate execution. Allows a charge without a 2nd factor.
max_amountwwwwwwiStringMaximum amount of mandate while setting 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
block_fundsBooleanSet 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 here 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_valueStringDetermines 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 here for additional rules on this value.
  "mandate_id", "mandate_status"
- Response for the Revoke Mandate API.
ParameterTypeDescription
mandate_idStringUnique identifier for the mandate sent by Juspay after mandate creation. mandate_id can be obtained from the List Mandate API response.
mandate_statusStringCurrent status of the mandate in question. Must be one of the states listed in this table.


Did this page help you?