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

Credit / Debit Card transaction

Compliance Check: Merchants who are not PCI DSS compliant should refrain from using this API and consume our PayV3.js for cards.

Scroll inside to view more

Supported Card Brand	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

                      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

Body

                      order_id
                      *
                      

string

Mandatory

order_id pertaining to the order for which the payment is started.

                      merchant_id
                      *
                      

string

Mandatory

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

                      payment_method_type
                      *
                      

string

Mandatory

Must be CARD.

                      payment_method
                      *
                      

string

Mandatory

One of VISA/MASTERCARD/MAESTRO/AMEX. 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

Mandatory

A valid credit/debit card number

                      name_on_card
                      
                      

string

Card holder name. Should contain alphabetical characters only.

                      card_exp_year
                      
                      

string

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

                      card_exp_month
                      
                      

string

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

                      card_security_code
                      
                      

string

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

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.

                      redirect_after_payment
                      
                      

boolean

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.

                      auth_type
                      
                      

String

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

                      tokenize
                      
                      

boolean

This is a boolean variable and accepts true/false. Required to be passed as true when card needs to be saved for future transactions.
(Note: This is an additional requirement along with save_to_locker)

                      authorization
                      
                      

Json

Optional

Autorization param to be passed to perform capture i.e. txn_type = CAPTURE passed in Order Create API

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

                      authentication
                      
                      

Json

Optional

Authentication params to be passed to perform the only authorization i.e. for txn_type = AUTHORIZATION | AUTHZ_CAPTURE passed in Order Create API

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

                      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_id
                      *
                      

string

Mandatory

order_id pertaining to the order for which the payment is started.

                      merchant_id
                      *
                      

string

Mandatory

ID of the merchant_account that you hold with us.

                      payment_method_type
                      *
                      

string

Mandatory

Must be CARD.

                      payment_method
                      *
                      

string

Mandatory

One of VISA/MASTERCARD/MAESTRO/AMEX. 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

Mandatory

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

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

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.

                      redirect_after_payment
                      
                      

boolean

                      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.

                      auth_type
                      
                      

String

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

                      authentication
                      
                      

Json

Optional

Authentication params to be passed to perform the only authorization i.e. for txn_type = AUTHORIZATION | AUTHZ_CAPTURE passed in Order Create API

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

                      authorization
                      *
                      

String

Mandatory

Authorization param to be passed to perform capture i.e. txn_type = CAPTURE passed in Order Create API

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

                      pre_auth_enabled
                      
                      

Boolean

Conditional

Response Body

                      order_id
                      
                      

string

:order_id

                      txn_id
                      
                      

string

:txn_id

                      status
                      
                      

string

PENDING_VBV

                      payment
                      
                      

object

                      authentication.method
                      
                      

string

                      authentication.url
                      
                      

String

Response Body

                      status
                      
                      

string

error

                      error_message
                      
                      

string

Order timed out

                      error_code
                      
                      

string

invalid_request

Common Error Codes:

Scroll inside to view more

Scenario	Error Codes	Description	Sample Error Message
For New card - Transaction without passing card number	400	Bad Request	{"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	Bad Request	{"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	Bad Request	{"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"}}
Passing a non configured currency	400	Bad Request	{"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 order_id field	400	Bad Request	{"error_message":"[order id] cannot be null","status":"invalid_request_error","error_code":"blank","error_info":{"user_message":"Cannot process your request. Please contact support team for assistance.","fields":[{"field_name":"order_id","reason":"Missing field."}],"developer_message":"Missing order id. Please pass order_id or order payload.","code":"MISSING_MANDATORY_PARAMETER","category":"USER_ERROR"}}
Invalid order_id	400	Bad Request	{"status":"NOT_FOUND","error_info":{"user_message":"Order Not Found","fields":[{"field_name":"order_id","reason":"Invalid order_id."}],"developer_message":"order not found. please pass a valid order_id for the given merchant.","code":"RESOURCE_NOT_FOUND","category":"USER_ERROR"},"status_id":40}
Not passing card expiry year	400	Bad Request	{"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"}}
Not passing card expiry month	400	Bad Request	{"error_message":"Missing card expiry month","status":"invalid_request_error","error_code":"missing_card_exp_month","error_info":{"user_message":"Please enter valid card expiry month.","fields":[{"field_name":"card_exp_month","reason":"Missing field."}],"developer_message":"Missing card expiry month. Card expiry month is mandatory for this card brand.","code":"MISSING_MANDATORY_PARAMETER","category":"USER_ERROR"}}
Invalid card number	400	Bad Request	{"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	Bad Request	{"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	Bad Request	{"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"}}
Not passing payment method	400	Bad Request	{"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	Bad Request	{"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"}}
Passing a non configured currency	400	Bad Request	{"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 PROMPTPAY payment method.","code":"GATEWAY_NOT_FOUND","category":"CONFIG_ERROR"}}

For Pre-auth and Capture:

Scroll inside to view more

Scenario	Error Codes	Description	Sample Error Message
Transaction without passing coma before the pre_auth_enabled field	400	Bad Request	{"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 pre_auth_enabled field	400	Bad Request	{"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