Payment Locking
Feature Details
- Allows merchants to block/allow selected payment instruments groupss, and/or specific payment instruments within a selected group to be displayed in the payment page.
- Merchants can also control the manage features like Direct OTP, E-Mandate on relevant instruments
(To be available soon) - Additional Feature covered :
- Supports reordering of the payment instruments group
Payload Structure:
All Payment Locking parameters are contained in the "offer_details" object, which is passed within the "orderDetails" object, which is part of the payload structure for the Process API:
{
"requestId": "<Request ID>",
"service": "<Servicc>",
"payload": {
"action": "<Action>",
...,
"orderDetails": {
"order_id": "<Order ID>",
...,
"offer_details": {
"offer_applied", "true"|"false",
...,
"merchant_offer_payment_methods":[{...},{...},...]
},
...,
},
...,
}
}
This would appear in expanded format as shown below:
` "orderDetails": "{
\"order_id\": \"<Order ID>\",
...,
\"offer_details\": "{
\"offer_applied\", \"true|false\",
...,
\"merchant_offer_payment_methods":"["{...}","{...}",...]"
}",
...,
}",
Order Details object parameters: (click to view)
Note: The added Offer Details object is shown at the bottom of this list:
Variable | Type | Description | Default | |
---|---|---|---|---|
order_id | * | String | 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.wwwwwww 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. |
* = Conditional
mandate.frequency / mandate.rule_value definitions: (click to view)
QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTEDDefault: ASPRESENTED
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)
mandate.rule_value
mandate.frequency
is set to 'FORTNIGHTLY' or 'MONTHLY'.metadata.wwwwnw {{parameter}} | * | Object iStringi | 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 till at which subscription date is active 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. Mandatory if subscriptionStartDate is sent in 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) |
* = Conditional
offer_details: {...}wi | * | Object | Offer Details object, which contains the Payment Locking parameters: (See table below) | wwww |
Variable | Type | Description | |
---|---|---|---|
offer_applied | * | Boolean | Set to "false" for payment locking & "true" for merchant offer application. Default: “false” |
merge_with_default_payment_methods | Boolean | Set to "false" to display only instruments mentioned in merchant_offer_payment_methods; set to "true" otherwise. Default: “false” | |
support_reordering | Boolean | Set to "false" to retain the order of the instruments groups as the same as the configured order & "true" to change the order of the instruments groups as passed in the offer_payment_methods key.Default: “false” | |
merchant_offer_payment_methods: [{...),..] | * | Array of JSON objects | Array of Merchant Offer Payment Method objects (See table below) |
* = Required
This JSON object is a specific instance on how filtering is to be applied to payment instruments on the payment page. Additional features, such as management of Direct OTP. E-Mandates on relevant instruments, and specific card filtering options, will be available soon.
Variable | Type | Description | Possible Values | |
---|---|---|---|---|
offer_payment_method_typewn | * | String | Details of the payment method type to target (Selects a payment instrument group) | See table below for possible values |
offer_payment_methods: [...] | Array of Strings | List of all Specific instruments within a group on which filtering is supposed to be applied. When not passed, filter will be applied on whole instrument group | See table below for possible values | |
offer_payment_card_type | String | Applicable only for cards | “DEBIT”, “CREDIT” | |
offer_payment_card_issuer: [...] | Array of Strings | Details of Card Banks Applicable only for cards | “HDFC Bank”, “SBI” etc. | |
filter_type | String | Type of filter Default : 'blacklist" | “whitelist”, “blacklist” | |
features: [{...},{...},..] | Array of Objects | Array of Features Objects Details of feature wise filter (To be available soon) |
Features Object Parameters: (click to view)
(To be available soon)Variable | Type | Description | Possible Values | |
---|---|---|---|---|
name | * | String | Feature name | “DOTP” |
instruments | * | Array of Strings |
List of instruments to be filtered | [“SBI”, “HDFC bank”] => for SBI Cards & HDFC Cards |
filter_type | String | Type of filtering that should be applied on instruments Default: "blacklist" |
“whitelist”, “blacklist” |
* = Conditionally mandatory if "features" is passed
specific_card_filters:n[{...},{...},..] wwwwwwwwwwwwwwwwwww | n | Array of Objects | Array of Specific Card Filters One to one maps of card details to filter (To be available soon) | twwwwwwww |
Specific Card Filters Object Parameters: (click to view)
(To be available soon)Variable | Type | Description | Example | |
---|---|---|---|---|
card_brand | * | String | Card Brand Name | “MASTERCARD” |
card_bin | Array of Strings |
Range of bins which is supposed to be filtered on | [“600000::900000”] | |
card_type | * | String | Card Type | “DEBIT” |
card_bank | String | Card Bank | “HDFC Bank” |
* = Conditionally mandatory if "specific_card_filters" is passed
Possible values for offer_payment_methods array with given offer_payment_method_type:
offer_payment_method_type (payment instrument group) |
offer_payment_methods:[...]www(possible array elements) (payment instruments within group) |
---|---|
“nb” For netbanking |
Bank codes Example : [“NB_AXIS”, “NB_HDFC”] |
“wallet” For wallets |
Wallet codes Example : [“PAYTM”, “MOBIKWIK”] |
“card” For Cards |
Card brands Example : [“MASTERCARD”, “VISA”] |
“paylater” For pay later instruments |
PayLater codes Example : [“LAZYPAY”] |
“cashod” For Cash-On-Delivery |
--- |
“upi” For upi collect & upi intent |
UPI handles (Pay using UPI ID) Example: [ “@ybl”, “@okhdfcbank”] |
”upiAppsWithOther” For popular upi apps on payment page and all apps & collect option on UPI screen |
Combination of handles & App Name or Package Names Example: [ “GPAY”, “PHONEPE”, “@ybl”, “@okhdfcbank”] (For best results use package names for upi apps) |
“upiApps” For upi intent only |
App Names Or Package Names. Example: [ “GPAY”, “PHONEPE”] |
Payload Details
offer_details:
{ "offer_applied": " " // Boolean string (true or false)
, "merchant_offer_payment_methods": [{...},..] // Array of Merchant Offer Payment Method objects
, "merge_with_default_payment_methods": " " // Boolean string (true or false)
, "support_reordering": " " // Boolean string (true or false)
}
merchant_offer_payment_methods: [
{ "offer_payment_method_type": " " // String (payment instrument group)
, "offer_payment_method": [...] // Array of strings (instruments within group)
, "offer_payment_card_type": " " // String ("DEBIT" or "CREDIT") -only for cards
, "offer_payment_card_issuer": [...] // Array of strings (“HDFC Bank”, etc.) -only for cards
, "filter_type": " " // String ("whitelist" or "blacklist")
, "features": [{...},{...},..] // Array of Features objects
, "specific_card_filters": [{...},{...},..] // Array of SpecificCardFilters objects -only for cards
},...]
features:
{ "name": " ", // String (“DOTP”)
"instruments": [...], // Array of strings ([“SBI”, “HDFC bank”] => for SBI Cards & HDFC Cards}
"filter_type": " " // String (“whitelist” or “blacklist”)
}
specific_card_filters:
{ "card_brand": " ", // String (“MASTERCARD”, "VISA", etc.)
"card_bin": [...], // Array of strings (card bin range) example:[“600000::900000”,..]
"card_type": " ", // String ("DEBIT" or "CREDIT")
"card_bank": " " // String (“HDFC Bank”, etc.)
}
Sample Payload
(This will whitelist NB_AXIS & NB_HDFC & completely blacklist i.e remove UPI while keeping other instruments & changing order of instruments )
order_details:
{
"order_id": "R8205947560",
"first_name": "John",
"last_name": "Wick",
"mobile_number": "9592329220",
"email_address": "[email protected]",
"customer_id": "9592329220",
"timestamp": "1611559686153",
"merchant_id": "croma",
"amount": "1.00",
"currency": "INR",
"offer_details":
{
"merge_with_default_payment_methods": "true",
"offer_applied": "false",
"merchant_offer_payment_methods": [
{
"filter_type": "whitelist",
"offer_payment_methods": [
"NB_AXIS",
"NB_HDFC"
],
"offer_payment_method_type": "NB"
},
{
"filter_type": "blacklist",
"offer_payment_method_type": "upiAppsWithOther"
}
],
"support_reordering": "true"
}
}
Special Case for blacklisting/whitelisting UPI when
merge_with_default_payment_methods
is set to true. Following screenshots mention the value to be used based on the configuration of UPI UI: Use values for
offer_payment_methods
as shown in the following screenshots based on the configuration of the UPI UI:
- upiApps


- upi


- upiAppsWithOther


Updated 3 months ago