Payload (Initiate & Process)

This section will explain the structure of input & output payload (data) for HyperSDK.

Payload structure for 'Initiate' and 'Process' API requests (input):

VariableTypeDescription
requestId*StringUnique randomly generated UUID v4 string for triggering any operation on HyperSDK. It is used for tracking purposes.
Should be a UUID string (see Generate UUID).
service*StringService name
(For payment page service, use: "in.juspay.hyperpay")
payload:wwwwwwww
    {param1, param2,..}
*JSON object
Strings
Request payload specific to each operation.
Open a table below to list the payload object parameters for Initiate or Process APIs:
 Initiate Payload Object Parameters:     (click to view)

The payload passed to the SDK during Initiate SDK call shall contain the parameters listed below. Please note that these parameters will be sufficient for the Payment Methods: Cards, Netbanking, Wallets and UPI (Collect, Intent flows).

VariableTypeDescriptionDefault
action*StringChanges based on operation to be performedwi"initiate"wi
clientId*StringClientId will be shared by Juspay team.
customerId*StringUnique identifier of the customer. It is the ID with which merchant refers to a customer object. In case of guest login it should be an empty string. Guest user login is supported on Web platform only.
Note: This parameter was found in the sample, but not in the original parameter list.
signaturePayload:wwww
  "{param1, param2, ...}"
*Stringified
Object
JSON Stringified signaturePayload object
Open table below to list parameters:
 signaturePayload Parameters:
  merchant_idnnnt* wwStringwww
Unique MerchantId shared during the on-boarding.
  customer_idnwnn* wwString
Uniquely identifies the customer. It is the ID with which merchant refers to a customer object.
  mobile_number t * wwString
Mobile number of the customer.
  email_addressnnn* wwString
Email address of the customer.
  first_namennnntnnnwwString
Customer’s first name.
  last_namennnnnnnnwwString
Customer’s last name.
  timestampnnnnntn* wwString
Time at which the session is started
(Epoch Unix timestamp in milliseconds).
signature*StringSigned signaturePayload (above mentioned JSON Stringified object). Please refer to Generating the Signature for instructions.
merchantKeyId*StringUnique identifier for the Signature that will be provided by Juspay after the merchant shares the public key. Please refer to Generating the Signature for instructions.
merchantId*StringUnique merchantId shared during onboarding.

This parameter shall not be passed if the customer/order is created through the Payments SDK.

It is Mandatory if the payment session token is obtained from Juspay Servers.
environment*StringEnvironment to be used in the session. Accepted values are “sandbox” or “prod“prod”
logLevelStringPass this parameter to receive the user click events. Refer to Clickstream Events for list of events.
Value : “1”
merchantFontsStringThis is an optional feature which may be used to enable the SDK to load fonts directly from merchants’ app. Please refer to Merchant Fonts for more details.

{
“bold” : {
    “name” : String
    ${source} : String/Int -> Placeholder for
    “resId” or “path”
    }
“regular” : {
    “name” : String
    ${source} : String/Int
    }
“semiBold”:{
    “name” :
    ${source} : String/Int
    }
}
  Process Payload Object Parameters:   (click to view)

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 the set of parameters to be passed in the payload from the list below:

Note : When the parameter action is set to “paymentManagement”, the payload for the Process API shall contain only the parameters listed here. This will start the payment management interface.
VariableTypeDescriptionDefault
orderDetails:wwwwww
  "{param1, param2, ...}"
*Stringified
Object
JSON :stringified :Order details.wwww
Open table below to list parameters:
wwwwt
  Order Details parameters:     (click to view)
