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:
- 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
objectParameter Type Description challenge_indicator
string This parameter indicates whether challenge flow is requested for this payment.
Possible values:01
—no preferences02
—it is preferable not to use challenge flow03
—challenge flow preferred04
—always use challenge flow
challenge_window
string The dimensions of a window in which authentication page opens.
Possible values:01
—250 x 400 px02
—390 x 400 px03
—500 x 600 px04
—600 x 400 px05
—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 stock02
—future merchandise availability
reorder
string This parameter indicates whether the cardholder is reordering previously purchased merchandise.
Possible values:01
—first time order02
—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. - 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:
- 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
objectParameter Type Description address_match
string The parameter indicates whether the customer billing address matches the address specified in the
shipping
object.Possible values:Y
—matchesN
—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 merchantadditional
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-out02
—customer account was created in this transaction03
—customer account was created less than 30 days ago04
—customer account was created 30 to 60 days ago05
—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 authentication02
—log on by using authentication data on file with merchant03
—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 transaction02
—updated less than 30 days ago03
—updated 30−60 days ago04
—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 changed02
—changed in this transaction03
—changed less than 30 days ago04
—changed 30−60 days ago05
—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 today03
—card details were saved less than 30 days ago04
—card details were saved 30 to 60 days ago05
—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 detected02
—suspicious activity detected
- 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:
- Add the shipping details in a
shipping
JSON object and then insert it into acustomer
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
parameterParameter Type Description shipping
—object that contains shipment detailsaddress
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 theshipping
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
-
- 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.
- Add the previous authentication attempt data in a
mpi_result
JSON object and then insert it into acustomer
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
parameterParameter Type Description mpi_result
—object that contains information about previous customer authenticationacs_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. -
- 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
Parameter | Type | Description |
---|---|---|
billing_region_code |
string |
State, province, or region code in the ISO 3166-2 format. Example: If you specify this parameter, you need also to specify and populate the |
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.
Parameter | Type | Description |
---|---|---|
billing_address
|
string | Street of the customer billing address |
billing_city
|
string | City of the customer billing address |
billing_country
|
string | Country of the customer billing address in the ISO 3166-1 alpha-2 format |
billing_postal
|
string | Postcode of the customer billing address |
customer_email
|
string | Customer email |
customer_phone
|
string | Customer phone number. From 4 to 24 digits |
These parameters are described in greater details here: Payment Page invocation parameters.