You're viewing our new Unified Payments API documentation. Click here to access our Classic API docs.

3D Secure payments

Verify your customers' online card payments with the new authentication standard.

Overview

The 3D Secure (3DS) protocol, commonly known by its branded names Verified by Visa, Mastercard SecureCode, American Express SafeKey and Diners Club ProtectBuy, introduced an additional layer of verification to protect you from liability for fraudulent card payments and make online payments more secure.

The next generation of authentication – 3D Secure 2 (3DS2) – is designed to help merchants in Europe comply with the new Strong Customer Authentication (SCA) requirements that will be introduced by the revised Payment Services Directive (PSD2) on 14 September 2019.

3DS2 uses a wider range of data and biometric authentication to allow for “frictionless authentication”, meaning a smoother checkout flow for both you and your customers – curbing cart abandonment rates and improving the user experience, all while improving the security of your payments.

And, if you're already using our existing 3DS integration, you don't have to do anything for now; we’ll transition you to 3DS2 as banks start to support it in April 2019.

If you do business in Europe, you must ensure that you can support 3DS2 and comply with SCA by 14 September 2019. This includes merchants who have not previously used 3DS.

What is Strong Customer Authentication?

When a customer makes an online payment, their bank may "challenge" them to provide more information before authenticating the payment – this is where SCA comes in.

SCA requires you to build additional authentication into your payment flow, using two out of the following three authentication elements:

  • Something the customers knows (e.g., a password or PIN)
  • Something the customer has (e.g., a mobile phone or wearable device)
  • Something the customer is (e.g., a fingerprint or facial recognition)

After 14 September 2019, banks will decline payments that require SCA and don’t meet these requirements.

When is Strong Customer Authentication required?

SCA will apply to “customer-initiated” payments – so, most online card payments and bank transfers. However, specific low-risk payments fall outside its scope or are exempt.

Exemptions to Strong Customer Authentication

If a payment falls into one of the SCA exemptions, we can request the relevant exemption when processing the payment. The customer's bank will then assess the risk of the payment and decide whether to accept the exemption or request strong authentication if it still thinks it necessary.

These exemptions include:

"Merchant-initiated” payments

Payments originating from the merchant where the payment is made with a saved card, such as direct debits, recurring payments and subscriptions, are exempt. However, to benefit from this exemption, you'll need to strongly authenticate the customer's card when you save it or when you take the first payment.

Low-risk payments

The payment may be exempted if the acquirer's or bank’s average fraud level for card payments, and the amount, does not exceed the following thresholds:

  • Below 0.13% and the payment is less than €100
  • Below 0.06% and the payment is less than €250
  • Below 0.01% and the payment is less than €500

Low-value payments

Payments below €30 are considered low-value and may be exempt. However, the bank may still trigger strong authentication if, within a 24-hour period, this exemption has been used five times since the customer's last successful authentication or the total value spent on the card without SCA exceeds €100.

Payments to a trusted business

The customer may add a merchant to a whitelist after the initial strong authentication, meaning all subsequent payments to that business will be exempt.

Mail order and telephone orders (MOTO) payments

Mail order payments and phone sales fall outside the scope of SCA.

Corporate payments

Corporate payments made with virtual and lodge cards (typically used for business travel expenses) or from central travel accounts are exempt.

How 3D Secure 2 works

With 3DS2, you can embed the authentication process in your checkout flow, resolving the clunky user experience that the original 3DS sometimes delivers.