VariableTypeDescriptionDefault
order_id*wtStringwtUnique Identifier for the order.wwwww
Should be Alphanumeric with character length less than 18.
merchant_id*StringUnique MerchantId shared during the on-boarding.
amount*StringAmount 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.
timestamp*StringEpoch Unix timestamp in milliseconds.
customer_id*StringString that uniquely identifies the customer. It is the ID with which merchant refers to a customer object.
first_nameStringCustomer’s first name.
Note: This was found in the orderDetails object for Payment Locking, but not in the orderDetails object for Process Payload.
last_nameStringCustomer’s last name.
Note: This was found in the orderDetails object for Payment Locking, but not in the orderDetails object for Process Payload..
currencyStringISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP."INR"
gateway_idString12 for PAYU, 18 for PAYTM
Specify your preferred gateway for this order. Complete mapping for “gateway_id” can be found here: Gateway mapping
customer_emailStringEmail address of the customer.
If the backend gateway requires it, then you must send this value.
customer_phoneStringMobile number or fixed line number of the customer.
If the backend gateway requires it, then you must send this value.
mobile_numberStringMobile number of the customer.
Note: This was found in the orderDetails object for Payment Locking, but not in the orderDetails object for Process Payload.
descriptionStringShort description for the order. We send this information to the backend gateways whenever there is a provision for this.
return_urlStringA fully qualified URL such as http://shop.merchant.com/ to which the customer will be redirected after payment completion. This URL shouldn’t contain any query parameters. This URL takes higher precedence over the common return URL configured in your account settings.
udf1StringCustom parameter
udf2StringCustom parameter
udf3StringCustom parameter
udf4StringCustom parameter
udf5StringCustom parameter
udf6StringCustom parameter
udf7StringCustom parameter
udf8StringCustom parameter
udf9StringCustom parameter
udf10StringCustom parameter
options.wwwwwwwww
    create_mandate
Object
String
Required to create a mandate transaction. Takes the value of REQUIRED, OPTIONAL, DISABLED
mandate.
    {{parameter}}
Object
String
Object containing a mandate detail (all mandate details are listed in mandate.{{parameter}} {object) format)
(open table below to view list of parameters):
  Mandate Object Parameters:      (click to view)
VariableTypeDescriptionDefault
max_amount*StringMaximum amount for a mandate. Mandatory only if mandate.amount_rule = VARIABLE.
start_date*StringMandate start date in UNIX EPOCH timestamp (UTC timezone). The start date has to be today’s date.

Mandatory only for UPI Mandates
end_date*StringMandate end date in UNIX EPOCH timestamp (UTC timezone), from when a mandate will move to EXPIRED state, and recurring mandate will not be allowed.

Mandatory only for UPI Mandates
frequencyStringDefines the frequency of mandate execution, or how often a customer should be charged.
(See description below table)
ASPRESENTED
rule_value*StringDetermines the day of week or month that a mandate will be executed, depending on mandate.frequency.
(See description below table)
amount_ruleStringData type: ENUM
Possible values: FIXED, VARIABLE.

In case of FIXED, max amount will be equal to amount
VARIABLE
rule_typeStringON / BEFORE / AFTER
For Razorpay, rule_type will be updated to BEFORE.
For Paytm, rule_type will be updated to AFTER
revokable_by_customerBooleanPossible Values:
TRUE, FALSE

If FALSE, the mandate cannot be revoked by the customer once set. It should be TRUE for Recurring and TRUE/FALSE for ONETIME
true
block_fundsBooleanSet 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.
* = Required
* = Conditional

  mandate.frequency / mandate.rule_value definitions:     (click to view)
mandate.frequency
Description: Defines the frequency of mandate execution, or how often a customer
should be charged.
Data type:    String (ENUM format)
Possible values:
ONETIME, DAILY, WEEKLY, FORTNIGHTLY, MONTHLY, BIMONTHLY,
QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
Default:        ASPRESENTED

mandate.rule_value
Description: This value determines the day of week or month that a mandate will
be executed, depending on the mandate.frequency.
Data type:    String (Integer format)
Possible values:
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, or 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.
  Special considerations for certain values of the mandate.rule_value /
mandate.frequency parameters:         (click to view)
Calculating the day of mandate execution for certain values of mandate.rule_value
when mandate.frequency is set to 'FORTNIGHTLY' or 'MONTHLY'.
mandate.frequency = FORTNIGHTLY:
1. If the value is ‘14’, ‘15’, or ‘16’, and falls on the latter half of February (16th to
28th), then the mandate shall execute on the last day of February.
2. If the mandate start date is 24th January 2018 with value ‘16’, then the first
debit will be on 31st January, followed by 15th February, 28th February,
15th March, 31st March, and so on.
3. If the value is ‘16’, and the month has only 30 days, then the mandate should
execute on 30th.
4. If the mandate start date is 29th January, and the value is ‘4’, then the first debit
will be on 4th February, followed by 19th February, 4th March, and so on.

