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 will be able to see the following fields that are necessary to know that said charge requires the end user to authenticate:

The important fields to consider are:

• The order status (order.status) will be pending since it has not been paid yet.
• The payment status (payment.data.status) will be 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. In case the merchant has an integration with DEUNA via API (Direct API), the merchant is responsible for redirecting the user to that page or in case of mobile opening that page in a webView. In case the integration is via API (Direct API) and redirection management is not desired, the [InitNextAction](https://docs.deuna.com/reference/next-action-web) widget can be used which handles the flow smoothly.

📘

Depending on the payment provider and/or 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 the .initNextAction() widget and the payment provider or MPI supports the use of iFrame, ask DEUNA to configure the InitNextAction Widget to render as iFrame instead of requiring redirection.

• In case the merchant is integrated with any of DEUNA's widgets, the widgets will be responsible for redirection or iFrame rendering and interpreting when the 3DS flow is required.
• For frictionless type cases (the issuing bank authenticates the user without any type of action or redirection), processed or denied statuses will be obtained in the payment (payment.data.status) without having previously received pending_3ds. This is because in frictionless type transactions, the bank based on the data provided during the purchase request was able to determine that the user is authentic and thus does not request an additional verification step for the operation, continuing with the normal flow.

Example Response

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

3. Render the url_challenge

Render the url_challenge from the acquirer`s page.

4. Redirect the user

Once authentication is finished, DEUNA offers that the merchant be redirected to callback_urls established by the merchant or to a default page.

📘

In case you decide to use callback_urls, please contact your implementation manager to activate this functionality.

• Use of callback_urls: the merchant can configure callbacks in:
  • For purchase V1: send the callback_urls in the following field:
    • specific_fields.callbacks
  • For purchase V2: send the callback_urls in the following field:
    • callback_urls
  • If using one of the widgets: in this case as the merchant is only responsible for creating the order, the callback_urls can be passed in the following field:
    • Contact DEUNA so we can indicate which field to use.
• Use of DEUNA's default page: in case the merchant doesn't use callback_urls after authentication, the buyer will be redirected to the following default web page.

📝

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 for the merchant to know the final payment status after 3DS authentication.

1. Perform long polling of the Get Order API
2. Listen to DEUNA webhooks

DEUNA recommends implementing both processes, since in case the merchant's server has intermittency and cannot listen to webhooks, with long polling it can recover after the intermittency.

Integration data

Frictionless 3D-Secure

In these cases the User (Cardholder) will not be 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, thus making users feel safer when making purchases at the Merchant.

To execute a successful Frictionless 3D-Secure purchase, certain information about the User must be collected such as, full BillingAddress (postal code, line 1, line 2, city, state/province, phone, email, etc), device fingerprint, IP address, browser details and 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, but to achieve such excellence, the necessary information needs to be sent, which is:

Radar session

In our Widgets (Checkout, Payment, Vault, etc) they are sent automatically.

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, 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 will be obtained: