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:

• For purchase V1: send the callback_urls in the field specific_fields.callbacks.
• For purchase 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.

📘

Once the challenge is opened, it has a maximum duration of 10min. This time is established by the EMVCo 3DS specification (section 5.5 Timeouts).

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"
      }
    }
  }
}

Stripe Radar Quality Excellent

The integration is designed to meet Stripe's excellence standards (Radar Quality Excellent) in fraud management and prevention. Send the necessary information to achieve the standard quality.

Radar session

The radar session data is sent autmatically 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: