3D Secure

3D Secure (3DS) is a protocol to combat fraudulent transactions. Since version 2, it has been standardised by a consortium of card schemes (EMVCo).

Card schemes have built their own branded implementations based on these standards, so it may be referred to as Visa Secure, Mastercard Identity Check, American Express SafeKey or Diners Club ProtectBuy in those respective contexts.

To combat fraudulent card payments, 3DS introduces additional processes to more accurately determine that the card is being presented by its true owner at the point of payment.

In practice, 3DS requires cardholders complete an extra authentication step with their card issuer when making a payment, by redirecting the cardholder to a specific part of their bank’s online system. The cardholder may be prompted here to enter a known password, or confirm a code delivered to their phone to authorise the payment. This helps protect you as a merchant from fraudulent transactions where the payment is not authorised by the true cardholder.

How 3D Secure works

Whenever a cardholder makes a payment, 3DS allows the merchant and a payment provider like Pin Payments to send additional data to the cardholder’s bank to better assess the transaction risk. Within the Pin Payments platform, this takes place behind the scenes and this data does not need to be explicitly provided.

Based on this data, the cardholder’s bank will then choose whether to immediately authenticate the payment (frictionless flow), or ask for more information before authenticating the payment (challenge flow).

Frictionless flow

If the data is sufficient for the bank, the payment will qualify for frictionless authentication and will complete without affecting the cardholder’s experience (apart from some additional redirections, which will be imperceptible to most customers).

Challenge flow

If the cardholder’s bank decides more proof is required, the authentication will follow the challenge flow and your customer will be prompted for additional information to authenticate themselves. This is often an SMS code sent to a registered phone, or an existing password that the cardholder is expected to know.

Completion

After authentication, the customer is redirected back to the merchant system, where the result of the authentication is provided. Only if the cardholder is successfully authenticated should you collect the payment and fulfil the transaction.

3D Secure via the Payment Page

Your Payment Page supports 3DS as standard.

Simply providing your Payment Page link to your customer and having them complete payment via this method will direct them through a 3DS enriched payment.

3D Secure via the API

For merchants with more complex requirements—those that run their own shopping carts, stores, or platforms—you may utilise 3DS via the API.

1. Request authentication via the charges endpoint

   Submit a standard charge creation request and provide the three_d_secure block, including the required fields "enabled":true and a callback_url which handles the 3DS result:

     {
       "amount": 10_00,
       "currency": "AUD",
       ...
       "three_d_secure": {
         "enabled": true,
         "callback_url": "https://yoursite.com/completion"
       }
     }
   

   If the card is enrolled for 3DS, you’ll receive a 202 - Accepted HTTP status response containing a redirect_url link, which you should redirect your customer’s browser to.

   The payload of this response has the following form:

     {
       "response": {
         "token": "ch_D8lyKJC8PgZcSKDUJ4QuFQ",
         "status_message": "Pending",
         "redirect_url": "https://sandbox.checkout.com/api2/v2/3ds/acs/sid_feixbit6us3utfedjulm6egnsu"
       }
     }
   

   The cardholder will arrive on their bank’s 3DS Access Control Server (ACS), which may then prompt them to verify their identity—generally with a password or SMS code delivered to their phone.

   Regardless of outcome, the cardholder is then redirected back to the callback_url you provided in the three_d_secure block of the initial Charge request.

2. Receive session token

   When the customer is redirected back to your site, a session_token query string parameter is provided at the end of the callback URL. It will look something like this:

   https://yoursite.com/completion?session_token=se_sGt9PuNYfVzJqTSLP2CV8g

   You should use the session_token to determine whether the payment was successful.

3. Verify the charge was successful

   To find out if the payment was successful, verify the payment against the charge verification endpoint.

   GET /charges/verify?session_token=se_sGt9PuNYfVzJqTSLP2CV8g

   With this endpoint you will receive a charge represented in JSON form, like the standard GET charges endpoint. Check the success field; if true then the payment was successful.

Handling cards that are not enrolled for 3D Secure

If the customer’s card is not enrolled for 3DS, or the card type isn't yet supported, you may want to attempt the transaction without 3DS. To indicate you are happy to do so, include the field "fallback_ok": true.

  {
    "amount": 10_00,
    "currency": "AUD",
    ...
    "three_d_secure": {
      "enabled": true,
      "fallback_ok": true,
      "callback_url": "https://yoursite.com/completion"
    }
  }

See the card types we support for 3D Secure.

When the card type is not supported and `fallback_ok: true` is provided in the Charge request, the response will be a normal 201 success as documented here.