--- page_title: Session API Payload product: tpv page_source: https://juspay.io/in/docs/tpv/docs/third-party-validation/session-api-payload llms_txt: https://juspay.io/in/docs/llms.txt product_llms_txt: https://juspay.io/in/docs/tpv/llms.txt --- # HyperCheckout SDK Payload To initiate TPV transaction, pass the following additional parameters in the Session API call. > **Note** > * For TPV payments, > > * `order_type` value be `TPV_PAYMENT`during payload creation for TPV transactions and it is mandatory field > * `metadata.bank_account_details` is mandatory parameter to be passed in TPV order creation request. Multiple linked bank account details can be passed in `metadata.bank_account_details` > * For TPV Emandate payments,Along with above additional TPV parameters, > > * `mandate.max_amount, mandate.start_date, mandate.end_date, mandate.frequency` are the additional parameters for TPV Emandate transactions > * `options.create_mandate` parameter value has to be passed as REQUIRED / OPTIONAL based on the business requirement ### Step 1.1. TPV parameters: ### Payload - **Order_type**: - Description: Applicable for TPV Orders. Value has to be `TPV_PAYMENT` - Value: value - Tags: String, Mandatory - **Metadata.bank_account_details**: - Description: Applicable for TPV Orders. - Value: - **Bank_account_number**: - Description: Customer Bank account - Tags: String, Mandatory - **Bank_ifsc**: - Description: IFSC code of bank - Tags: String, Mandatory - **Juspay_bank_code**: - Description: juspay bank code given in eligibility API. e.g. JP_HDFC - Tags: String, Optional - **Bank_beneficiary_name**: - Description: Name of account holder - Tags: String, Optional - Tags: Array, Mandatory ### Step 1.1. Mandate Parameters: ### Payload - **Options.create_mandate**: - Description: 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. - Value:

Example:-
OPTIONAL

- Tags: string, Required - **Mandate.max_amount**: - Description: This is the maximum amount which can be debited via mandate. Required, only when amount type is variable. If amount type is fixed, pass mandate max amount same as the order 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 - Value:

Example:-
1000.0

- Tags: string, Required - **Mandate.start_date**: - Description: Mandate start date in UNIX EPOCH timestamp (UTC timezone). The start date has to be today's date. **Default:** will be system date - Value:

Example:-
1633087969

- Tags: string, Optional - **Mandate.end_date**: - Description: 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 - Value:

Example:-
1633088989

- Tags: string, Optional - **Mandate.frequency**: - Description: 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 frequency is not supported by Billdesk and Paytm (For cards)2. In UPI AutoPay, for ONETIME frequency, Mandate is valid only for 90 Days - Value:

Example:-
ASPRESENTED

- Tags: string - **Mandate.rule_value**: - Description: 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 - Value:

Example:-
1

- Tags: string - **Mandate.amount_rule**: - Description: Defines the amount rule of the recurring debit. Data type **ENUM: FIXED, VARIABLE** . By default, it is considered as VARIABLE. - Value:

Example:-
FIXED

- Tags: string - **Mandate.block_funds**: - Description: 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. - Value:

Example:-
false

- Tags: Boolean Please find below the complete list of parameters for this API. ### Payload - **Order_id**: - Description: Unique Identifier for the order. Should be Alphanumeric with character length less than 21. - Value:

Example:-
order-id-9876580

- Tags: string, required - **Amount**: - Description: 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.Minimum value of amount should be INR 1. - Value:

Example:-
1.00

- Tags: string, required - **Customer_id**: - Description: 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. - Value:

Example:-
customer-id-007

- Tags: string, required - **Customer_email**: - Description: 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). - Value:

Example:-
test@gmail.com

- Tags: string, required - **Customer_phone**: - Description: 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. - Value:

Example:-
9999999912

- Tags: string, required - **Payment_page_client_id**: - Description: A unique identifier of merchant. This is available in welcome e-mail shared by Juspay - Value:

Example:-
sampleMerchantId

- Tags: string, required - **Action**: - Description: Value "paymentPage" is to start the Hypercheckout interface.Value "paymentManagement" for deleting saved cards and linking/unlinking wallets. - Value:

Example:-
paymentPage

- Tags: string, required - **Return_url**: - Description: 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** : 1. URL shouldn't contain any query parameters or Ip address. 2. URL should be a valid HTTPS endpoint that is reachable from Juspay servers. 3. Return URL should not redirect to a different URL. 4. 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. - Value:

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

