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

Process Payload

Payload for Process SDK

Since the SDK is an enhanced Payments Orchestrator, the payload to Process SDK is typically a bunch of basic Payments payload parameters. Merchants must make sure to add these required metrics while invoking Payments SDK. These parameters are crucial in initiating the SDK and for analytical purposes. Find below the steps to create the set of parameters which needs to be passed in the payload:

Step 1

Create OrderDetails Payload

Using your cart information, create the orderDetails payload as given below

                      Base Parameters
                      
                      

                      order_id
                      
                      

String

Conditional

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

Example:-
order-id-9876580

If you have enabled paymentAttempt event, then you can send order_id in resumePayment event.

                      merchant_id
                      *
                      

String

Mandatory

Merchant ID provided by Juspay during onboarding

                      amount
                      *
                      

String

Mandatory

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

                      timestamp
                      *
                      

String

Mandatory

Epoch Unix timestamp in milliseconds

Example:-
1695029591000

                      customer_id
                      *
                      

String

Mandatory

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

                      customer_email
                      *
                      

String

Mandatory

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

Mandatory

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.

Example:-
9999999912

                      return_url
                      *
                      

String

Mandatory

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

                      features
                      
                      

String

Optional

                      paymentAttempt
                      
                      

String

Optional

                      enabled
                      
                      

Boolean

Optional

When passed as true merchant receives a payment attempt when the user clicks on proceed to pay on the payment page. Sample event - https://juspay.io/in/docs/payment-page-enterprise/web/resources/order-updation-events#2.-paymentAttempt-Event

Example:- true/false

                      order_type
                      
                      

String

Conditional

Applicable only for TPV Orders.

Example:- Eg: TPV_PAYMENT

                      Mandate/Subscriptions Parameters Parameters
                      
                      

                      options.create_mandate
                      *
                      

String

Mandatory

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.

Example:-
OPTIONAL

                      mandate.max_amount
                      *
                      

String

Mandatory

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.

Example:-
1000.0

                      mandate.start_date
                      
                      

String

Mandatory for UPI Mandate. Mandate start date in UNIX EPOCH timestamp (UTC timezone). By default value will be today’s date. Note: For PayU enach, tomorrow’s date needs to be passed. If today’s date is passed, it will be changed internally to tomorrow’s date.

Example:-
1633087969

                      mandate.end_date
                      
                      

String

Mandatory for UPI Mandate. 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 (Supported only by UPI)
DAILY
WEEKLY
FORTNIGHTLY
MONTHLY
BIMONTHLY
QUARTERLY
HALFYEARLY
YEARLY
ASPRESENTED

Default: ASPRESENTED

Note:
1. Daily is not supported by Billdesk and Paytm (For cards)
2. In UPI 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. 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

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

                      User Defined Parameters
                      
                      

                      udf1 , udf2 , udf3 , udf4, udf5
                      
                      

String (Upto 255 Characters)

No Special Characters Supported

User Defined Parameter (UDF)

The above field can be used to send any user defined parameters. These fields will not accept any special characters in value

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

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

                      Metadata Parameters
                      
                      

                      metadata.JUSPAY:gateway_reference_id
                      
                      

String

Use this parameter only when you have use case of gateway reference ID. For detailed information check here

                      metadata.bank_account_details
                      
                      

Array

Conditional

Applicable for TPV Orders.

Either bank_account_number or bank_account_id is mandatory

                      bank_account_number
                      
                      

String

Conditional

Customer Bank account

                      bank_ifsc
                      
                      

String

Optional

IFSC code of bank

                      juspay_bank_code
                      
                      

String

Optional

juspay bank code given in eligibility API. e.g. JP_HDFC

                      bank_beneficiary_name
                      
                      

String

Optional

Name of account holder

                      bank_account_id
                      
                      

String

Conditional

bank account id provided by Juspay while storing bank account details

                      bank_account_type
                      
                      

String

Optional

Account Type of the Customer Account

Example:- Eg: CURRENT or SAVINGS

                      mutual_fund_details
                      
                      

List

Optional

This block contains the details of the Mutual Fund

NOTE: mutual_fund_details needs to be passed in a stringified format

                      memberId
                      *
                      

String

Mandatory

Member Id with ICCL or ARN_RIA with RTA

                      userId
                      *
                      

String

Mandatory

Client Id with ICCL or USER_CODE with RTA

                      mfPartner
                      *
                      

String

Mandatory

NSE/BSE/KFIN/CAMS

                      orderNumber
                      *
                      

String

Mandatory

Unique order number or application number of each MF

                      amount
                      *
                      

String

Mandatory

Individual MF amount within the array of MF being purchased in a single basket

                      investmentType
                      *
                      

String

Mandatory

LUMPSUM/SIP

                      schemeCode
                      
                      

String

Optional

Scheme Code of the MF (Mandatory for RTA reporting)

                      folioNumber
                      
                      

String

Optional

Folio Number of the MF (Mandatory for RTA reporting)

                      panNumber
                      
                      

String

Optional

PAN Number of the user, to be passed in UPPERCASE only (Mandatory for RTA reporting)

                      amcCode
                      
                      

String

Optional

AMC Code of the MF

                      ihNumber
                      
                      

String

Conditional

In-house Number of the SIP (Mandatory for K-Fin RTA)

                      showExpiry
                      
                      

