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):

Variable		Type	Description
requestId	*	String	Unique 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	*	String	Service 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).

Variable		Type	Description	Default
action	*	String	Changes based on operation to be performed	wi"initiate"wi
clientId	*	String	ClientId will be shared by Juspay team.
customerId	*	String	Unique 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	*	String	Signed `signaturePayload` (above mentioned JSON Stringified object). Please refer to Generating the Signature for instructions.
merchantKeyId	*	String	Unique 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	*	String	Unique `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	*	String	Environment to be used in the session. Accepted values are “sandbox” or “prod”	“prod”
logLevel		String	Pass this parameter to receive the user click events. Refer to Clickstream Events for list of events. Value : “1”
merchantFonts		String	This 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.

Variable		Type	Description	Default
orderDetails:wwwwww "{param1, param2, ...}"	*	Stringified Object	JSON :stringified :Order details.wwww Open table below to list parameters:	wwwwt

Order Details parameters: (click to view)

Variable		Type	Description	Default
order_id	*	wtStringwt	Unique Identifier for the order.wwwww Should be Alphanumeric with character length less than 18.
merchant_id	*	String	Unique MerchantId shared during the on-boarding.
amount	*	String	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.
timestamp	*	String	Epoch Unix timestamp in milliseconds.
customer_id	*	String	String that uniquely identifies the customer. It is the ID with which merchant refers to a customer object.
first_name		String	Customer’s first name. Note: This was found in the orderDetails object for Payment Locking, but not in the orderDetails object for Process Payload.
last_name		String	Customer’s last name. Note: This was found in the orderDetails object for Payment Locking, but not in the orderDetails object for Process Payload..
currency		String	ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP.	"INR"
gateway_id		String	12 for PAYU, 18 for PAYTM Specify your preferred gateway for this order. Complete mapping for “gateway_id” can be found here: Gateway mapping
customer_email		String	Email address of the customer. If the backend gateway requires it, then you must send this value.
customer_phone		String	Mobile number or fixed line number of the customer. If the backend gateway requires it, then you must send this value.
mobile_number		String	Mobile number of the customer. Note: This was found in the orderDetails object for Payment Locking, but not in the orderDetails object for Process Payload.
description		String	Short description for the order. We send this information to the backend gateways whenever there is a provision for this.
return_url		String	A 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.
udf1		String	Custom parameter
udf2		String	Custom parameter
udf3		String	Custom parameter
udf4		String	Custom parameter
udf5		String	Custom parameter
udf6		String	Custom parameter
udf7		String	Custom parameter
udf8		String	Custom parameter
udf9		String	Custom parameter
udf10		String	Custom 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)

Variable		Type	Description	Default
max_amount	*	String	Maximum amount for a mandate. Mandatory only if `mandate.amount_rule` = VARIABLE.
start_date	*	String	Mandate start date in UNIX EPOCH timestamp (UTC timezone). The start date has to be today’s date. Mandatory only for UPI Mandates
end_date	*	String	Mandate 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
frequency		String	Defines the frequency of mandate execution, or how often a customer should be charged. (See description below table)	ASPRESENTED
rule_value	*	String	Determines the day of week or month that a mandate will be executed, depending on `mandate.frequency`. (See description below table)
amount_rule		String	Data type: ENUM Possible values: FIXED, VARIABLE. In case of FIXED, `max amount` will be equal to `amount`	VARIABLE
rule_type		String	ON / BEFORE / AFTER For Razorpay, rule_type will be updated to BEFORE. For Paytm, rule_type will be updated to AFTER
revokable_by_customer		Boolean	Possible 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_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.

* = 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)

Variable		Type	Description	Default
JUSPAY:gateway_reference_id	*	String	String 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	*	String	Applicable only for Paytm. (format -> YYYY-MM-DD) Date at which subscription will expire.	“2035-12-31”
PAYTM_V2:SUBSCRIPTION_FREQUENCY_UNIT	*	String	Applicable 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	*	String	Applicable 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	*	String	Applicable 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	*	String	Applicable 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	*	wiObjectwi	Offer Details object, which contains the Payment Locking parameters: (See the "Payment Locking" page for details.)	wwww

wtVariablewt	i	Type	wwwtDescriptionwwwt	Default


action wwwwwwwwwwwwwwn	i *i	wiStringwi	Changes 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	*	String	Identifies the merchant. eg. “merchant”.
clientId	*	String	ClientId will be shared by Juspay team
orderId	*	String	Unique identifier for the order. Should be Alphanumeric, with character length less than 18.
amount	*	String	Amount of the transaction.
customerId	*	String	Unique 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	*	String	Customer's email address.
customerMobile	*	String	Customer's phone number.
signature	*	String	RSA-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	*	String	Unique 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.
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".	"english"
environment	*	String	Environment to be used in the session. Accepted values are “sandbox” or “prod”	"prod"
guest_login_url	*	String	Provide URL where user should be redirected for login inorder to fetch saved payment methods. This feature is available only in Web payment page.
payeeName		String	Custom *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)
displayNote		String	Custom *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):

Variable		Type	Description
requestId	*	String	Unique identifier sent for every operation
event	*	String	Indicates 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	*	String	Service name (For payment page service: in.juspay.hyperpay)
error	*	Boolean	Error 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	*	String	Check for this key to detect error when ‘error’ parameter is `true`.
errorMessage	*	String	Check 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)

Variable		Type	Description
actionwwwwwwwww	*	String	''initiate"wwwwwwwwwwwwwwwwwwwwwwwnmwww
status	*	String	Result 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)

Variable		Type	Description
action	*	String	''process"
status	*	String	Result 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	*	String	The payment instrument that was used within the selected payment instrument group. Example.: “NB_AXIS”or “NB_HDFC” for the "nb" group.
paymentInstrumentGroup	*	String	The 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.

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

Sample input API request for Initiate:

Sample input API request for Process:

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

Sample output response for the 'Initiate' API:

Sample output response for the 'Process' API:

🚧requestId - Juspay Reference

🚧
requestId - Juspay Reference