- Tags: string - **First_name**: - Description: 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: `().-_` - Value:

Example:-
John

- Tags: string - **Last_name**: - Description: 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: `().-_` - Value:

Example:-
Wick

- Tags: string - **Description**: - Description: Description for order to be displayed to the user on amountBar. - Value:

Example:-
Complete your payment

- Tags: String - **Currency**: - Description: 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 - Tags: String, Case Sensitive - **Metadata.JUSPAY:gateway_reference_id**: - Description: **Use this parameter only when you have use case of gateway reference ID.** - Value:

Example:-
BUS

- Tags: string, Optional - **Metadata.webhook_url**: - Description: 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](https://merchant.juspay/response)** - Tags: String, Optional - **Metadata.bank_account_details**: - Description: Applicable for TPV Orders. Either bank_account_number or bank_account_id is mandatory - Value: - **Bank_account_number**: - Description: Customer Bank account - Tags: String, Conditional - **Bank_ifsc**: - Description: IFSC code of bank - Tags: String, Optional - **Juspay_bank_code**: - Description: juspay bank code given in eligibility API. e.g. JP_HDFC - Tags: String, Optional - **Bank_beneficiary_name**: - Description: Name of account holder - Tags: String, Optional - **Bank_account_id**: - Description: bank account id provided by Juspay while storing bank account details - Tags: String, Conditional - Tags: Array, Mandatory ## Sample Code Snippets: ### Sample Request: #### TPV Code Snippet: ```tpv 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":"3.00", "order_id":"yourUniqueOrderId", "customer_id":"yourUniqueCustId", "customer_phone":"9876543210", "customer_email":"dummyemail@gmail.com", "payment_page_client_id":"merchant", "action":"paymentPage", "order_type": "TPV_PAYMENT", "metadata.bank_account_details": "[{\"bank_account_number\":\"198731890\",\"bank_ifsc\":\"ICICI0000300\",\"bank_beneficiary_name\":\"TestName\"}]" }' ``` #### TPV Emandate Code Snippet: ```tpv emandate 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":"3.00", "order_id":"yourUniqueOrderId", "customer_id":"yourUniqueCustId", "customer_phone":"9876543210", "customer_email":"dummyemail@gmail.com", "payment_page_client_id":"merchant", "action":"paymentPage", "options.create_mandate":"OPTIONAL/REQUIRED", "mandate.max_amount":"1000.00", "mandate.start_date":"1644420442", "mandate.end_date":"1646234827", "order_type": "TPV_PAYMENT", "metadata.bank_account_details": "[{\"bank_account_number\":\"198731890\",\"bank_ifsc\":\"ICICI0000300\",\"bank_beneficiary_name\":\"TestName\"}]" }' ``` ### Sample Response: #### TPV: ```json { "status": "NEW", "id": "ordeh_cc7177bf16d", "order_id": "TEST", "payment_links": { "web": "https://sandbox.juspay.in/orders/ordeh_cc7177bf16d/payment-page", "expiry": null }, "sdk_payload": { "requestId": "8162c92851c8bd9", "service": "in.juspay.hyperpay", "payload": { "clientId": "TEST", "amount": "3.0", "merchantId": "TEST", "clientAuthToken": "tkn_20f89d52522335", "clientAuthTokenExpiry": "2024-02-14T10:36:13Z", "environment": "sandbox", "action": "paymentPage", "customerId": "9999999999", "currency": "INR", "customerPhone": "9999999999", "customerEmail": "test@gmail.com", "orderId": "TEST" } } } ``` #### TPV Emandate: ```plaintext { "status": "NEW", "id": "ordeh_cc7177bf16d", "order_id": "TEST", "payment_links": { "web": "https://sandbox.juspay.in/orders/ordeh_cc7177bf16d/payment-page", "expiry": null }, "sdk_payload": { "requestId": "8162c92851c8bd9", "service": "in.juspay.hyperpay", "payload": { "clientId": "TEST", "amount": "3.0", "merchantId": "TEST", "clientAuthToken": "tkn_20f89d52522335", "clientAuthTokenExpiry": "2024-02-14T10:36:13Z", "environment": "sandbox", "action": "paymentPage", "customerId": "9999999999", "currency": "INR", "customerPhone": "9999999999", "customerEmail": "test@gmail.com", "orderId": "TEST" } } } ```