Body
Session API
This is a Server-to-Server API that takes order parameters as an input and returns the SDK payload and the payment link.
This also creates order in the Juspay system.
Request
Response
API Endpoints
Sandbox Link
POST
https://api.sandbox.juspay.io/session
Production Link
POST
https://api.juspay.io/session
Authorization Header
Basic Auth
*
Base64 Encoded username:password
required
Consists of two parts.
Username: API Key obtained from Juspay dashboard
Password: Empty string
Example:-
Basic LIR2UUZEQzhFQTY0OUU5QTIxQzNFNTQwNkFDMEZCOg==
Headers
x-merchantid
*
String
Required
Merchant ID provided by Juspay or Juspay's merchant id.
Content-Type
*
String
Required
Value: application/json
Request Schema: application/json
Basic Parameters
order_id
*
string
required
Max Length :21
Unique Identifier for the order. Should be Alphanumeric with character length less than 21.
Example:-
order-id-9876580
amount
*
Double
required
Amount that the customer has to pay. Will accept 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.
Example:-
1.00
customer_id
*
string
required
Max Length :300
It is the ID with which merchant refers to a customer object. This id is used to access the stored payment methods, allow instalment transactions and setup subscriptions.
In case of 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 "+55" or any mobile country code at the beginning.
Example:-
9999999912
payment_page_client_id
*
string
required
A unique identifier of merchant for all client-side requests. 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 managing saved cards or other payment Instruments like wallets, Pix consents etc.
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 page header.
Example:-
Complete your payment
identity_credentials
String
The identity_credentials field is used to capture the customer identifier required by payment gateways. It should contain at least one of the following customer identifiers: CPF, CNPJ, or PIX key. If not provided upfront, this information can alternatively be collected dynamically on the payment page after the user selects the payment method.
cpf
String
Optional
cnpj
String
Optional
pix_key
String
Optional
account_registration_date
String
Optional
This is the date when customer registered with the business, its a mandatory field for Pix Biometric Flow.
It is used as a risk signal to understand the customer profile
Example: 2020-12-03 (YYYY-MM-DD)
Metadata Object
metadata.JUSPAY:gateway_reference_id
string
Max Length :255
You will have to mandatorily pass this reference id if you created a gateway with gateway reference id on Juspay's dashboard. For detailed information check here
.
Mandate Parameters
options.create_mandate
*
string
Required
Enum: 'REQUIRED' , "OPTIONAL'.
Defines what kind mandate for cards or consent for Pix support is available during a session. Required to create a Mandate for card and other payment Instrument and long-term consent for Pix Automatico.
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
*
Double
Mandatory
Max Length : 8
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.
mandate.start_date
*
string
Required
Max Length :10
Mandate start date in UNIX EPOCH timestamp (UTC timezone). The start date has to be today's date
Example:-
1633087969
mandate.end_date
*
string
Required
Max Length :10
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. By default value 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
DAILY
WEEKLY
FORTNIGHTLY
MONTHLY
BIMONTHLY
QUARTERLY
HALFYEARLY
YEARLY
ASPRESENTED
Default: ASPRESENTED
Note:
1. In AutoPay, ONETIME frequency, Mandate is valid only for 90 Days
Example:-
ASPRESENTED
mandate.rule_value
string
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.
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.revokable_by_customer
Boolean
If false, the mandate cannot be revoked by the customer once set. Applicable only for mandate. It should be true for Recurring and true/false for ONETIME. By default value will be true
Example:-
false
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
metadata.CIELO:authorizeNow
*
String
Mandatory
Required if you are using CIELO gateway.
Set "metadata.CIELO:AauthorizeNow": “true” first charge to be made at the time of subscription.
Example:- true
mandate.min_amount
Double
Max Length :8
This is the minimum amount which should be debited via mandate for the least. Required, only when amount type is variable. If amount type is fixed, amount parameter itself will be considered as max amount.
This is a required field for Pix Automatico.
User Defined Parameters (UDF)
udf1 , udf2 , udf3 , udf4, udf5
string (Upto 255 characters)
No special characters supported
Max Length :255
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
Max Length :255
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
200 : Success
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
Order Id passed during order creation
status
string
Status of order
Example:-
NEW
400 : Invalid Input data
Response Body
status
string
Bad Request
error_code
string
Details of keys missing
Example:-
Mandatory fields are missing
error_message
string
Further Details of keys missing
401 : Authentication Failed
Response Body
status
string
error
error_code
string
access_denied
404 : Not Found
Response Body
status
string
error
error_code
string
Internal server Error
500 : Unexpected Error
Response Body
status
string
error
error_code
string
Internal server Error
Have questions?
- Need help? Contact support
- LLM? Read llms.txt