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":[{...},{...},...]
              },
              ...,                                                  
          },
          ...,
     }
}
Note:
The orderDetails object is actually sent in the Process API payload as a stringified object, as shown here.

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:

VariableTypeDescriptionDefault
order_id*StringUnique 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.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)
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.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)
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 till at which subscription date is active 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. 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)
      * = Required
      * = Conditional
offer_details: {...}wi*ObjectOffer Details object, which contains the Payment Locking parameters:       (See table below)wwww
Offer Details object parameters:
VariableTypeDescription
offer_applied*BooleanSet to "false" for payment locking & "true" for merchant offer application.
Default: “false
merge_with_default_payment_methodsBooleanSet to "false" to display only instruments mentioned in merchant_offer_payment_methods; set to "true" otherwise. Default: “false
support_reorderingBooleanSet 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

Merchant Offer Payment Method object parameters:

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.

VariableTypeDescriptionPossible Values
offer_payment_method_typewn*StringDetails 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 groupSee table below for possible values
offer_payment_card_typeStringApplicable 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_typeStringType 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
nArray 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

* = Required

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”]
Refer to Note 1 below for more info on different UPI values


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"
     }
}
Note 1:
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

Did this page help you?