Accepting 3D Secure payments
Overview
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.
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 3D 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 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.