# 3D Secure payments
[Card payments](/online-payments/checkout/accepting-payments/card-payments.md) 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](/api-reference/open-api-references/customer.md) APIs**.** The table below details the required fields and their formats for creating a customer record to be compatible with 3D Secure.
{% hint style="info" %}
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/open-api-references/customer.md) API reference.
{% endhint %}
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:
```json
{
"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.address@verifone.com"
}
}
```
The response for creating the customer will look like this:
```json
{
"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](/online-payments/checkout/accepting-payments/card-payments.md):
* `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](https://verifone.cloud/api-catalog/checkout-documentation#/default/postV1Checkout).
**Example request**:
```apache
{
"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](/online-payments/checkout/accepting-payments/card-payments.md#handling-responses) for all possible Checkout outcomes.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.verifone.com/online-payments/checkout/accepting-payments/3d-secure-payments.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.