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

Create Order with Payments

This API creates an order and initiates the transaction consecutively. Both order creation parameters and payment details must be passed in this API. Parameters need to included in format order.<parameter_name>. For example, order.metadata.JUSPAY:gateway_reference_id.

Scroll inside to view more

Supported Card Brands	payment_method
Sodexo	SODEXO
Mastercard	MASTER
Visa	VISA
Rupay	RUPAY
American Express	AMEX
Discover	DISCOVER
Diners	DINERS
Maestro	MAESTRO
JCB	JCB
BAJAJ Cards	BAJAJ
KNEt Cards	KNET
MADA Cards	MADA
QPay Cards	QPAY
QWIKCILVER Gift Cards	QWIKCILVER
China UnionPay	UNIONPAY

Request

Response

API Endpoints

Sandbox Link

POST

https://sandbox.juspay.in/txns

Production Link

POST

https://api.juspay.in/txns

                      Basic Auth
                      *
                      

Base64 Encoded Username:Password

Required

Consists of two parts.

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

Example:- Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==

                      x-merchantid 
                      
                      

String

Recommended

Unique identifier for the merchant. This is the Merchant ID provided by Juspay. The value is case sensitive.

Passing this value will help us route efficiently at network level.

Example:- x-merchantid: testaccount

                      Content-Type
                      *
                      

String

Required

application/x-www-form-urlencoded

                      version
                      
                      

String

Optional

Pass the date in YYYY-MM-DD format.
Note: If a version is provided, the response will include data corresponding to that specific version date.

It is recommended not to enforce strict validation on the entire response on the merchant's side to allow for future key additions.

Body

Request Schema: application/json

                      key
                      *
                      

String

Mandatory

                      order.order_id
                      *
                      

String

Required

Unique Identifier for the order. Should be Alphanumeric with character length less than 21.

Example:-
order-id-9876580

                      order.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.

Creating an order with a "0" amount is feasible. Please contact the Juspay team for internal enablement.

                      order.customer_id
                      
                      

String

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

Example:-
customer-id-007

                      order.customer_email
                      
                      

String

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

Example:-
test@gmail.com

                      order.customer_phone
                      
                      

String

Mobile number or fixed line number of the customer. If the backend gateway requires it, then you must send this value.

Example:-

9999999912

                      order.currency
                      
                      

String

ISO string of the currency. Accepted values are BRL, EUR, USD, GBP,HKD. Default value: INR

                      order.return_url
                      
                      

String

A fully qualified URL 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 shouldn't contain any query parameters or Ip address. This URL takes higher precedence over the common return URL configured in your account settings.

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

                      merchant_id
                      *
                      

String

Required

