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:

1. Two-step flow:
   1. Create an order
   2. Create a payment associated with that order
2. Single-step flow

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) is pending, because it has not been paid yet.
• The payment status (payment.data.status) is pending_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) or semi-frictionless (the user is presented with the 3DS flow but doesn't need to take an action), the payment.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 the payment.data.authorization_3ds.url_challenge field.

3. Render the 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 field specific_fields.callbacks.
• Forpurchase V2: send the callback_urls in the field callback_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: