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
    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

Parameter Type Description
billing_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.

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.