Accepting 3-D Secure payments

Overview

Checkout can be used for applying 3D-Secure authentication to your payments. Checkout accepts both 3D-Secure 1 and 2. If the card is enrolled for 3D-Secure 2 an automatic fallback is done to 3D-Secure 1. The outcome of the authentication can be deduced from the query string parameters appended to the returnUrl, read Handling responses for more information. After adding the appropriate configuration for 3D-Secure in the create Checkout API call the page will take care of the rest.

Customer requirements

To process 3D-Secure authentications it is required to add a customer to the Checkout creation call. 3D-Secure has specific requirements for creating customers. You should make sure that all required fields are provided, else the page would result in a failure once the Customer tries to submit a payment with it.

The following table explains what fields are required (R), optional, (O) or conditional (C) when creating a customer that will be used for 3D-Secure. These requirements override what formatting requirements in the API are.

Here is an example request with the required fields for creating a customer for 3D-Secure. Replace the entityId with your own.

{
    "billing": {
        "address1": "Street 1",
        "city": "City",
        "countryCode": "NL",
        "firstName": "John",
        "lastName": "Gilmore",
        "postalCode": "1016 AB",
        "state": "NH"
    },
    "emailAddress": "john.gilmore@test.com",
    "entityId": "{entityId}",
    "phoneNumber": "+31123456789",
}

The response for creating the customer will look like this.

{
    "id": "string",
    "billing": {
        "address1": "Street 1",
        "city": "City",
        "countryCode": "NL",
        "firstName": "John",
        "lastName": "Gilmore",
        "postalCode": "1016 AB",
        "state": "NH"
    },
    "createdAt": "2020-07-01",
    "emailAddress": "john.gilmore@test.com",
    "entityId": "{entityId}",
    "phoneNumber": "+31123456789",
    "updatedAt": "2020-07-01"
}

Required 3-D Secure fields

To configure Checkout for accepting card payments the following fields are required:

• entityId - This value can be found in the portal or provided to you by a Verifone employee.
• currencyCode
• amount
• merchantReference
• returnUrl
• customer - This id is returned when creating a customer.
• configurations.card.paymentContractId - This id can be found in the portal or given to you by a Verifone employee. This id used to determine which MID should be used for processing the transaction
• configurations.card.threedSecure.threeDSContractId - 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.threedSecure.enabled - Has to be set to true
• configurations.card.threedSecure.transactionMode

Optional 3D-Secure configuration fields can be found in the Create Checkout API.

Optional Checkout parameters for Accepting card payments. 

Here is an example POST request with the required fields that can be copied for creating a Checkout. Replace the following fields with your own ids.

• entityId
• paymentContractId
• threeDSContractId

{
  "entityId": "{entityId}",
  "currencyCode": "EUR",
  "amount": 100,
  "customer": "{customerId}",
  "configurations": {
    "card": {
      "paymentContractId": "{paymentContractId}",
      "threedSecure": {
        "threeDSContractId": "{threeDSContractId}",
        "enabled":true,
        "transactionMode":"S"
      }
    }
  },
  "merchantReference": "test transaction",
  "returnUrl": "https://verifone.com"
}

 The response for creating the checkout will look like this.

{
  "id": "string",
  "url": "string"
}

The response body consists of several components.

id - Checkout identifier, used for later on lookup in order to determine the outcome of the Checkout

url - URL of the newly created Checkout page, which the Customer should be sent to

When the customer has completed the checkout successfully they will be redirected to the returnUrl:

{returnUrl}?transactionId={transactionId}&checkoutId={checkoutId}

See Handling responses for all possible Checkout outcomes.