mandate.frequency = MONTHLY:
1. If the value is ‘29’, ‘30’, or ‘31’, and falls in February, then the mandate shall
execute on the last day of February.
2. If the value is ‘31’, and the next executable month has 30 days, then the
mandate will execute on the 30th.
3. If the mandate start date is 29th January and the value is ‘17’, then the first
debit will be on 17th February.
metadata.wwwwwwww
    {{parameter}}
*Object
wtStringwt
Object containing a Metadata parameter (all metadata details are listed in metadata.{{parameter}} (object) format)
(open table below to view list of parameters):
wwww
  Metadata Object Parameters:     (click to view)
VariableTypeDescriptionDefault
JUSPAY:gateway_reference_id*StringString that identifies the gateway for Merchant. This shall be passed only when the merchant uses a Multi-MID setup for each gateway
(i.e - merchant has more than 1 MID linked with the same payment gateway).

For Multi-MID setup of a Merchant, this parameter is mandatory
PAYTM_V2:SUBSCRIPTION_EXPIRY_DATE*StringApplicable only for Paytm.

(format -> YYYY-MM-DD) Date at which subscription will expire.
“2035-12-31”
PAYTM_V2:SUBSCRIPTION_FREQUENCY_UNIT*StringApplicable only for Paytm.

This, combined with interval, defines the frequency. The values supported for this attribute currently are: DAY , MONTH, YEAR. If the billing cycle is of 2 months, the value for this attribute would be MONTH.
DAY
PAYTM_V2:SUBSCRIPTION_FREQUENCY*StringApplicable only for Paytm.

Combined with subscriptionFrequencyUnit, defines the frequency of renewal transaction. If the renewal cycle is of 2 months, attribute values can be: subscriptionFrequency : 2, subscriptionFrequencyUnit : MONTH. If the renewal cycle is of 15 days, attribute values can be: subscriptionFrequency : 15, subscriptionFrequencyUnit : DAY
"1"
PAYTM_V2:SUBSCRIPTION_START_DATE*StringApplicable only for Paytm.

(format -> YYYY-MM-DD) Date from which to start subscription. Conditionally mandatory if SUBSCRIPTION_GRACE_DAYS is passed. If this is not passed, renewal can be called after 24 hours.
PAYTM_V2:SUBSCRIPTION_GRACE_DAYS*StringApplicable only for Paytm.

Number of days after renewal cycle start date for which merchant can send renewal request.

Conditionally mandatory if SUBSCRIPTION_START_DATE is passed. If this is not passed renewal can be called after 24 hours.

(If SUBSCRIPTION_FREQUENCY_UNIT and SUBSCRIPTION_FREQUENCY are not passed (in which case, they are given default values: DAY, 1), then grace days should be 0, as renewal cycle is of 1 day, if entered more than 0, Paytm will invalidate the request)
* = Required
* = Conditional
offer_details: {...}wwwi*wiObjectwiOffer Details object, which contains the Payment Locking parameters:   (See the "Payment Locking" page for details.)wwww
wtVariablewtiTypewwwtDescriptionwwwtDefault
action wwwwwwwwwwwwwwni *iwiStringwiChanges based on operation to be performed.
wwwwwwwwwwwwwwwwwwwwwwww
Pass “paymentPage” to start the payment page interface.

Pass “quickPay” to start the quick pay interface.

Pass “paymentManagement” to start the payment management interface. Refer here for complete Process API payload
"paymentPage"
merchantId wwwwwwwwwwwww*StringIdentifies the merchant.
eg. “merchant”.
clientId*StringClientId will be shared by Juspay team
orderId*StringUnique identifier for the order. Should be Alphanumeric, with character length less than 18.
amount*StringAmount of the transaction.
customerId*StringUnique identifier of the customer. It is the ID with which merchant refers to a customer object.

