3D Secure Authentication

What is 3D Secure?

3D Secure (3DS) introduces an additional authentication step to your payment flow and helps to reduce fraud and in some cases, meet regulatory requirements. For different card networks, it's known by the names Visa Secure and Mastercard Identity Check.

📘

European Strong Customer Authentication (SCA) regulations require that 3DS is the verification method used for card payments. When signing up for a Circle Account, please reach out to your account manager to see if these requirements apply to you.

If 3DS is not required, its use is still encouraged due of its ability to reduce fraud.

In most cases, when 3DS is requested, you will redirect your customer to a page on their bank's website, where they will authenticate via a PIN associated with the card or by entering a one-time passcode that has been sent to their phone (either a text message or a push notification).

📘

Support for 3D Secure v1 and v2

Our Payments API supports both the original version of 3D Secure (3DS1) as well as the newer 3D Secure 2, which offers benefits like frictionless authentication. When customers present a card that is not supported by 3DS2, we will automatically fall back to 3DS1 without any changes needed in your API integration.

For some businesses, using 3DS for payments can shift the liability of fraudulent chargebacks from you, the merchant, to the customer's issuing bank. Please reach out to your account manager to understand whether this benefit applies to your business.

Using 3D Secure

3DS is available for all Circle Accounts, even when it is not a requirement.

Setting 3DS as the Verification Method

To use 3DS verification for a payment, during the payment creation API call, pass in three_d_secure as the verification method and provide two additional URLs to take the user to on 3DS success/failure:

{
  "amount": {
    "amount": "3.14",
    "currency": "USD"
  },
  "source": {
    "id": "...",
    "type": "card"
  },
  "verification": "three_d_secure",
  "verificationSuccessUrl": "https://example.org/payment_success",
  "verificationFailureUrl": "https://example.org/payment_failure",
  ...
}

After visiting their bank's website, if their payment is successful, your customer will be redirect to the verificationSuccessUrl that you set. On a failed payment (e.g., if they are unable to enter the correct PIN or code), they will be redirected to verificationFailureUrl.

Required Action and Redirecting

Soon after payment creation, the status of the payment will change from pending to action_required and you will receive a webhook informing you that additional action is required, and a URL will be provided. Your customer will need to be taken to this URL and authorize the transaction.

{
  "id": "...",
  "type": "payment",
  "amount": {
    "amount": "3.14",
    "currency": "USD"
  },
  "source": {
    "id": "...",
    "type": "card"
  },
  "status": "action_required",
  "requiredAction": {
    "type": "three_d_secure_required",
    "redirectUrl": "https://web.circle.com/..."
  },
  ...
}

While the redirectUrl points to a Circle endpoint, it will automatically redirect to your customer's banking website.

Authentication Flow

Once you take your customer to the redirectUrl, they will be presented with one of two flows: a challenge flow where they will enter a PIN or one-time passcode, or a frictionless flow where no explicit action is required.

The frictionless flow automatically determines the authentication outcome without any customer interaction, and leverages details of the payment and information derived from the device. The customer will automatically be redirected to the verificationSuccessUrl or verificationFailureUrl, based on the outcome.

In the challenge flow, typically your customer has either already set up a PIN to use for all 3DS payments, or their issuing bank will send them a text message or push notification for a one-time code to enter.

In a production environment, your customer may see something like:

While in Sandbox, you'll see a more generic challenge flow:

When the customer enters the correct code, they will be taken to the success URL you specified. Otherwise, they will be redirected to the failure URL.

The 3DS authentication flow needs to be completed within 15 minutes of payment creation. Beyond this, payments with status: action_required will move to status: failed, and if another payment attempt is desired, a new payment will need to be created.

Redirect Behavior

At the conclusion of both the frictionless and challenge flows, your customer will be redirected to the URLs you provided during initial payout creation. Both of these should be pages that your service hosts, and this provides you an opportunity to guide the customer on to the next part of your payment or checkout flow.

An additional paymentId parameter will be added as a query parameter to both verificationSuccessUrl and verificationFailureUrl, so that you can add additional context or decide your own redirect logic. This parameter represents the id of the payment that you created:

https://example.org/payment_success?paymentId=4b75bab-ad7d..

Payment Status

In addition to the failure and success redirects, the status of your payment will also be updated to confirmed or failed, and a corresponding webhook notification will be sent.

For successful payments:

{
  "id": "...",
  "type": "payment",
  "amount": {
    "amount": "3.14",
    "currency": "USD"
  },
  "source": {
    "id": "...",
    "type": "card"
  },
  "verification": {
    "threeDSecure": "pass"
  },
  "status": "confirmed",
  ...
}

For failed payments:

{
  "id": "...",
  "type": "payment",
  "amount": {
    "amount": "3.14",
    "currency": "USD"
  },
  "source": {
    "id": "...",
    "type": "card"
  },
  "verification": {
    "threeDSecure": "fail"
  },
  "status": "failed",
  "errorCode": // to be provided
  ...
}

3D Secure in Sandbox

Triggering Specific 3DS Flows

The following payment amounts, when used in conjunction with Test Card Numbers in the Sandbox environment, will produce predetermined outcomes so that you can test your 3DS payment flows:

Using values other than what's specified above will trigger the successful frictionless flow.

Challenge Flow

When confronted with a challenge flow in the Sandbox environment, enter circle12345 for a successful payment outcome. Incorrect codes will result in a failed payment.