String

Optional

To show expiry timer on the payment page

                      isEnable
                      *
                      

Boolean

Mandatory

Pass true if the expiry timer needs to be shown

Example:- true/false

                      activeTimeInMs
                      *
                      

String

Mandatory

Pass the time within which user has to complete the transaction (in ms)

                      basket
                      
                      

String

Optional

To pass product specific information in the user’s basket/cart. This key is required to be passed as stringified JSON

                      productName
                      
                      

String

Conditional

Name of the product

id

String

Conditional

Product ID

                      quantity
                      
                      

String

Conditional

Quantity of the product that User has in basket/cart

                      unitPrice
                      
                      

String

Conditional

Price of the product

                      amount_info
                      
                      

String

Optional

To pass amount breakup information for displaying surcharge, convenience fee or shipping fee. This key is required to be passed as stringified JSON.

Example:
"amount_info": "{\"base_amount\":\"100\", \"add_on_amounts\": [{\"name\":\"SURCHARGE\",\"amount\":\"2\"}]}"

                      features
                      
                      

String

Optional

To enable features like paymentAttempt.
Example:

\"features\":{\"paymentAttempt\":{\"enable\":true}}

                      paymentAttempt
                      
                      

String

Optional

This event is triggered whenever user attempts to make payment using any PO.
paymentAttempt Payload

resumePayment : In response to paymentAttempt, merchant needs to call the resumePayment event with hyperServices.process call
Status value true is indicative of merchant approval to proceed with the transaction, whereas false aborts the payment and SDK exits to return control back to merchant website.
resumePayment Payload

                      enable
                      *
                      

Boolean

Mandatory

If true, then SDK will wait for resumePayment call before proceeding with the transaction.

Example:- true/false

Step 2

Sign the OrderDetails Payload

To provide enterprise-grade security, it is required to create a RSA-SHA256 signature of the orderDetails payload created above.

The orderDetails JSON payload first needs to be converted into a string and then signed using the Private key stored on the merchant server. Click here to know How to Generate the Signature

The orderDetails payload along with the signature are required to create the process payload as a next step

Step 3

Create Process Payload

The process API takes a JSONObject as argument. This argument is also known as process payload.

                      action
                      *
                      

String

Mandatory

Pass paymentPage is to start the Hypercheckout screen

Pass paymentManagement to start the payment management interface for deleting saved cards and linking/unlinking wallets

                      merchantId
                      *
                      

String

Mandatory

Merchant ID provided by Juspay during onboarding

                      clientId
                      *
                      

String

Mandatory

Client ID provided by Juspay during onboarding

                      orderId
                      *
                      

String

Mandatory

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

Order ID at Juspay end is not case sensitive. We do not differentiate between upper and lower case values

                      amount
                      *
                      

String

Mandatory

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

                      customerId
                      *
                      

String

Mandatory

Example:-
customer-id-007

                      customerEmail
                      *
                      

String

Mandatory

_ 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

                      customerMobile
                      *
                      

String

Mandatory

Example:-
9999999912

                      orderDetails
                      *
                      

String

Mandatory

Stringify the JSON payload created in Step 3.1

                      signature
                      *
                      

String

Mandatory

In signature, pass the Output of Step 3.2

Example:-

AZOn8jH8RPWSzrbZ0iiHSLjMdvnvDBkyKslgx4yDadtiQ49kqf8vFh7GMEC/aSARgfovwUOBoPPRTksV6IXNlwIBwuSLWeH7/dIBC+FdtgOR1UNhRGKM17xNg/A6iLufR880Pa31QT3JAWJtRPeQ3aGczsgsFc8NzbSNCQmV2w7ziSSUAwdpU8JWthkFc2oW23QTcMHXnk/EHXf9vAHUZS1x2vKMnrUE6JuTa8vNLlpAcsZ8ueGLvBuobx6lBltsyb8+DjWT+3+W4nt1xmH734g9aOkduLyQTvGIYDKCpnvWdR0J34SvgUnCnv5XzRm9+HQInZDSslJ+1q5hAe3PQQ==

                      merchantKeyId
                      *
                      

String

Mandatory

Unique identifier against which merchant’s public key is stored with Juspay. Can be fetched from Juspay Dashboard. Login>EC Operations>Settings>Security>RSA Key

                      language
                      
                      

String

Pass the language value to localise payment experience in regional language. Accepted values are "english", "hindi", "telugu", "tamil", "bengali", "malayalam", "gujarati", "kannada", "marathi"

                      payeeName
                      
                      

String

Custom payeeName to override default payeeName in UPI-INTENT APP
May or may not reflect due to extra verification at UpiApps end which cannot be controlled by Juspay

                      displayNote
                      
                      

String

Custom displayNote to override default displayNote(transaction-note) in UPI-INTENT APP
May or may not reflect due to extra verification at UpiApps end which cannot be controlled by juspay

                      description
                      
                      

String

Description for order to be displayed to the user on amountBar

Example:-
Complete your payment

As soon as you sign up with Juspay, we set you up with a Dummy PG automatically. Using this Dummy PG, you can run test transactions with a pre-configured set of cards.

You may also configure the test credentials of the gateway and use the respective test cards for completing the transaction journey.
Please refer to the Test Resources page for more details.

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