JavaScript is disabled. Some features may not work. You can also read the static version: View text version

Session API

This is a Server-to-Server API which accepts order parameters as an input to create order in the Juspay systems and returns SDK payload and payment links.

‘Metadata’ is used to send custom params to the payment aggregators, irrespective of default parameters, The supported parameters

Scroll inside to view more

Payment Gateways	Fields
CCAVENUE_V2	metadata.CCAVENUE_V2:promo_code
BILLDESK	metadata.BILLDESK:AdditionalInfo3
BILLDESK	metadata.BILLDESK:AdditionalInfo4
FREECHARGE	metadata.FREECHARGE:campaignCode
GOCASHFREE	metadata.CASHFREE:metadata1
HSBC_UPI	metadata.HSBC_UPI:addInfo
MIGS	metadata.MIGS:vpc_AddendumData
MIGS	metadata.MIGS:vpc_OrderInfo
OLAMONEY	metadata.OLAMONEY:couponCode
PAYTM	metadata.PAYTM:PROMO_CAMP_ID
PAYTM	metadata.PAYTM:CUST_ID
PAYTM	metadata.PAYTM:MERC_UNQ_REF
PAYTM_V2	metadata.PAYTM_V2:MERC_UNQ_REF
PAYTM_V2	metadata.PAYTM_V2:CUST_ID
TATAPAY	metadata.TATAPAY: merchantTxnMetadata
PAYU	metadata.PAYU:offer_key
PAYU	metadata.PAYU:offer_auto_apply
PAYU	metadata.PAYU:udf1
PAYU	metadata.PAYU:udf2
PAYU	metadata.PAYU:udf3
PAYU	metadata.PAYU:udf4
PAYU	metadata.PAYU:udf5
PHONEPE	metadata.PHONEPE:merchantContext
RAZORPAY	metadata.RAZORPAY:notes[cust_id]
RAZORPAY	metadata.RAZORPAY:notes[cust_name]
RAZORPAY	metadata.RAZORPAY:offer_id
RAZORPAY	metadata.razorpay:PNR
RAZORPAY	metadata.razorpay:PaymentID
RAZORPAY	metadata.razorpay:lob
RAZORPAY	metadata.RAZORPAY:notes Ex: metadata.RAZORPAY:notes={"key1":"value1","key2":"value2","key3":"value3"}
Subvention Amount	metadata.subvention_amount
TPSL	metadata.TPSL:shoppingCartDetails
TPSL	metadata.TPSL:accountNo
ZAAKPAY	metadata.ZAAKPAY:productDescription
ZAAKPAY	metadata.ZAAKPAY:product1Description
PAYPAL	metadata.PAYPAL:landing_page
PAYPAL	metadata.PAYPAL:phone_number
PAYPAL	metadata.PAYPAL:country_code
PAYPAL	metadata.PAYPAL:first_name
PAYPAL	metadata.PAYPAL:last_name
PAYPAL	metadata.PAYPAL:experience_id
PAYPAL	metadata.PAYPAL:brand_name
PAYPAL	metadata.PAYPAL:additional_data
PAYPAL - For Link and Pay	metadata.PAYPAL:lnp_product_name
PAYPAL - For Link and Pay	metadata.PAYPAL:lnp_product_code
PAYPAL - For Link and Pay	metadata.PAYPAL:lnp_charge_pattern
PAYPAL - For Link and Pay	metadata.PAYPAL:direct_wallet_version
PAYPAL - For Link and Pay	metadata.PAYPAL:purchase_category
AMAZONPAY	metadata.AMAZONPAY:sellerNote

Request

Response

API Endpoints

Sandbox Link

POST

https://sandbox.juspay.in/session

Production Link

POST

https://api.juspay.in/session

                      Basic Auth
                      *
                      

Base64 Encoded username:password

required

Consists of two parts.

Username: API Key obtained from Juspay dashboard
Password: Empty string

Example:-
Basic LIR2UUZEQzhFQTY0OUU5QTIxQzNFNTQwNkFDMEZCOg==

                      x-merchantid
                      *
                      

String

Required

Merchant ID provided by Juspay

                      Content-Type
                      *
                      

String

Required

Value: application/json

                      x-routing-id
                      *
                      

String

Required

We recommend passing the customer_id as the x-routing-id. If the customer is checking out as a guest, you can pass an alternative ID that helps track the payment session lifecycle. For example, this could be an Order ID or Cart ID.

This ID is associated with the customer. It plays a key role in ensuring consistency and maintaining connections across different systems. If you fail to pass the same x-routing-id for the same customer in all related API calls, it could lead to issues with API functionality. Therefore, it’s crucial that you use the same x-routing-id for all requests tied to the same customer.

Example:- customer_1122

Body

Request Schema: application/json

                      order_id
                      *
                      

string

required

Max Length : 21

It is a unique Identifier for the order. It should be Alphanumeric with character length less than 21.

Make sure to go through best practices for order_id

Example:-
order-id-9876580

                      amount
                      *
                      

string

required

