Deposits with 3DS Authentication

Learn how to create Deposits with 3DS Authentication!

We may require a 3DS Authentication to deposits performed with Cards. Here you will find information about how to handle the payment flow and user experience towards the end-users.

We offer different ways of approaching payment flows, depending on the integration:

• For PCI Integrations:

  • Redirect flow. Merchants can opt to display the authentication_url with our 3DS validations. This flow will remain the deposit in PENDING status while the user is being authenticated. Right after that the transaction will be processed.

  • Third-party 3DS. Merchants can opt to send the three_domain_secure[] object with their third-party 3DS authentication results and having the transaction processed synchronously.

• For non-PCI integrations, we take care of the 3DS authentication in the Credit Card checkout.

Redirect flow

The Deposits that are subject to the 3DS Authentication flow, will receive as Response of the PCI Deposit Endpoint a payment_info.result with value PENDING_AUTHENTICATION.

Deposits that are not subject to 3DS Authentication are synchronically approved or rejected with payment_info.result with values SUCCESS and REJECTED.

Example response

{ 
  "deposit_id": 300854027,
  "merchant_invoice_id": "postmanTest488131304", 
  "payment_info": { 
    "type": "CREDIT_CARD", 
    "result": "PENDING_AUTHENTICATION", 
    "reason": "Require 3DS Authentication", 
    "reason_code": "PENDING_AUTHENTICATION", 
    "payment_method": "VI", 
    "payment_method_name": "Visa", 
    "created_at": "2023-10-19 16:57:55", 
    "authentication_url": "https://checkout.cc-stg.directa24.net/authentication/MM15BgQjHVjGEpQLCYZQ1dBoMOcJuDAc" 
  } 
}

authentication_url

This parameter contains a URL with the 3DS Authentication challenge to be displayed to the end-user. In order to do so, you can:

Open the authentication_url within an iframe

The challenge can be displayed within an iframe in the case you want to keep the user on the same webpage.

The iframe can be opened with a JavaScript method EventListener that will communicate whenever the iframe can be closed and the result of the transaction.

JavaScript Method

window.addEventListener('message', handler);

Additionally the EventListener will include whether the transaction was successful or error within the payment_result object.

Success

{
  "payment_result": "success"
}

Error

{
  "payment_result": "error"
}

Redirect the user into a new tab

The authentication_url can also be opened in a new tab to the end-user. In case of opting for this flow, please make sure of including the following parameters in the Deposit request:

Parameter	Format	Description
back_url	URL	URL to redirect the user in case of willing to withdraw from the payment flow.
success_url	URL	URL to redirect the user after the Deposit flow came to an end.
error_url	URL	URL to redirect the user in case that an error occur.

Notification

After the authentication and payment processing, a webhook notification will be sent in order to check the Deposit Status Endpoint and retrieve the status of the transaction. Please check the hyperlinks of this Documentation specific pages for more details.

Third-party 3DS

Please check regional availability with your account manager as not all countries may scope this functionality 🌎

It is possible to create a deposit submitting information from a third-party 3DS provider!

In order to do so, you need to include the three_domain_secure[] Object in the PCI Deposit Creation request.

three_domain_secure[] Object

"three_domain_secure":{
      "cavv": "3q4+33t+ur5erb7vyv53vv\/\/\/\/9=",
      "eci": "05",
      "transaction_id": "HMUzFWRzOTcwOKG7PzY3Rw==",
      "specification_version": "2.0.0"
      }

Field	Format	Description
cavv	String	The cardholder authentication value for the 3D Secure authentication session. The returned value is a base64-encoded 20-byte array.
eci	String	The electronic commerce indicator.
transaction_id	String	The transaction identifier assigned by the 3DS Server for v2 authentication (36 characters, commonly in UUID format).
specification_version	String	The 3DS Authentication version. Accepted from 2.0.0 onwards.

Allowed ECI codes for Third Party 3DS flow, are:

• 01 and 02 for Mastercard

• 05 and 06 for Visa and Amex.

Example PCI Deposit Creation request with third-party 3DS

{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11111",
        "document": "84932568207",
        "document_type": "CPF",
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Smith",
        "phone": "[phone]",
        "birth_date": "19880910",
        "address": {
            "street": "Calle 13",
            "city": "bahia",
            "state": "SP",
            "zip_code": "12345-678"
        }
    },
    "credit_card": {
        "cvv": "123",
        "card_number": "4111111111111111",
        "expiration_month": "10",
        "expiration_year": "25",
        "holder_name": "JOHN SMITH"
    },
    "three_domain_secure":{
      "cavv": "AJkBARglcgAAAAPohABHdQAAAAA=",
      "eci": "05",
      "transaction_id": "7e76d057-100a-4d0d-9683-5eb0ce0ee3a4",
      "specification_version": "2.0.0"
      },
    "description": "Test transaction",
    "client_ip": "123.123.123.123",
    "device_id": "knakvuejffkiebyab",
    "fee_on_payer": false
}