3D Secure payments

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

Customer requirements

To process 3D 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 3D Secure.

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.

R = Required, O = Optional, C = Conditional

Field name	Description	Status	Specification / Observation
billing.address_1	Customer's billing address information.	R	String (50)
billing.address_2	Customer's billing address information.	C	String (50) / Required if information is available.
billing.address_3	Customer's billing address information.	C	String (50) / Required if information is available.
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	String (2) / Customer's alpha 2-digit ISO 3166 country code.
billing.first_name	Customer's billing first name.	R	String (50)
billing.last_name	Customer's billing last name.	R	String (50)
billing.phone	Customer's phone number for billing address. This should be unformatted without hyphens. (e.g., 4422345678)	C	String (20) / Required if information is available. This should be un formatted without hyphens.
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	String (50) / Required if information is available.
company_name	Company name.	C	String (100) / If billing.firstName or billing.lastName are not provided.
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	String (50) / Required if information is available.
shipping.address_2	Customer's shipping address information.	C	String (50) / Required if information is available.
shipping.address_3	Customer's shipping address information.	C	String (50) / Required if information is available.
shipping.city	Customer's city of their shipping address.	C	String (50) / Required if information is available.
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	String (2) / Required if information is available.
shipping.postal_code	Customer's postal code of their shipping address.	C	String (10) / Required if information is available.
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	String (3) / Required if information is available.
title	Mr or ms	O	String
work_phone	Customer's work phone number.	C	Number (25) / Required if information is available.

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

{
    "entity_id": "entity_id",
    "currency_code": "currency",
    "amount": 1000,
    "configurations": {
        "card": {
            "payment_contract_id": "ppc",
            "threed_secure": {
                "threeds_contract_id": "3ds",
                "enabled": true
            }
        }
    },
    "customer_details": {
        "entity_id": "entity_id",
        "company_name": "Test company name",
        "billing":
{             "address_1": "123 Main Street",             "city": "City",             "country_code": "US"         }
,
        "email_address": "[email protected]"
    }
}

The response for creating the customer will look like this:

{
    "code": 126,
    "details":
{         "missing_parameters": [             "customer.billing.firstName",             "customer.billing.lastName"         ]     }
,
    "errors": [],
    "message": "Missing parameters from required schema",
    "name": "MISSING_SCHEMA_PARAMS_ERROR",
    "stack": "",
    "service": "CO",
    "timestamp": 1731876046828,
    "traceId": "c69b0bf5-56f8-490c-a07a-1106c0ebc411"
}

Required 3D Secure fields

To configure Checkout for accepting 3D 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 3D Secure service.

• configurations.card.threed_secure.enabled - Has to be set to true.

• configurations.card.threed_secure.transaction_mode

The complete list of 3D 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.