It is the amount that the customer has to pay. It accepts stringified double or integer values with upto two decimal places. For example, "100.15" and "100" are valid input but "100.1532" is not valid.

Minimum value of amount should be INR 1.

Example:-
1.00

                      customer_id
                      *
                      

string

required

Max Length : 128

It is the unique identifier with which merchant refers to a customer object. It is used to access the saved payment methods, allow EMI transactions and setup subscriptions.
In case of a guest login, it should be an empty string.

Example:-
customer-id-007

                      customer_email
                      *
                      

string

required

Max Length : 300

Email address of the customer. If the backend gateway requires it, then you must send this value.

Constraints : You are allowed to use alphanumeric characters and the following special characters:!#$%&'*+-/=?^_.{|}~`@

_ and . cannot appear at the beginning or end of the local part of the email address (before and after the @ symbol).

Example:-
test@gmail.com

                      customer_phone
                      *
                      

string

required

Max Length : 300

Mobile number or fixed line number of the customer. If the backend gateway requires it, then you must send this value. We recommend passing a 10-digit number without including the "+91" or any mobile country code at the beginning.

Example:-
9999999912

                      mobile_country_code
                      
                      

String

Optional

Max Length :64

Your mobile's country code. No need to add prefix ‘+’ in front of it.

Example:- 65

                      payment_page_client_id
                      *
                      

string

required

A unique identifier of merchant. This is available in welcome e-mail shared by Juspay

Example:-
sampleMerchantId

                      action
                      *
                      

string

required

Value "paymentPage" is to start the Hypercheckout interface.

Value "paymentManagement" for deleting saved cards and linking/unlinking wallets.

Example:-
paymentPage

                      return_url
                      *
                      

string

required

Max Length : 255

A fully qualified URL on which the customer will be redirected after payment completion. It is also required to provide the control back to SDK after the completion of transaction. This URL takes higher precedence over the common return URL configured in your account settings.

NOTE:

URL shouldn't contain any query parameters or Ip address.
URL should be a valid HTTPS endpoint that is reachable from Juspay servers.
Return URL should not redirect to a different URL.
Please ensure to pass a valid return URL in the session API call or configure it on the Juspay Dashboard. Not doing the same will lead the SDK not being closed post transaction completion.

Example:-
https://shop.merchant.com

                      first_name
                      
                      

string

Max Length : 255

First Name of customer. This value will be used for customer identification.

Constraints : You are allowed to use alphanumeric characters and the following special characters: ().-_

Example:-
John

                      last_name
                      
                      

string

Max Length : 255

Last name of customer. This value will be used for customer identification.

Constraints : You are allowed to use alphanumeric characters and the following special characters: ().-_

Example:-
Wick

                      description
                      
                      

String

Max Length : 255

Description for order to be displayed to the user on amountBar.

Example:-
Complete your payment

                      currency
                      
                      

String

Case Sensitive

Currency for the order. Should only be passed when supported by the Payment Gateway and enabled in the Juspay Dashboard within EC Operations → PGCC → Select PG → Edit → Supported Currencies.

Default Value if not passed: INR
Note: The value must be in Uppercase

Example: USD

                      order_type
                      
                      

String

Conditional

Applicable only for TPV Orders.

Example:- TPV_PAYMENT

                      language
                      
                      

String

This field tells which language the payment page should be displayed in.

Example: english

                      order_fullfillment_threshold_in_mins
                      
                      

String

Optional

It only accepts integer values. For example, "60" is valid input but "60.00" is not valid.

Minimum value of amount should be 1.

                      metadata.JUSPAY:gateway_reference_id
                      
                      

string

Use this parameter only when you have use case of gateway reference ID. For detailed information check here.

                      metadata.webhook_url
                      
                      

String

Merchant can pass dynamic webhook URL in this field. The webhook authentication would be same as the one configured on the dashboard.

                      metadata.bank_account_details
                      
                      

Array

Conditional

Applicable for TPV Orders.

Either bank_account_number or bank_account_id is mandatory

                      bank_account_number
                      *
                      

String

Required

Customer Bank account

                      bank_ifsc
                      *
                      

String

Required

IFSC code of bank

                      juspay_bank_code
                      
                      

String

Optional

juspay bank code given in eligibility API. e.g. JP_HDFC

                      bank_beneficiary_name
                      
                      

String

Optional

Name of account holder

                      bank_account_id
                      
                      

String

Conditional

bank account id provided by Juspay while storing bank account details

                      bank_account_type
                      
                      

String

Conditional

Account Type of the Customer Account

Example:- CURRENT or SAVINGS

                      metadata.expiryInMins
                      
                      

String

Applicable for international merchants

                      metadata.txns.allow_card_no_3ds
                      
                      

boolean

Applicable for international merchants

                      options.create_mandate
                      *
                      

string

Required

Enum: 'REQUIRED' , "OPTIONAL'.

Defines what kind mandate support is available during a session. Required to create a Mandate.

Chose between the follow values based upon requirements :-

REQUIRED : Mandate is must for completing transaction. Only instruments which support Mandate will be shown
OPTIONAL : Mandate is a user choice for completing transaction.

