Payment Page request formats

Overview

In the 3‑D Secure 2 procedures, payment requests use request standard formats and support parameters (both existing parameters and new ones) that are optional, but it is strongly advised to use them to make selection of frictionless flow more likely.

For detailed description of the standard request formats, see Payment Page API. The new objects and parameters are described in this section.

New parameter: payment_merchant_risk

The payment_merchant_risk parameter is used in Payment Page invocation request. The parameter value is a Base64-encoded string which contains all the purchase details and indication of the preferable authentication flow.

The value for the payment_merchant_risk parameter is generated as follows:

1. Add the purchase details and preferable authentication flow data in a payment JSON object as shown in the following sample.

   Figure: Sample JSON object code

   { 
     "payment":{ 
       "reorder":"01",
       "preorder_purchase":"01",
       "preorder_date":"01-10-2019",
       "challenge_indicator":"01",
       "challenge_window":"01",
       "gift_card":{ 
         "amount":12345,
         "currency":"USD",
         "count":1
       }
     }
   }

   Table 1. Parameters of the payment object

   Parameter	Type	Description
   challenge_indicator	string	This parameter indicates whether challenge flow is requested for this payment. Possible values: 01—no preferences 02—it is preferable not to use challenge flow 03—challenge flow preferred 04—always use challenge flow 05—do not use challenge flow (risk analysis has been performed by the merchant) 06—do not use challenge flow (use Data Only flow) 07—do not use challenge flow (Strong Customer Authentication has been performed) 08—do not use challenge flow (merchant is included in cardholder's trusted beneficiaries list) 09—always use challenge flow (prompt the cardholder to add merchant to the trusted beneficiaries list)
   challenge_window	string	The dimensions of a window in which authentication page opens. Possible values: 01—250 x 400 px 02—390 x 400 px 03—500 x 600 px 04—600 x 400 px 05—full screen
   preorder_date	string	The date the preordered merchandise will be available. Format: dd-mm-yyyy.
   preorder_purchase	string	This parameter indicates whether cardholder is placing an order for merchandise with a future availability or release date. Possible values: 01—merchandise available in stock 02—future merchandise availability
   reorder	string	This parameter indicates whether the cardholder is reordering previously purchased merchandise. Possible values: 01—first time order 02—reorder
   gift_card—object with information about payment with prepaid card or gift card.
   amount	integer	Amount of payment with prepaid or gift card denominated in minor currency units.
   currency	string	Currency of payment with prepaid or gift card in the ISO 4217 alpha-3 format, for example GBP.
   count	integer	Total number of individual prepaid or gift cards/codes used in purchase.

2. Encode the JSON object by using the Base64 scheme.

   Figure: Sample Base64-encoded string

   eyAKICAicGF5bWVudCI6eyAKICAgICJyZW9yZGVyIjoiMDEiLAogICAgInByZW9yZGVyX3B1cmNoYXNlIjoiMDEiLAogICAgInByZW9yZGVyX2RhdGUiOiIwMS0xMC0yMDE5IiwKICAgICJjaGFsbGVuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgImNoYWxsZW5nZV93aW5kb3ciOiIwMSIsCiAgICAiZ2lmdF9jYXJkIjp7IAogICAgICAiYW1vdW50IjoxMjM0NSwKICAgICAgImN1cnJlbmN5IjoiVVNEIiwKICAgICAgImNvdW50IjoxCiAgICB9CiAgfQp9Cg==

This string is passed as the value of the payment_merchant_risk parameter which is included amongst other parameters in Payment Page invocation request.

New parameter: customer_account_info

The customer_account_info parameter is used in Payment Page invocation request. The parameter value is a Base64-encoded string which contains customer account details and customer contact information on record with the web service.

The value for the customer_account_info parameter is generated as follows:

1. Add the customer account details and customer contact information data in a customer JSON object as shown in the following sample.

   { 
     "customer":{ 
       "address_match":Y,
       "home_phone":"79105211111",
       "work_phone":"74955211111",
       "account":{ 
         "additional":"gamer12345",
         "age_indicator":"01",
         "date":"01-10-2019",
         "change_indicator":"01",
         "change_date":"01-10-2019",
         "pass_change_indicator":"01",
         "pass_change_date":"01-10-2019",
         "purchase_number":12,
         "provision_attempts":16,
         "activity_day":22,
         "activity_year":222,
         "payment_age_indicator":"01",
         "payment_age":"01-10-2019",
         "suspicious_activity":"01",
         "auth_method":"01",
         "auth_time":"01-10-201913:12",
         "auth_data":"login_0102"
       }
     }
   }

   Table 2. Parameters of the customer object

   Parameter	Type	Description
   address_match	string	The parameter indicates whether the customer billing address matches the address specified in the shipping object. Possible values: Y—matches N—does not match
   home_phone	string	Customer home phone number. Numeric, from 4 to 24 characters. Example: 44991234567.
   work_phone	string	Customer work phone number. Numeric, from 4 to 24 characters. Example: 44997654321.
   account—object with account information on record with merchant
   additional	string	Additional customer account information, for instance arbitrary customer ID. Maximum 64 characters.
   activity_day	integer	Number of card payment attempts in the last 24 hours. Maximum 3 characters (999).
   activity_year	integer	Number of card payment attempts in the last 365 days. Maximum 3 characters (999).
   age_indicator	string	Number of days since the customer account was created. Possible values: 01—guest check-out 02—customer account was created in this transaction 03—customer account was created less than 30 days ago 04—customer account was created 30 to 60 days ago 05—customer account was created over 60 days ago
   auth_data	string	Any additional log in information in free text. Maximum 255 characters.
   auth_method	string	Authentication type the customer used to log on to the account when placing the order. Possible values: 01—no authentication 02—log on by using authentication data on file with merchant 03—log on by using federated ID (for example, Google Account or Facebook) 04—log on by using a FIDO authenticator (Fast IDentity Online)
   auth_time	string	Account log on date and time. Format: dd-mm-yyyyhh:mm.
   date	string	Account creation date. Format: dd-mm-yyyy.
   change_date	string	Last account change date except for password change or password reset. Format: dd-mm-yyyy.
   change_indicator	string	Number of days since last customer account update, not including password change or reset. Possible values: 01—updated in this transaction 02—updated less than 30 days ago 03—updated 30−60 days ago 04—updated over 60 days ago
   pass_change_date	string	Last password change or password reset date. Format: dd-mm-yyyy.
   pass_change_indicator	string	Number of days since the last password change or reset. Possible values: 01—password never changed 02—changed in this transaction 03—changed less than 30 days ago 04—changed 30−60 days ago 05—changed over 60 days ago
   payment_age	string	Card record creation date. Format: dd-mm-yyyy.
   payment_age_indicator	string	Number of days since the payment card details were saved in a customer account. Possible values: 01—current payment uses no customer account (guest checkout) 02—card details were saved today 03—card details were saved less than 30 days ago 04—card details were saved 30 to 60 days ago 05—card details were saved more than 60 days ago
   provision_attempts	integer	Number of attempts to add card details in customer account in the last 24 hours. Maximum 3 characters (999).
   purchase_number	integer	Number of purchases with this cardholder account in the previous six months. Maximum 4 characters (9999).
   suspicious_activity	string	Suspicious activity detection result. Possible values: 01—no suspicious activity detected 02—suspicious activity detected

2. Encode the JSON object by using the Base64 scheme.

   Figure: Sample Base64-encoded string

   eyAKICAiY3VzdG9tZXIiOnsgCiAgICAiYWRkcmVzc19tYXRjaCI6dHJ1ZSwKICAgICJob21lX3Bob25lIjoiNzkxMDUyMTExMTEiLAogICAgIndvcmtfcGhvbmUiOiI3NDk1NTIxMTExMSIsCiAgICAiYWNjb3VudCI6eyAKICAgICAgImFkZGl0aW9uYWwiOiJnYW1lcjEyMzQ1IiwKICAgICAgImFnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJkYXRlIjoiMDEtMTAtMjAxOSIsCiAgICAgICJjaGFuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAiY2hhbmdlX2RhdGUiOiIwMS0xMC0yMDE5IiwKICAgICAgInBhc3NfY2hhbmdlX2luZGljYXRvciI6IjAxIiwKICAgICAgInBhc3NfY2hhbmdlX2RhdGUiOiIwMS0xMC0yMDE5IiwKICAgICAgInB1cmNoYXNlX251bWJlciI6MTIsCiAgICAgICJwcm92aXNpb25fYXR0ZW1wdHMiOjE2LAogICAgICAiYWN0aXZpdHlfZGF5IjoyMiwKICAgICAgImFjdGl2aXR5X3llYXIiOjIyMjIsCiAgICAgICJwYXltZW50X2FnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJwYXltZW50X2FnZSI6IjAxLTEwLTIwMTkiLAogICAgICAic3VzcGljaW91c19hY3Rpdml0eSI6IjAxIiwKICAgICAgImF1dGhfbWV0aG9kIjoiMDEiLAogICAgICAiYXV0aF90aW1lIjoiMDEtMTAtMjAxOTEzOjEyIiwKICAgICAgImF1dGhfZGF0YSI6ImxvZ2luXzAxMDIiCiAgICB9CiAgfQp9

This string is passed as the value of the customer_account_info parameter which is included amongst other parameters in Payment Page invocation request.

New parameter: customer_shipping

The customer_shipping parameter is used in Payment Page invocation request. The parameter value is a Base64-encoded string which contains shipping details.

The value for the customer_shipping parameter is generated as follows:

1. Add the shipping details in a shipping JSON object and then insert it into a customer object as shown in the following sample.

   Figure: Sample JSON object code

   { 
     "customer":{ 
       "shipping":{ 
         "type":"01",
         "delivery_time":"01",
         "delivery_email":"test@gmail.com",
         "address_usage_indicator":"01",
         "address_usage":"01-10-2019",
         "city":"Moscow",
         "country":"RU",
         "address":"Lenina street 12",
         "postal":"109111",
         "region_code":"RU",
         "name_indicator":"01"
       }
     }
   }

   Table 3. Objects and parameters for the customer_shipping parameter

   Parameter	Type	Description
   shipping—object that contains shipment details
   address	string	Shipping address. Maximum 150 characters.
   address_usage	string	First shipping address usage date in the dd-mm-yyyy format.
   address_usage_indicator	string	Number of days since the first time usage of the shipping address. Possible values: 01—this transaction 02—less than 30 days ago 03—30−60 days ago 04—more than 60 days ago
   city	string	Shipping city. Maximum 50 characters.
   country	string	Shipping country in the ISO 3166-1 alpha-2 format, for example GB.
   delivery_email	string	The email to ship purchased digital content, if the customer chooses email delivery. Maximum 255 characters.
   delivery_time	string	Shipment terms. Possible values: 01—digital delivery 02—same-day delivery 03—overnight delivery 04—longer than overnight delivery
   name_indicator	string	Shipment recipient flag. 01—customer and shipment recipient are the same person 02 —customer and shipment recipient are different persons
   postal	string	Shipping postbox number. Maximum 16 characters.
   region_code	string	State, province, or region code in the ISO 3166-2 format. Example: SPE for Saint Petersburg, Russia. If you specify this parameter, you need also to specify and populate the country parameter in the shipping object.
   type	string	Shipment indicator. Possible values: 01—ship to cardholder billing address 02—ship to another verified address on file with merchant 03—ship to address that is different from the cardholder billing address or any verified address on file with merchant 04—ship to local store 05—digital goods shipment 06—no shipment, for instance for travel or event tickets 07—other, for example gaming or subscriptions

2. Encode the JSON object by using the Base64 scheme.

   Figure: Sample Base64-encoded string

   eyAKICAiY3VzdG9tZXIiOnsgCiAgICAic2hpcHBpbmciOnsgCiAgICAgICJ0eXBlIjoiMDEiLAogICAgICAiZGVsaXZlcnlfdGltZSI6IjAxIiwKICAgICAgImRlbGl2ZXJ5X2VtYWlsIjoidGVzdEBnbWFpbC5jb20iLAogICAgICAiYWRkcmVzc191c2FnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJhZGRyZXNzX3VzYWdlIjoiMDEtMTAtMjAxOSIsCiAgICAgICJjaXR5IjoiTW9zY293IiwKICAgICAgImNvdW50cnkiOiJSVSIsCiAgICAgICJhZGRyZXNzIjoiTGVuaW5hIHN0cmVldCAxMiIsCiAgICAgICJwb3N0YWwiOiIxMDkxMTEiLAogICAgICAicmVnaW9uX2NvZGUiOiJSVSIsCiAgICAgICJuYW1lX2luZGljYXRvciI6IjAxIgogICAgfQogIH0KfQ==

This string is passed as the value of the customer_shipping parameter which is included amongst other parameters in Payment Page invocation request.

New parameter: customer_mpi_result

The customer_mpi_result parameter is used in Payment Page invocation request. The parameter value is a Base64-encoded string which contains the information about the previous authentication attempt of the current customer.

1. Add the previous authentication attempt data in a mpi_result JSON object and then insert it into a customer object as shown in the following sample.

   Figure: Sample JSON object code

   { 
     "customer":{ 
       "mpi_result":{ 
         "acs_operation_id":"00000000-0005-5a5a-8000-016d3ea31d54",
         "authentication_flow":"01",
         "authentication_timestamp":"201812141050"
       }
     }
   }

   Table 4. Objects and parameters for the customer_mpi_result parameter

   Parameter	Type	Description
   mpi_result—object that contains information about previous customer authentication
   acs_operation_id	string	The ID the issuer assigned to the previous customer operation and returned in the acs_operation_id parameter inside the callback with payment processing result. Maximum 36 characters.
   authentication_flow	string	The flow the issuer used to authenticate the cardholder in the previous operation and returned in the authentication_flow parameter of the callback with payment processing results. Possible values: 01—frictionless flow 02—challenge flow
   authentication_timestamp	string	Date and time of the previous successful customer authentication as returned in the mpi_timestamp parameter inside the callback message with payment processing result.

2. Encode the JSON object by using the Base64 scheme.

   Figure: Sample Base64-encoded string

   eyAKICAiY3VzdG9tZXIiOnsgCiAgICAibXBpX3Jlc3VsdCI6eyAKICAgICAgImFjc19vcGVyYXRpb25faWQiOiIwMDAwMDAwMC0wMDA1LTVhNWEtODAwMC0wMTZkM2VhMzFkNTQiLAogICAgICAiYXV0aGVudGljYXRpb25fZmxvdyI6IjAxIiwKICAgICAgImF1dGhlbnRpY2F0aW9uX3RpbWVzdGFtcCI6IjIwMTgxMjE0MTA1MCIKICAgIH0KICB9Cn0=

This string is passed as the value of the customer_mpi_result parameter which is included amongst other parameters in Payment Page invocation request.

New parameter: billing_region_code

Existing parameters involved in authentication flow selection

To make selection of the frictionless flow authentication more likely, we recommend that you use some of the existing parameters—in addition to the new ones that are described in the previous sections. The following table describes the existing parameters of the customer object you can use to facilitate authentication.

These parameters are described in greater details here: Payment Page invocation parameters.