In case of guest login it should be an empty string. Guest user login is supported on Web platform only
customerEmail*StringCustomer's email address.
customerMobile*StringCustomer's phone number.
signature*StringRSA-SHA256 Signature of orderDetails in HEX format. This is Mandatory if the order is created through Payments SDK. Please refer to Generating the Signature for instructions.
merchantKeyId*StringUnique identifier for the Signature that will be provided by Juspay after the merchant shares the public key. Please refer to Generating the Signature for instructions.
languageStringPass the language value to localise payment experience in regional language. Accepted values are "english", "hindi", "telugu", "tamil", "bengali", "malayalam", "gujarati", "kannada", "marathi"."english"
environment*StringEnvironment to be used in the session. Accepted values are “sandbox” or “prod"prod"
guest_login_url*StringProvide URL where user should be redirected for login inorder to fetch saved payment methods. This feature is available only in Web payment page.
payeeNameStringCustom payeeName to override default payeeName in UPI-INTENT APP
Note : - May or may not reflect due to extra verification at UpiApps end which cannot be controlled by Juspay
(New parameter)
displayNoteStringCustom displayNote to override default displayNote (transaction-note) in UPI-INTENT APP
Note : - May or may not reflect due to extra verification at UpiApps end which cannot be controlled by Juspay
(New parameter)
* = Required
* = Conditional

Sample input API request for Initiate:

{
  "requestId" : "8cbc3fad-8b3f-40c0-ae93-2d7e75a8624a",
  "service" : "in.juspay.hyperpay",
  "payload" : {
    "action" : "initiate",
    "merchantId" : "<Merchant Id>",
    "merchantKeyId" :"<Merchant Key Id>",   
    "clientId" : "<Client Id>", 
    "customerId" : "<Customer Id>", //Any unique refrences to current customer
    "environment" : "sandbox"|"prod",
    "signaturePayload" : "{\"merchant_id\":\"idea_preprod\",\"customer_id\":\"1234567890\",\"mobile_number\":\"9234567890\",\"email_address\":\"[email protected]\",\"timestamp\":\"1573724015209\"}",
    "signature" : "<Sigature>"
  }
}
"signaturePayload": 
   "{
      \"merchant_id\": \"idea_preprod\",
      \"customer_id\": \"1234567890\",
      \"mobile_number\": \"9234567890\",
      \"email_address\": \"[email protected]\",
      \"timestamp\": \"1573724015209\"
    }",

Sample input API request for Process:

{
  "requestId" : "8cbc3fad-8b3f-40c0-ae93-2d7e75a8624a", 
  "service" : "in.juspay.hyperpay",
  "payload"  :
    {
      "action" : "paymentPage",
      "merchantId" : "idea_preprod",
      "clientId": "idea_preprod",
      "orderId": "R1096438018",
      "amount": "1.00",
      "customerId": "1234567890",
      "customerEmail": "[email protected]",
      "customerMobile": "9739534710",
      "orderDetails": "{\"order_id\":\"R1096438018\",\"amount\":\"1.00\",\"customer_id\":\"1234567890\",\"merchant_id\":\"idea_preprod\",\"customer_email\":\"[email protected]\",\"customer_phone\":\"1234567890\",\"timestamp\":\"1571922200845\"}",
      "signature": "AZOn8jH8RPWSzrbZ0iiHSLjMdvnvDBkyKslgx4yDadtiQ49kqf8vFh7GMEC/aSARgfovwUOBoPPRTksV6IXNlwIBwuSLWeH7/dIBC+FdtgOR1UNhRGKM17xNg/A6iLufR880Pa31QT3JAWJtRPeQ3aGczsgsFc8NzbSNCQmV2w7ziSSUAwdpU8JWthkFc2oW23QTcMHXnk/EHXf9vAHUZS1x2vKMnrUE6JuTa8vNLlpAcsZ8ueGLvBuobx6lBltsyb8+DjWT+3+W4nt1xmH734g9aOkduLyQTvGIYDKCpnvWdR0J34SvgUnCnv5XzRm9+HQInZDSslJ+1q5hAe3PQQ==",
      "merchantKeyId": "2980",
      "language": "english",
      "environment": "sandbox"
    }
}
"orderDetails":
   "{
      \"order_id\": \"R1096438018\",
      \"amount\": \"1.00\",
      \"customer_id\": \"1234567890\",
      \"merchant_id\": \"idea_preprod\",
      \"customer_email\": \"[email protected]\",
      \"customer_phone\": \"1234567890\",
      \"return_url\": \"https://sandbox.juspay.in/end\",
      \"timestamp\": \"1571922200845\"
    }",