Example:-
OPTIONAL

                      mandate.max_amount
                      *
                      

string

Required

This is the maximum amount which can be debited via mandate. Required, only when amount type is variable. If amount type is fixed, amount parameter itself will be considered as max amount.

Please be informed that the value assigned to "mandate.max_amount" will be displayed to the user when they open any UPI apps for payment. The value assigned to "amount" field will be used to show the amount on our Hypercheckout page

Example:-
1000.0

                      mandate.end_date
                      
                      

string

Optional

Mandate end date in UNIX EPOCH timestamp (UTC timezone). Post end date, mandate will move to EXPIRED state and recurring mandate will not be allowed.

Default: will be Mandate start date + 30 years

Example:-
1633088989

                      mandate.frequency
                      
                      

string

Defines the frequency of mandate execution, how often a customer should be charged.
Data type ENUM:
ONETIME (Supported only by UPI)
DAILY
WEEKLY
FORTNIGHTLY
MONTHLY
BIMONTHLY
QUARTERLY
HALFYEARLY
YEARLY
ASPRESENTED

Default: ASPRESENTED

Note:
1. Daily is not supported by Billdesk and Paytm (For cards)
2. In UPI AutoPay, ONETIME frequency, Mandate is valid only for 90 Days

Example:-
ASPRESENTED

                      mandate.rule_value
                      
                      

string

When frequency is passed as WEEKLY, FORTNIGHTLY, MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, or YEARLY then is it required that the exact day of the period should be passed.

1-7 when frequency is WEEKLY. In weekly, serial numbers start from Monday. Monday represents 1 and Sunday represents 7.

1-16 when 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-31 when frequency is MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, or YEARLY.

Not required when frequency is ONETIME, DAILY, 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

Example:-
1

                      mandate.amount_rule
                      
                      

string

Data type ENUM: FIXED, VARIABLE.
By default, it is considered as VARIABLE. In case of FIXED amount_rule

Example:-
FIXED

                      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.

Example:-
false

                      udf1 , udf2 , udf3 , udf4, udf5
                      
                      

string (Upto 255 characters)

No special characters supported

User Defined Parameter (UDF)

This field can be used to send any user defined parameters

The UDF parameters for orders can be seen in the JUSPAY dashboard under each order

Example:-
user5349

                      udf6 , udf7 , udf8 , udf9 , udf10
                      
                      

string (Upto 255 characters)

Special characters supported

User Defined Parameter (UDF)

This field can be used to send any user defined parameters

The UDF parameters for orders can be seen in the JUSPAY dashboard under each order

Example:-
user_5349

                      mutual_fund_details
                      
                      

List

Optional

This block contains the details of the Mutual Fund

NOTE: mutual_fund_details needs to be passed in a stringified format

                      memberId
                      *
                      

String

Mandatory

Member Id with ICCL or ARN_RIA with RTA

                      userId
                      *
                      

String

Mandatory

Client Id with ICCL or USER_CODE with RTA

                      mfPartner
                      *
                      

String

Mandatory

NSE/BSE/KFIN/CAMS

                      orderNumber
                      *
                      

String

Mandatory

Unique order number or application number of each MF

                      amount
                      *
                      

String

Mandatory

Individual MF amount within the array of MF being purchased in a single basket

                      investmentType
                      *
                      

String

Mandatory

LUMPSUM/SIP

                      schemeCode
                      
                      

String

Optional

Scheme Code of the MF (Mandatory for RTA reporting)

                      folioNumber
                      
                      

String

Optional

Folio Number of the MF (Mandatory for RTA reporting)

                      panNumber
                      
                      

String

Optional

PAN Number of the user, to be passed in UPPERCASE only (Mandatory for RTA reporting)

                      amcCode
                      
                      

String

Optional

AMC Code of the MF

                      ihNumber
                      
                      

String

Conditional

In-house Number of the SIP (Mandatory for K-Fin RTA)

Response Body

                      sdk_payload
                      
                      

JSON

Process SDK Call Payload. This is supposed to be passed to your frontend application to open the Hypercheckout screen.

                      payment_links
                      
                      

string

Https link using which user can open the Hypercheckout screen and perform transaction against the order created

                      order_id
                      
                      

string

Max Length : 21

Order Id passed during order creation

                      status
                      
                      

string

Max Length : 255

Status of order

Example:-
NEW

Response Body

                      status
                      
                      

string

Max Length : 255

Bad Request

                      error_code
                      
                      

string

Max Length : 255

Details of keys missing

Example:-
Mandatory fields are missing

                      error_message
                      
                      

string

Max Length : 255

Further Details of keys missing

Response Body

                      status
                      
                      

string

Max Length : 255

error

                      error_code
                      
                      

string

Max Length : 255

access_denied

Response Body

                      status
                      
                      

string

Max Length : 255

error

                      error_code
                      
                      

string

Max Length : 255

Internal server Error

Response Body

                      status
                      
                      

string

Max Length : 255

error

                      error_code
                      
                      

string

Max Length : 255

Internal server Error