ID of the merchant_account that you hold with us.
(Merchant ID provided by Juspay or Juspay's merchant id.)

                      payment_method_type
                      *
                      

String

Required

Depending on type of payment to be processed.

Example:-
CARD

                      payment_method
                      
                      

String

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.

                      card_number
                      *
                      

String

Required

A valid credit/debit card number

                      name_on_card
                      
                      

String

Card holder name. Should contain alphabetical characters only.

                      card_exp_year
                      *
                      

String

Required

Represent the expiry year of the card as YY (two digits only)

                      card_exp_month
                      *
                      

String

Required

Represent the expiry month of the card as MM (two digits only)

                      card_security_code
                      *
                      

String

Required

CVV of the card. Usually three digits. Optional for all VISA saved cards, SODEXO saved cards, and saved cards of select issuing banks of MASTERCARD

                      save_to_locker
                      
                      

Boolean

Optional

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. Only applicable for international cards.

                      redirect_after_payment
                      *
                      

Boolean

Mandatory

This is a boolean variable and accepts true/false. 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

Mandatory

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.

                      order.txn_type
                      
                      

String

Conditional

Type of the transaction, please pass the following details
1. AUTHENTICATION => To perform authentication only
2. AUTHORIZATION => To perform authorization only
3. CAPTURE => To Perform Standalone capture
4. AUTHN_AUTHZ => To Perform Authentication and Authorization
5. AUTHZ_CAPTURE => To Perform Authorization and capture

                      authentication
                      
                      

json

Optional

Authentication params to be passed to perform the only authorization i.e. for order.txn_type = AUTHORIZATION | AUTHZ_CAPTURE

              
                {
  "eci": "",
  "cavv": "",
  "threeDSVersion": "",
  "threeDSTransStatusReason": "",
  "threeDSServerTransID": "",
  "threeDSTransStatus": "",
  "cavvAlgorithm": "",
  "threeDSTransId": ""
}

                      authorization
                      
                      

Json

Optional

Autorization param to be passed to perform capture i.e. order.txn_type = CAPTURE

              
                {
  "authIdCode": "",
  "acquirerBin": "",
  "acquirerMid": "",
  "mcc": "",
  "merchantName": ""
}

                      auth_type
                      
                      

String

optional

auth_type refers to authorization type of the transaction
NO_THREE_DS => for non 3DS transaction
THREE_DS => for 3DS transaction

                      order.metadata.txns.allow_card_no_3ds
                      
                      

Boolean

Optional

Set it to true if you want no Two Factor Authentication(2FA) where transaction gets successful once it is initiated.

                      order.udf1
                      *
                      

string

Mandatory

Max Length : 255 characters

No Special Characters Supported

User Defined Functions (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.
User Defined parameters can be passed in any of the 10 supported fields from udf1 to udf10.

                      order.metadata.txns.auto_capture
                      
                      

Boolean

Set it to true if you want to use pre auth and capture.

                      order.metadata.JUSPAY:gateway_reference_id
                      
                      

String

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

                      order.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. Ex: metadata.webhook_url=https://merchant.juspay/response

                      pre_auth_enabled
                      
                      

Boolean

Conditional

If the parameter metadata.txns.auto_capture is not passed during order creation and the transaction needs to be converted to an authorization and capture transaction, this parameter can be utilized.

Set to true for pre-auth and Capture transactions

                      order.order_id
                      *
                      

String

Required

Unique Identifier for the order. Should be Alphanumeric with character length less than 21.

Example:-
order-id-9876580

                      order.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.

                      order.customer_id
                      
                      

String

Example:-
customer-id-007

                      order.customer_email
                      
                      

String

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

Example:-
test@gmail.com

                      order.customer_phone
                      
                      

String

Mobile number or fixed line number of the customer. If the backend gateway requires it, then you must send this value.

Example:-

9999999912

                      order.currency
                      
                      

String

ISO string of the currency. Accepted values are BRL, EUR, USD, GBP,HKD. Default value: INR

                      order.return_url
                      
                      

String

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

                      merchant_id
                      *
                      

String

Required

ID of the merchant_account that you hold with us.
(Merchant ID provided by Juspay or Juspay's merchant id.)

                      payment_method_type
                      *
                      

String

Required

Depending on type of payment to be processed.

Example:-
CARD

                      payment_method
                      
                      

String

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.

                      card_token
                      *
                      

String

Required

A valid card token obtained using /card/list API. If you send this parameter, then card_number, name_on_card, card_exp_year, 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.

                      card_security_code
                      *
                      

String

Required

CVV of the card. Usually three digits. Optional for all VISA saved cards, SODEXO saved cards, and saved cards of select issuing banks of MASTERCARD

                      redirect_after_payment
                      *
                      

Boolean

Mandatory

                      format
                      *
                      

String

Mandatory

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.

                      order.txn_type
                      
                      

String

Conditional

                      authentication
                      
                      

json

Optional

Authentication params to be passed to perform the only authorization i.e. for order.txn_type = AUTHORIZATION | AUTHZ_CAPTURE

              
                {
  "eci": "",
  "cavv": "",
  "threeDSVersion": "",
  "threeDSTransStatusReason": "",
  "threeDSServerTransID": "",
  "threeDSTransStatus": "",
  "cavvAlgorithm": "",
  "threeDSTransId": ""
}

                      authorization
                      
                      

Json

Optional

Autorization param to be passed to perform capture i.e. order.txn_type = CAPTURE

              
                {
  "authIdCode": "",
  "acquirerBin": "",
  "acquirerMid": "",
  "mcc": "",
  "merchantName": ""
}

                      auth_type
                      
                      

String

optional

auth_type refers to authorization type of the transaction
NO_THREE_DS => for non 3DS transaction
THREE_DS => for 3DS transaction

                      order.metadata.txns.allow_card_no_3ds
                      
                      

Boolean

Optional

Parameter to define the authentication method,

Set to true for no Two Factor Authentication(2FA) where transaction gets successful once it is initiated..
Set to false for standard Two Factor Authentication(2FA).

                      order.udf1
                      *
                      

string

Mandatory

Max Length : 255 characters

No Special Characters Supported

                      order.metadata.txns.auto_capture
                      
                      

Boolean

A parameter to determine the capture method,

Set to false for pre-auth and capture.
Set to true for automatic capture.

                      order.metadata.JUSPAY:gateway_reference_id
                      
                      

String

conditional

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.

                      order.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. Ex: metadata.webhook_url=https://merchant.juspay/response

                      pre_auth_enabled
                      
                      

Boolean

Conditional

Response Body

                      order_id
                      
                      

String

:order_id

                      txn_id
                      *
                      

String

Mandatory

                      status
                      
                      

String

PENDING_VBV

                      payment
                      
                      

Object

                      authentication.method
                      
                      

String

                      authentication.url
                      
                      

String

                      txn_uuid
                      
                      

String

:txn_uuid

                      offer_details
                      
                      

Object

                      offers
                      
                      

Array of Strings

Offer ID’s passed in transaction

Response Body

                      status
                      
                      

String

error

                      error_message
                      *
                      

String

Mandatory

invalid_card_number

                      error_code
                      *
                      

String

Mandatory

invalid_request

Error Codes:

Scroll inside to view more

Scenario	Error Codes	Sample Error Message
Not passing the currency value	400	{"error_message":"Bad Request.","status":"Bad Request","error_code":"INVALID_REQUEST","error_info":{"user_message":"Invalid input data","fields":[{"field_name":"currency","reason":"Missing field or Invalid Value"}],"developer_message":"Invalid input data","code":"INVALID_INPUT","category":"USER_ERROR"}}
Not passing the amount value	400	{"error_message":"Bad Request.","status":"Bad Request","error_code":"INVALID_REQUEST","error_info":{"user_message":"Invalid input data","fields":[{"field_name":"amount","reason":"Missing field or Invalid Value"}],"developer_message":"Invalid input data","code":"INVALID_INPUT","category":"USER_ERROR"}
Passing the amount in negative Integer	400	{"error_message":"Bad Request.","status":"Bad Request","error_code":"INVALID_REQUEST","error_info":{"user_message":"Invalid input data","fields":[{"field_name":"amount","reason":"Invalid amount"}],"developer_message":"Invalid input data","code":"INVALID_INPUT","category":"USER_ERROR"}}
Passing the amount in Positive Integer	400	{"error_message":"BadRequest.","status":"Bad Request","error_code":"INVALID_REQUEST","error_info":{"user_message":"Invalid input data","fields":[{"field_name":"amount","reason":"Missing field or Invalid Value"}],"developer_message":"Invalid input data","code":"INVALID_INPUT","category":"USER_ERROR"}}
Not passing the customer_email	400	{"status":"error","error_code":"invalid_request","error_info":{"user_message":"Invalid customer Email","fields":[{"field_name":"customerEmail","reason":"Invalid value."}],"developer_message":"customerEmail shouldn't have any special chars","code":"INVALID_INPUT","category":"USER_ERROR"}}
Not passing the orderId	400	{"error_message":"order_id is missing","status":"Bad Request","error_code":"order_id is missing","error_info":{"user_message":"Please pass order_id in request","fields":[{"field_name":"order_id","reason":"Missing field."}],"developer_message":"order_id is missing in request","code":"MISSING_MANDATORY_PARAMETER","category":"USER_ERROR"}}
Not passing API key	403	{"error":true,"error_message":"Forbidden.No valid API key or client auth token is present in Authorization header or client_auth_token query parameter","user_message":"Access Denied.Unable to proceed.","userMessage":"Access Denied.Unable to proceed.","error_info":{"code":"UNAUTHORIZED","category":"USER_ERROR","user_message":"AccessDenied","developer_message":"No valid API key or client auth token is present in Authorization header or client_auth_token query parameter"}}
Invalid API key	401	{"status":"error","error_code":"access_denied","error_info":{"user_message":"Unauthorized.","developer_message":"Invalid API Key.Please pass a valid and active apikey.","code":"UNAUTHORIZED","category":"USER_ERROR"}}
Whitelisting of IP in dashboard	403	{"error":true,"error_message":"Internal Server error.","user_message":"Bad Origin.","error_info":{"code":"BAD_ORIGIN","category":"USER_ERROR","user_message":"Bad Origin.","developer_message":"IP Verification Failed"}}
Passing amount as 0(without Juspay internal enablement)	400	{"error_message":"Bad Request.","status":"ERROR","error_code":"INVALID_REQUEST","error_info":{"user_message":"Invalid input data","fields":[{"field_name":"amount","reason":"Invalid amount"}],"developer_message":"Invalid input data","code":"INVALID_INPUT","category":"USER_ERROR"}}'
Passing a non configured currency	400	{"error_message":"Can't find a suitable gateway to process the transaction","status":"Bad Request","error_code":"invalid_request_error","error_info":{"user_message":"Gateway not found to process the transaction request.","developer_message":"No functional gateways after filtering for currency THB","code":"GATEWAY_NOT_FOUND","category":"CONFIG_ERROR"}}
Not passing payment method	400	{"error_message":"Payment method type cannot be null","status":"invalid_request_error","error_code":"missing_payment_method_type","error_info":{"user_message":"Please pass payment method type in the request.","fields":[{"field_name":"payment_method_type","reason":"Missing field."}],"developer_message":"Missing payment method type in the request. Payment method type is a mandatory parametere.","code":"MISSING_MANDATORY_PARAMETER","category":"USER_ERROR"}}
Not passing payment method type	400	{"error_message":"Payment method cannot be null","status":"invalid_request_error","error_code":"missing_payment_method","error_info":{"user_message":"Cannot process your request. Please contact support team for assistance.","fields":[{"field_name":"payment_method","reason":"Missing field."}],"developer_message":"Missing payment method. Payment method is required for provided payment method type.","code":"MISSING_MANDATORY_PARAMETER","category":"USER_ERROR"}}
For New card - Transaction without passing card number	400	{"error_message":"Card number is required.","status":"invalid_request_error","error_code":"missing_card_number","error_info":{"user_message":"Please enter a valid card number.","fields":[{"field_name":"card_number","reason":"Missing field."}],"developer_message":"Missing card number.","code":"MISSING_MANDATORY_PARAMETER","category":"USER_ERROR"}}
Not passing merchant_id field	400	{"error_message":"Bad request.","status":"ERROR","error_code":"Bad request.","error_info":{"user_message":"Bad request.","fields":[{"field_name":"merchant_id","reason":"Field required but not passed."}],"developer_message":"Failed while parsing your request.","code":"MISSING_MANDATORY_PARAMETER","category":"USER_ERROR"}}
Transaction without passing card_security_code field	400	{"error_message":"Can't find a suitable gateway to process the transaction","status":"Bad Request","error_code":"invalid_request_error","error_info":{"user_message":"Gateway not found to process the transaction request.","developer_message":"No functional gateways supporting this transaction.","code":"GATEWAY_NOT_FOUND","category":"CONFIG_ERROR"}}
Not passing card expiry year	400	{"error_message":"Bad request.","status":"ERROR","error_code":"Bad request.","error_info":{"user_message":"Bad request.","fields":[{"field_name":"merchant_id","reason":"Field required but not passed."}],"developer_message":"Failed while parsing your request.","code":"MISSING_MANDATORY_PARAMETER","category":"USER_ERROR"}}
Invalid card number	400	{"error_message":"Card number is invalid.","status":"invalid_request_error","error_code":"invalid_card_number","error_info":{"user_message":"Cannot process your request. Please contact support team for assistance.","fields":[{"field_name":"card_number","reason":"Invalid value."}],"developer_message":"Invalid card number. Card number should contain only digits and should pass luhn check.","code":"INVALID_INPUT","category":"USER_ERROR"}}
Invalid card expiry month	400	{"error_message":"Invalid expiry month.","status":"invalid_request_error","error_code":"invalid_expiry_month","error_info":{"user_message":"Please enter valid card expiry month.","fields":[{"field_name":"card_exp_month","reason":"Invalid value."}],"developer_message":"Invalid card expiry month. Expiry month cannot be greater than 12 and less than 1","code":"INVALID_INPUT","category":"USER_ERROR"}}
Invalid card expiry year	400	{"error_message":"Card already expired.","status":"invalid_request_error","error_code":"card_expired","error_info":{"user_message":"Card expired.","developer_message":"Card expired. Card expiry year/month cannot be less than current year/month.","code":"INVALID_INPUT","category":"USER_ERROR"}}
For pre-auth and capture, Transaction without passing pre_auth_enabled field	400	{"error_message":"Bad request.","status":"ERROR","error_code":"Bad request.","error_info":{"user_message":"Bad request.","fields":[{"field_name":"merchant_id","reason":"Field required but not passed."}],"developer_message":"Failed while parsing your request.","code":"MISSING_MANDATORY_PARAMETER","category":"USER_ERROR"}}

Have questions?
Need help? Contact support
LLM? Read llms.txt