Payment request formats

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.

Request standard formats in Gate are covered in details in Interaction concepts. The new objects and parameters are described in this section.

New object: acs_return_url

The acs_return_url object contains the data required to return the customer to the web service after authentication is complete and to accept receipt acknowledgments from the Access Control Server when using extended authentication workflow.

Parameter Type Description
return_url string The address to redirect the customer back to the web service after authentication. Mandatory, if you use extended authentication workflow. The value of this parameter must be the same as the value of the TermUrl parameter in the customer redirection information (see below).
3ds_notification_url string The address the web service uses for accepting receipt acknowledgements. Mandatory, if you need to accept the receipt acknowledgements when using extended authentication workflow.

New entities in the customer object

The customer object is extended with new parameters which we broke into the following categories:

  • Customer browser properties
  • Details of the customer account on record with the web service
  • Shipping details
  • Details of the previous customer authentication procedure

The tables that follow describe these parameters in greater details.

Table 1. Customer browser properties
Parameter Data type Description
accept_header string Accept HTTP header as received from customer browser.
color_depth integer Color depth of customer browser, bits per pixel.
java_enabled boolean The parameter indicates whether customer browser supports Java.
js_enabled boolean The parameter indicates whether customer browser supports JavaScript.
timezone_offset string UTS offset of customer browser time in minutes. Example: -120.
Table 2. Details of the customer account on record with the web service
Parameter Type Description
address_match boolean

The parameter indicates whether the customer billing address matches the address specified in the shipping object.

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, for 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-yyyyThh: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.

format.
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
Table 3. Shipping details
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
Table 4. Details of the previous customer authentication procedure
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.

New entities in 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
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.

New parameter in the billing object

Parameter Type Description
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 billing_country parameter of this object.

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
email string Customer email.
phone string Customer phone number. From 4 to 24 digits.
billing—object with customer billing address details.
address string Street of the customer billing address.
city string City of the customer billing address.
country string Country of the customer billing address, in ISO 3166-1 alpha-2 format
postal string Postcode of the customer billing address