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

R = Required,
O = Optional,
C = Conditional

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.address@verifone.com"
    }
}

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.