Response structure for 'Initiate' and 'Process' APIs (output):

VariableTypeDescription
requestId*StringUnique identifier sent for every operation
event*StringIndicates what event is triggered by HyperSDK
Possible events:
"initiate_result": for handling initiate responses, etc., and logging them
"hide_loader": for stopping the processing loader
"log_stream": for consuming the click events
"process_result": for handling process responses, etc., and logging them
service*StringService name
(For payment page service: in.juspay.hyperpay)
error*BooleanError is returned true in case the operation is not successful. In case the error field is true, please check errorCode and error message for more details.
errorCode*StringCheck for this key to detect error when ‘error’ parameter is true.
errorMessage*StringCheck for this key to detect error when ‘error’ parameter is true.
(See Error Codes for details on error codes and messages.)
payload:wwwwwwww
    {param1, param2,..}
*JSON object
Strings
Response payload specific to each operation ('Initiate' or 'Process') Open table below to list payload parameters
  Initiate API response payload:       (click to view)
VariableTypeDescription
actionwwwwwwwww*String''initiate"wwwwwwwwwwwwwwwwwwwwwwwnmwww
status*StringResult of the action
Open table below to list:
 Possible status codes:
"success":   Initiate successfully completed
"fail":   Initiate failed
  Process API response payload:     (click to view)
VariableTypeDescription
action*String''process"
status*StringResult of the action
Open table below to list:
  Possible status codes:
"charged", "cod_initiated":
Transaction successfully completed (only when "error" is false - "error" must be true for all other status indications) - call orderStatus once to verify (false positives) - process data ("cod_initiated" means user opted for cash on delivery option displayed on payment page)
"backpressed":
User back-pressed from PP without without initiating transaction (/txn)
"user_aborted":
User initiated a Transaction (/txn) and pressed back - poll order status
"pending_vbv", "authorizing":
Transaction (/txn) in pending state - poll order status until backend says fail or success
"authorization_failed", "authentication_failed", "api_failure":
Transaction (/txn) failed - poll order status to verify (false negatives)
"juspay_declined":"
User input is not accepted by the underlying PG - poll order status to verify (false negatives) Error code found here.
"new":
Order created but transaction failed - very rare for V2 (signature based) - poll order status
" ":
(default) unknown status, this is also failure - poll order status

(See Status Codes and Error Codes for more details on status and error codes in responses to Process API calls.)

paymentInstrument*StringThe payment instrument that was used within the selected payment instrument group.
Example.: “NB_AXIS”or “NB_HDFC” for the "nb" group.
paymentInstrumentGroup*StringThe payment instrument group that was used.
Example.: "nb", "card","wallet", etc.
* =
Conditional - included in the payload response for the Process API only if a payment instrument was used.
* = Required

Sample output response for the 'Initiate' API:

{
  "service": "in.juspay.hyperpay",
  "requestId": "8cbc3fad-8b3f-40c0-ae93-2d7e75a8624a",
  "payload":
     {
       "action": "initiate",
       "status": "success"
     },
  "errorMessage": "",
  "errorCode": "",
  "error": false,
  "event" : "initiate_result"
}

Sample output response for the 'Process' API:

{
  "service": "in.juspay.hyperpay",
  "requestId": "8cbc3fad-8b3f-40c0-ae93-2d7e75a8723b",
  "payload":
     {
       "action": "process",
       "status": "charged",
       "paymentInstrument": "NB_AXIS",
       "paymentInstrumentGroup": "nb"
     },
  "errorMessage": "",
  "errorCode": "",
  "error": false,
  "event" : "process_result"
}

🚧

requestId - Juspay Reference

"requestId" should be unique for all operations to HyperSDK. This ID allows for easier debugging and for querying responses required for integrations.


Did this page help you?