## 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:
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 `
### 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.
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:
### 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:
For failed payments:
## 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:
|$5.69||Frictionless flow that is successful|
|$5.72||Frictionless flow that is unsuccessful|
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.