Skip to main content

Online payments

Accepting 3-D Secure payments

Last updated: 18-Apr-2022
Rate this article:

Overview

Card payments via the Checkout can also be used with 3-D Secure authentications. 3-D Secure 1 and 2 are supported, with automatic fallback in case the card is not enrolled for 3-D Secure 2.

Customer requirements

To process 3-D Secure authentications, it is required to add a customer to the Checkout creation call. Customer records can be created and managed via the Customer APIs. The table below details the required fields and their formats for creating a customer record to be compatible with 3-D Secure.

Note: You should make sure that all required fields are provided in their correct formats, else the page would result in a failure once the Customer tries to submit a payment with it. The field requirements below take priority over the API schema described in the Customer API reference.

Required = R, Optional = O, Conditional = C

Field name Description Status Observation Specification
billing.address_1 Customer's billing address information. R   String (50)
billing.address_2 Customer's billing address information. C Required if information is available. String (50)
billing.address_3 Customer's billing address information. C Required if information is available. String (50)
billing.city Customer's city on their billing address. R   String (50)
billing.country_code Customer's alpha 2-digit ISO 3166 country code. (e.g., United States = US) R Customer's alpha 2-digit ISO 3166 country code. String (2)
billing.first_name Customer's billing first name. R Required in case that companyName is not provided. String (50)
billing.last_name Customer's billing last name. R Required in case that companyName is not provided. String (50)
billing.phone Customer's phone number for billing address. This should be unformatted without hyphens. (e.g., 4422345678) C Required if information is available. This should be un formatted without hyphens. String (20)
billing.postal_code Customer's postal code of their billing address. C   String (10)
billing.state Customer's state or province of their billing address. Should be the country subdivision code defined in ISO 3166-2. If this field is not provided, the 3DS service will try to automatically populate it, based on the billing.countryCode and billing.postalCode values. C Required if information is available. String (50)
company_name Company name. C If billing.firstName or billing.lastName are not provided. String (100)
company_registration_number Unique identifier of the company, recognized by the government. Known as CoC (Chamber of Commerce) number in some countries. O   String
date_of_birth The date of birth of a person, 10 characters, ISO-8601 (YYYY-MM-DD). O   String (10)
email_address Customer's email address. R   String (255)
entity_id The entityId obtained from Verifone Central. The Entity ID can be found in Verifone Central under Administration → Organisations. The 'Organisation ID' listed is the Entity ID. R   String
phone_number Cardholder's mobile phone number. C   Number (25)
shipping.address_1 Customer's shipping address information. C Required if information is available. String (50)
shipping.address_2 Customer's shipping address information. C Required if information is available. String (50)
shipping.address_3 Customer's shipping address information. C Required if information is available. String (50)
shipping.city Customer's city of their shipping address. C Required if information is available. String (50)
shipping.first_name Customer's shipping first name. O    
shipping.last_name Customer's shipping first name. O    
shipping.country_code Customer's alpha 2-digit ISO 3166 country code. (e.g., United States = US) C Required if information is available. String (2)
shipping.postal_code Customer's postal code of their shipping address. C Required if information is available. String (10)
shipping.state Customer's state or province of their shipping address. (e.g., Ohio = OH, Texas = TX) Should be the country subdivision code defined in ISO 3166-2. If this field is not provided, the 3DS service will try to automatically populate it, based on the shipping.countryCode and shipping.postalCode values. C Required if information is available. String (3)
title mr or ms O   String
work_phone Customer's work phone number. C Required if information is available. Number (25)

Here is an example request with the required fields for creating a customer for 3-D Secure:

{
    "billing": {
        "address_1": "Street 1",
        "city": "Amsterdam",
        "country_code": "NL",
        "first_name": "John",
        "last_name": "Gilmore",
        "postal_code": "1016 AB",
        "state": "NH"
    },
    "email_address": "john.gilmore@test.com",
    "entity_id": "{entityId}",
    "phone_number": "31123456789",
}

The response for creating the customer will look like this:

{
    "id": "string",
    "billing": {
        "address_1": "Street 1",
        "city": "Amsterdam",
        "country_code": "NL",
        "first_name": "John",
        "last_name": "Gilmore",
        "postal_code": "1016 AB",
        "state": "NH"
    },
    "created_at": "2020-07-01",
    "email_address": "john.gilmore@test.com",
    "entity_id": "{entityId}",
    "phone_number": "31123456789",
    "updated_at": "2020-07-01"
}

 

Required 3-D Secure fields

To configure Checkout for accepting 3-D Secure card payments, the following fields are required in addition to the fields required for a standard Card payment:

  • configurations.card.threed_secure.threeds_contract_id - This ID can be found in the portal or given to you by a Verifone employee. This object stores the credentials for connecting to the 3-D Secure service.
  • configurations.card.threed_secure.enabled - Has to be set to true.
  • configurations.card.threed_secure.transaction_mode

The complete list of 3-D Secure and other optional fields can be found in the Create Checkout API.

Example request:

{
    "amount": 9998,
    "currency_code": "EUR",
    "entity_id": "{{entity_id}}",
    "customer": "{{customer_id}}",
    "configurations": {
        "card": {
            "payment_contract_id": "{{payment_contract_id}}",
            "threed_secure": {
                "enabled": true,
                "threeds_contract_id": "{{3ds_contract_id}}",
                "total_items": "01",
                "transaction_mode": "S"
            }
        }
    },
    "merchant_reference": "ORDER-1234",
    "return_url": "{{merchant_return_url}}"
}

Handling responses

Upon completion of a 3DS checkout, a redirection occurs including an additional query parameter "authentication_id" which can be used to retrieve the 3DS complete details from the 3DS service.

See Handling card responses for all possible Checkout outcomes.

Rate this article:

Need help?

Do you have a question? On our Support page you will find a list with answers to frequently asked questions.
Did not find the answer you are looking for? Please contact us. We are happy to help.

Logo of Verifone