3DS purchase
Make a purchase payment with 3DS in DEUNA.
1. Generate a payment
To create a payment, you can use the following two flows:
2. Use the payment response
In the payment response, you can see the following fields that are necessary to know that said charge requires the end user to authenticate:
{
"order": {
"order_id": "75029759-4a64-42cd-b0b6-9f12777707b7",
"currency": "USD",
"total_amount": 3150,
// ...
"status": "pending", // status of the order will be "pending"
"payment": {
"data": {
// ...
"method_type": "credit_card",
"id": "75029759-4a64-42cd-b0b6-9f12777707b7",
"processor": "kushki",
"status": "pending_3ds", // note here the payment status
"authorization_3ds": {
"version": "3DS2",
"url_challenge": "https://api.stg.deuna.io/transactions/view_challenge?token=01HC0XG8GA2GH5G684QW572507"
}
}
}
}
}
3DS fields
The important fields to consider are:
- The order status (
order.status
) ispending
, because it has not been paid yet. - The payment status (
payment.data.status
) ispending_3ds
. This status indicates that it's waiting for authentication by the cardholder. - For
challenge
type authentication cases (the user must take an action during authentication) orsemi-frictionless
(the user is presented with the 3DS flow but doesn't need to take an action), thepayment.data.next_action.authorization_3ds.url
property will contain the URL of the web page that should be presented to the buyer. For compatibility with previous integrations, it can also be found in thepayment.data.authorization_3ds.url_challenge
field.
3. Render the url_challenge
url_challenge
Render the url_challenge
from the acquirer`s page.

4. Redirect the user
Once authentication is finished, redirect the user to your callback_urls or to a default page.
For Direct API integrations, you are responsible for redirecting the user to that page or in case of mobile opening that page in a webView.
Use of 3DS Next action widget
For Direct API integrations where redirection management is not desired, use the 3DS Next action widget.
Depending on the payment provider and MPI, the URL must be opened in a completely new tab and not in an iFrame. Check with DEUNA to indicate according to the provider you're going to use.
If you use 3DS Next action widget and the payment provider or MPI supports the use of iFrame, ask DEUNA to configure the widget to render as iFrame instead of requiring redirection.
If you use widgets, then the widgets will be responsible for redirection or iFrame rendering and interpreting when the 3DS flow is required.
If you want to use callback_urls, then contact your implementation manager to activate this functionality.
Use of callback_urls:
Configure callbacks in:
- Forpurchase V1: send the
callback_urls
in the fieldspecific_fields.callbacks
. - Forpurchase V2: send the
callback_urls
in the fieldcallback_urls
.
Use of widgets
As your server only responsible for creating the order, the urls can be passed in the callback_urls
field.
DEUNA default page
The user is redirected to the following web page if you do not use callback_urls
after authentication:

Depending on the issuing bank, different challenge pages are obtained, but the redirection flow remains the same.
Authentication Timeouts
- During a 3-D Secure flow, shoppers may be asked to complete an authentication challenge—for example, by entering a one-time password or approving the transaction in their banking app. This challenge must be completed within a limited timeframe before it expires.
- The issuing bank controls the shopper's authentication experience. Most banks set relatively short time windows—typically between 3 and 5 minutes—to encourage prompt action. While the shopper is authenticating, the transaction remains in status
pending_3ds
. - Since challenge timeouts vary between issuing banks, DEUNA allows a maximum of 10 minutes for the authentication process to complete. During this period, the transaction status remains
pending_3ds
until the shopper either completes or abandons the challenge. - If the shopper does not complete the authentication challenge within the allowed timeframe, the transaction will fail due to timeout. In this scenario, the transaction status will be updated to
denied
, and the shopper must restart the checkout process.
5. Check the final payment status
DEUNA provides two ways to know the final payment status after 3DS authentication:
- Perform long polling of the Get Order API
- Listen to DEUNA webhooks
DEUNA recommends implementing both processes, so that you can either listen to webhooks or use long polling in case the server has intermittency.
Frictionless 3D-Secure
In the frictionless flow, the user is not requested any type of authentication verification when making the payment, since the ACS (Access Control Server) has validated the user's authenticity with the data provided in the purchase.
This provides a smoother experience for the user, increasing the payment approval rate and decreasing fraud.
To execute a successful Frictionless 3D-Secure purchase, collect certain information about the user such as:
- Full billing address
- Device fingerprint
- IP address
- Browser details
- Other relevant information about the user.
Example response
{
"order": {
"order_id": "75029759-4a64-42cd-b0b6-9f12777707b7",
"currency": "USD",
"total_amount": 3150,
// ...
"status": "succeeded",
"payment": {
"data": {
// ...
"method_type": "credit_card",
"id": "75029759-4a64-42cd-b0b6-9f12777707b7",
"processor": "kushki",
"status": "processed"
}
}
}
}
Radar Quality Excellent
The integration is designed to meet Deuna's excellence standards in fraud management and prevention. Send the necessary information to achieve the standard quality.
Radar session
The radar session data is sent automatically in the widgets.
Via API, it must be sent in the following property:
{
//...
"device_id": "{{DEVICE_ID}}"
//...
}
{
//...
"anti_fraud_info": {
"session_id": "{{SESSION_ID}}"
}
//...
}
Customer signals
Provide complete user information:
{
//...
"email": "{{USER_EMAIL}}",
"credit_card": {
"expiry_month": "11",
"expiry_year": "29",
"card_number": "4111111111111111",
"card_holder": "Elon Musk",
"card_holder_dni": "1234567891",
"zip": "12345",
"city": "Ibarra",
"address1": "Avenida Mariano Acosta & Obispo Alejandro Pasquel Monge, Ibarra, Ecuador",
"state": "Quito",
"phone": "+59123456789",
"country": "Ecuador",
"card_cvv": "123"
}
//...
}
{
//...
"payer_info": {
"email": "{{USER_EMAIL}}"
},
"credit_info": {
"expiry_month": "11",
"expiry_year": "29",
"card_number": "4111111111111111",
"card_holder": "Elon Musk",
"card_holder_dni": "1234567891",
"zip": "12345",
"city": "Ibarra",
"address1": "Avenida Mariano Acosta & Obispo Alejandro Pasquel Monge, Ibarra, Ecuador",
"state": "Quito",
"phone": "+59123456789",
"country": "Ecuador",
"card_cvv": "123"
}
//...
}
Testing 3DS in sandbox environment
If you want to test 3DS in DEUNA's test mode, then consult your payment service provider's documentation to locate:
- Test cards
- Test amounts needed to activate 3DS
Use the test information with your implementation to test 3DS with DEUNA
Error codes
When performing the authentication process with DEUNA's 3DS MPI, different errors can occur. For particular cases where a payment fails due to a specific 3DS flow error, one of these errors ocurred:
Error code | Rejection reason |
---|---|
DEUNA_3DS.FAILED_CHALLENGE_AUTHENTICATION | Cardholder challenge failed |
DEUNA_3DS.UNAVAILABLE_CHALLENGE_AUTHENTICATION | Cardholder authentication is rejected without a challenge by the issuer |
DEUNA_3DS.UNABLE_ISSUER | Issuer unable to perform authentication |
DEUNA_3DS.ENROLLMENT_CHECK_ERROR | System error prevented authentication when checking enrollment |
DEUNA_3DS.AUTHENTICATION_NOT_AVAILABLE_WHEN_CHECKING_ENROLLMENT | System error prevented authentication when checking enrollment |
DEUNA_3DS.ENROLLMENT_CHECK_TIMEOUT | An error occurred while attempting to check if the cardholder is part of an authentication program |
DEUNA_3DS.UNSUCCESSFUL_FRICTIONLESS_AUTHENTICATION | Authentication without a challenge by the card issuer failed |
DEUNA_3DS.STAND_IN_FRICTIONLESS_AUTHENTICATION_ATTEMPTED | Cardholder is enrolled in 3-D Secure but the card issuer does not support 3-D Secure |
DEUNA_3DS.UNAVAILABLE_FRICTIONLESS_AUTHENTICATION | Authentication is unavailable |
DEUNA_3DS.REJECTED_FRICTIONLESS_AUTHENTICATION | Cardholder authentication is rejected without a challenge by the issuer |
DEUNA_3DS.TIME_EXPIRED | The time for the user to complete the 3DS authentication flow has expired |
Updated 10 days ago