Whenever a customer makes a payment, 3DS2 allows the merchant and a payment provider like us to send over 100 data elements (e.g., the customer's shipping address, device ID and payment history) to the cardholder's bank to assess its risk level. And this all takes place behind the scenes within your web or mobile checkout flow – no redirects needed.

Based on this data, the customer's bank will then choose to immediately authenticate the payment or ask for more information before authenticating the payment, directing the payment toward one of two flows:

Frictionless flow

If the data is sufficient for the bank (i.e., they trust that it is the cardholder making the payment), the payment will qualify for frictionless authentication and complete without affecting the customer's experience.

Challenge flow

If the bank decides it needs more proof, the authentication will follow the challenge flow and your customer will be prompted for additional information to authenticate their payment.

Liability shift
If the 3DS2 authentication is successful (whether following the frictionless or challenge flow), the liability for the payment is passed to the bank, protecting you from fraudulent transactions. However, if a payment relies on one of the exemptions mentioned above, the liability remains with you, the merchant.

How Checkout.com helps you get SCA-ready

We are delivering our 3DS2 solution in a phased approach, minimizing the impact on merchants who are currently using our existing 3DS integration and giving you the time to build an integration that best suits your needs.

Phase I

From April 2019, we will start to roll out our fully integrated browser 3DS2 solution. It will use our existing 3DS integration and we'll gather all the required information on your behalf – so no need to change your existing integration.

We'll then gradually switch traffic onto 3DS2, starting with European merchants whose issuers support the new protocol. If the bank does not yet support the new version, the request will automatically default to the original 3DS. We'll activate full 3DS2 support in each region in line with the card scheme networks’ release schedule.

Our 3DS2 solution will help you comply with SCA in two main ways:

  • Exemption flags in the authorization flow. This may result in soft declines, in which case we will automatically direct the transaction to an authentication flow where the bank asks for SCA authentication before authorizing the payment.
  • Flags for SCA-exempt payments, like low-value payments and those to trusted merchants, to help you achieve the highest conversion rates.

Phase II

From September/October 2019, the second phase of our rollout will give you a wider selection of integration options and the use of exemption flags in the authentication flow. You'll be able to submit additional optional fields to help with the banks' risk-based authentication (RBA) decisions, and split authentication and authorization into two steps (e.g., submitting authentications through Checkout.com, and submitting authorizations through a third party – and vice versa).

In addition, we are building a scheme token service to help merchants operating card-on file (COF) and subscription businesses comply with SCA. For such merchants, the initial payment must go through strong authentication, but, by using our scheme token service for COF processing, subsequent customer- and merchant-initiated payments will be exempted from SCA.

We'll continue to improve our solution and offer you more features and services as they become available.

Create a 3D Secure payment with a card token

Step 1: Collect a card token

First, the customer needs to enter their card details which are then exchanged for a card token. Card tokens are collected through one of our integration options; this process is called tokenization - tokenization - The industry standard process for protecting sensitive data by replacing it with an algorithmically generated number called a token. At Checkout.com we use tokenization to protect our customers' confidential payment information from fraudsters. Payment information is substituted with randomly generated numbers — the tokens — and passed to us over the internet. Using the token, we can locate the payment details from our secure vault and complete the request without the need to transfer any sensitive data. .

Step 2: Create a card token payment request

The difference between a standard card token payment and 3D Secure is the 3ds attribute. Set the enabled attribute to true — this defines the payment as 3D Secure.

You can see a 3D Secure payment request example below:

{
  "source": {
    "type": "token",
    "token":"tok_f6z4mnoububudpqnvhwa5ff27u"
  },
  "amount": 2000,
  "currency": "USD",
  "3ds": {
    "enabled": true
  }
}

Step 3: Redirect your customer

If the card is enrolled for 3D Secure, you receive a 202 - Accepted response containing a redirect link that you should redirect your customer to.

{
  "id": "pay_hehfmlkpykeupofyxf7nbr6yyy",
  "status": "Pending",
  "customer": {
    "id": "cus_u4a4zosnrw7ehhzr7jipbkdzo4"
  },
  "3ds": {
    "downgraded": false,
    "enrolled": "Y"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_hehfmlkpykeupofyxf7nbr6yyy"
    },
    "redirect": {
      "href": "https://sandbox.checkout.com/api2/v2/3ds/acs/sid_feixbit6us3utfedjulm6egnsu"
    }
  }
}

The customer is then prompted to verify their identity — generally with a password.

Redirection URLs
You can configure redirection success and redirection failure URLs in your Hub dashboard or in the payment request itself by setting the success_url and failure_url fields.

Step 4: Verify the payment with the session ID

When the customer is redirected back to your site, a cko-session-id querystring parameter is provided at the end of the success URL. It'll look something like this:

http://example.com/success?*cko-session-id=sid_ubfj2q76miwundwlk72vxt2i7q*

Once you've grabbed the cko-session-id, you can use our get payment details API to determine whether the payment was approved.

Endpoints

Live

GEThttps://api.checkout.com/payments/{id}

Sandbox

GEThttps://api.sandbox.checkout.com/payments/{id}

Header and path parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Path
Value

id
Required

The cko-session-id.

Use the approved field to check whether or not the authorization was successful ("approved": true). If your authorization was not successful, it's possible the payment used an invalid/expired card, or a valid card with an insufficient available balance.

The response includes an actions object, which only applies to 3D Secure payments. It gives you a summary of all the actions performed for that payment. This allows you to obtain the response code of the authorization if it was declined.


{
  "id": "pay_y3oqhf46pyzuxjbcn2giaqnb44",
  "requested_on": "2019-01-16T22:08:06Z",
  "source": {
    "type": "card",
    "id": "src_wmlfc3zyhqzehihu7giusaaawu",
  },
  "amount": 6540,
  "currency": "USD",
  "approved": false,
  "status": "Declined",
  "3ds": {
    "downgraded": false,
    "enrolled": "Y",
    "signature_valid": "Y",
    "authentication_response": "Y",
    "cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
    "xid": "MDAwMDAwMDAwMDAwMDAwMzIyNzY="
  },
  "eci": "06",
  "actions": [
    {
      "id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
      "type": "Authorization",
      "response_code": "20005",
      "response_summary": "Declined - Do Not Honour"
    }
  ],
  "_links": {
    "self": {
      "href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
    },
    "actions": {
      "href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/actions"
    }
  }
}

Handle non-enrolled cards

By default, when you request a 3D Secure payment and the card is not enrolled, the payment will be declined. If you wish to downgrade and process the payment as non 3D Secure, you can add the attempt_n3d field to your request as in the example below.

{
  "source": {
    "type": "token",
    "token":"tok_vtvlbgpyoaaubmldynpm32bali"
  },
  "amount": 2000,
  "currency": "USD",
  "3ds": {
    "enabled": true,
    "attempt_n3d": true
  }
}

Use the approved field to check whether or not the authorization was successful ("approved": true). If your authorization was not successful, it's possible the payment used an invalid/expired card, or a valid card with an insufficient available balance.

Please note:
The liability shift advantage of 3D Secure payments will not apply to downgraded (non-3D Secure) payments. This means that there will be no protection against potentially fraudulent payments or chargebacks.

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at support@checkout.com.

3D Secure payments


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.