Skip to main content

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.

Field name Description Required/Optional/Conditional Specification
billing.address1 Customer's billing address information. R String (50)
billing.address2 Customer's billing address information. C Required if information is available String (50)
billing.address3 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.countryCode Customer's alpha 2 digit ISO 3166 country code. (e.g. United States = US) R String (2)
billing.firstName Customer's billing first name. R String (50)
billing.lastName 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 Required if information is available String (20)
billing.postalCode Customer's postal code of their billing address. R 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 (3)
companyName Company name C if billing.firstName or billing.lastName not provided String
companyRegistrationNumber Unique identifier of the company, recognised by the government. Known as CoC (Chamber of Commerce) number in some countries. O String
dateOfBirth The date of birth of a person, 10 characters, ISO-8601 (YYYY-MM-DD) O String (10)
emailAddress Customer's email address. R String (255)
gender male or female O String (male or female)
entityId The entityId R String
phoneNumber Cardholder's mobile phone number R Number (25)
shipping.address1 Customer's shipping address information. C Required if information is available String (50)
shipping.address2 Customer's shipping address information. C Required if information is available String (50)
shipping.address3 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.countryCode Customer's alpha 2 digit ISO 3166 country code. (e.g. United States = US) C Required if information is available String (2)
shipping.postalCode 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)
socialSecurityNumber The social security number of the customer. Only supported for DK, FI, NO & SE. O String
title mr or ms O String
workPhone 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. 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.

About us

Verifone logo

Contact

Support

 

Facebook  Twitter  Linkedin