--- page_title: Card transaction API product: EC API Global page_source: https://juspay.io/sea/docs/ec-api-global/docs/order--payment-api-integration/card-transaction-api openapi: https://juspay.io/sea/docs/api/swagger?document=https%3A%2F%2Fjuspay.io%2Fsea%2Fdocs%2Fec-api-global%2Fdocs%2Forder--payment-api-integration%2Fcard-transaction-api llms_txt: https://juspay.io/sea/docs/llms.txt product_llms_txt: https://juspay.io/sea/docs/ec-api-global/llms.txt --- ## API Version: default # Credit / Debit Card transaction > **Note** > * **Compliance Check:** Merchants who are not PCI DSS compliant should refrain from using this API and consume our [PayV3.js](https://juspay.io/sea/docs/payv3) for cards. | 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 | ## Endpoints: - Sandbox: https://sandbox.juspay.in/txns - Production: https://api.juspay.in/txns ## Request Type: POST ## Headers: #### x-merchantid: Unique identifier for the merchant. This is the Merchant ID provided by Juspay. The value is case sensitive. > **Note** > Passing this value will help us route efficiently at network level. - Value: x-merchantid: testaccount - Tags: String, Recommended ## Sample Code Snippets: ### Sample Request: #### New Card Transaction Code Snippet: ```new card transaction curl --location 'https://api.juspay.in/txns' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic xxx==xxx345' \ --header 'x-merchantid: your_merchant_id' \ --data-urlencode 'merchant_id=:merchant_id' \ --data-urlencode 'payment_method_type=CARD' \ --data-urlencode 'payment_method=VISA' \ --data-urlencode 'card_number=485498988654599015'\ --data-urlencode 'card_exp_month=07'\ --data-urlencode 'card_exp_year=24'\ --data-urlencode 'name_on_card=Name'\ --data-urlencode 'card_security_code=808'\ --data-urlencode 'save_to_locker=true'\ --data-urlencode 'tokenize=true'\ --data-urlencode 'auth_type=NO_THREE_DS' --data-urlencode 'redirect_after_payment=true' \ --data-urlencode 'format=json' \ --data-urlencode 'order_id=:ord_orderid' ``` #### Stored Card Transaction Code Snippet: ```stored card transaction curl --location 'https://api.juspay.in/txns' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic xxx==xxx345' \ --header 'x-merchantid: your_merchant_id' \ --data-urlencode 'merchant_id=:merchant_id' \ --data-urlencode 'payment_method_type=CARD' \ --data-urlencode 'payment_method=VISA' \ --data-urlencode 'card_token=tkn_4ce192bbc23f987568524f28159bfa3'\ --data-urlencode 'card_security_code=808'\ --data-urlencode 'auth_type=NO_THREE_DS' \ --data-urlencode 'redirect_after_payment=true' \ --data-urlencode 'format=json' \ --data-urlencode 'order.order_id=:ord_orderid' ``` ### Sample Response: #### Response: ```json { "order_id": ":order_id", "txn_id": ":txn_id", "status": "PENDING_VBV", "payment": { "authentication": { "method": "GET", "url": "https://api.juspay.in/pay/start/guest/8646a7a0xxx74fxxxx95fec00340a507" } } } ``` ## Body Parameters: ### New Card Transaction: #### order_id: - Description: order_id pertaining to the order for which the payment is started. - Tags: string, Mandatory #### merchant_id: - Description: ID of the merchant_account that you hold with us.(Merchant ID provided by Juspay or Juspay's merchant id) - Tags: string, Mandatory #### payment_method_type: - Description: Must be CARD. - Tags: string, Mandatory #### payment_method: - Description: 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. - Tags: string, Mandatory #### card_number: - Description: A valid credit/debit card number - Tags: string, Mandatory #### name_on_card: - Description: Card holder name. Should contain alphabetical characters only. - Tags: string #### card_exp_year: - Description: Represent the expiry year of the card as YY (two digits only) - Tags: string #### card_exp_month: - Description: Represent the expiry month of the card as MM (two digits only) - Tags: string #### card_security_code: - Description: 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 - Tags: string #### save_to_locker: - Description: 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. - Tags: boolean #### redirect_after_payment: - Description: 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. - Tags: boolean #### format: - Description: 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. - Tags: String, Mandatory #### auth_type: - Description: auth_type refers to authorization type of the transactionNO_THREE_DS => for non 3DS transactionTHREE_DS => for 3DS transaction - Tags: String #### tokenize: - Description: 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) - Tags: boolean #### authorization: - Description: Autorization param to be passed to perform capture i.e. txn_type = CAPTURE passed in Order Create API #### Authorization parameters Code Snippet: ```authorization parameters curl --location --request POST 'https://api.juspay.in/session' \ --header 'x-merchantid: yourMerchantId' \ --header 'Authorization: Basic base64encodedkey==' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount":"10.00", "order_id":"yourUniqueOrderId", "customer_id":"dummyCustId", "customer_phone":"9876543210", "customer_email":"dummyemail@gmail.com", "payment_page_client_id":"", "action":"paymentPage" }' ``` - Tags: Json, Optional #### authentication: - Description: Authentication params to be passed to perform the only authorization i.e. for txn_type = AUTHORIZATION | AUTHZ_CAPTURE passed in Order Create API #### Authentication parameters Code Snippet: ```authentication parameters curl --location --request POST 'https://api.juspay.in/session' \ --header 'x-merchantid: yourMerchantId' \ --header 'Authorization: Basic base64encodedkey==' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount":"10.00", "order_id":"yourUniqueOrderId", "customer_id":"dummyCustId", "customer_phone":"9876543210", "customer_email":"dummyemail@gmail.com", "payment_page_client_id":"", "action":"paymentPage" }' ``` - Tags: Json, Optional #### pre_auth_enabled: - Description: 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 - Tags: Boolean, Conditional ### Saved Card Transaction: #### order_id: - Description: order_id pertaining to the order for which the payment is started. - Tags: string, Mandatory #### merchant_id: - Description: ID of the merchant_account that you hold with us. - Tags: string, Mandatory #### payment_method_type: - Description: Must be CARD. - Tags: string, Mandatory #### payment_method: - Description: 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. - Tags: string, Mandatory #### card_token: - Description: 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. - Tags: string, Mandatory #### card_security_code: - Description: 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 - Tags: string #### save_to_locker: - Description: 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. - Tags: boolean #### redirect_after_payment: - Description: 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. - Tags: boolean #### format: - Description: 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. - Tags: string, Mandatory #### auth_type: - Description: auth_type refers to authorization type of the transactionNO_THREE_DS => for non 3DS transactionTHREE_DS => for 3DS transaction - Tags: String #### authentication: - Description: Authentication params to be passed to perform the only authorization i.e. for txn_type = AUTHORIZATION | AUTHZ_CAPTURE passed in Order Create API #### Authentication parameters Code Snippet: ```authentication parameters curl --location --request POST 'https://api.juspay.in/session' \ --header 'x-merchantid: yourMerchantId' \ --header 'Authorization: Basic base64encodedkey==' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount":"10.00", "order_id":"yourUniqueOrderId", "customer_id":"dummyCustId", "customer_phone":"9876543210", "customer_email":"dummyemail@gmail.com", "payment_page_client_id":"", "action":"paymentPage" }' ``` - Tags: Json, Optional #### authorization: - Description: Authorization param to be passed to perform capture i.e. txn_type = CAPTURE passed in Order Create API #### Authorization parameters Code Snippet: ```authorization parameters curl --location --request POST 'https://api.juspay.in/session' \ --header 'x-merchantid: yourMerchantId' \ --header 'Authorization: Basic base64encodedkey==' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount":"10.00", "order_id":"yourUniqueOrderId", "customer_id":"dummyCustId", "customer_phone":"9876543210", "customer_email":"dummyemail@gmail.com", "payment_page_client_id":"", "action":"paymentPage" }' ``` - Tags: String, Mandatory #### pre_auth_enabled: - Description: 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 - Tags: Boolean, Conditional ## API Responses: ### 200: #### order_id: - Description: :order_id - Tags: string #### txn_id: - Description: :txn_id - Tags: string #### status: - Description: PENDING_VBV - Tags: string #### payment: - Value: - **Authentication.method**: - Tags: string - **Authentication.url**: - Tags: String - Tags: object ### 400: #### status: - Description: error - Tags: string #### error_message: - Description: Order timed out - Tags: string #### error_code: - Description: invalid_request - Tags: string ## Common Error Codes: | 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: | 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"}} | --- ## See Also - [3.3.2 Order Status API](https://juspay.io/sea/docs/ec-api-global/docs/order--payment-api-integration/32-order-status-api) - [Card Info](https://juspay.io/sea/docs/ec-api-global/docs/order--payment-api-integration/card-info)