3D-Secure

Redirect 3D-Secure

In some regions 3D-Secure authentication might be mandatory. In such a scenario, the Create a Payment function will return a payment with status =PENDING (status_code = 101 ). The Payment Object in the response will include a 3D-Secure object (three_dsecure), containing the redirect_url that the user needs to be redirected to so as to complete the authorization.

Once the user completed the authentication successfully, the payment will be processed and the user will be redirected to the callback_url .

Example Authorization with Redirect

Example Request
Example Response
Example Request

Example Request

curl -X POST \
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
-H 'X-Login: sak223k2wdksdl2' \
-H 'X-Trans-Key: fm12O7G9' \
-H 'Content-Type: application/json' \
-H 'X-Version: 2.1' \
-H 'User-Agent: MerchantTest / 1.0 ' \
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
-d '{body}'
https://api.dlocal.com/secure_payments

Example Request Body

{
"amount": 120.00,
"currency" : "BRL",
"country": "BR",
"payment_method_id" : "CARD",
"payment_method_flow" : "DIRECT",
"payer":{
"name" : "Thiago Gabriel",
"email" : "thiago@example.com",
"document" : "53033315550",
"user_reference": "12345",
"address": {
"state" : "Rio de Janeiro",
"city" : "Volta Redonda",
"zip_code" : "27275-595",
"street" : "Servidao B-1",
"number" : "1106"
},
"ip" : "179.27.83.210",
"device_id" : "2fg3d4gf234"
},
"card":{
"holder_name" : "Thiago Gabriel",
"number" : "4111111111111111",
"cvv" : "123",
"expiration_month" : 10,
"expiration_year" : 2040,
"capture" : FALSE
},
"order_id": "657434343",
"notification_url": "http://merchant.com/notifications",
"callback_url": "http://merchant.com/callback"
}
Example Response
"id": "D-4-cf8eef6b-52d5-4320-b5ea-f5e0bbe4343f",
"amount": 120,
"currency": "BRL",
"payment_method_id": "CARD",
"payment_method_type": "CARD",
"payment_method_flow": "DIRECT",
"country": "BR",
"card": {
"holder_name": "Thiago Gabriel",
"expiration_month": 10,
"expiration_year": 2040,
"brand": "VI",
"last4": "1111"
},
"three_dsecure" : {
"redirect_url" : "http://api.dlocal.com/three-ds/M-64356345634587b3495"
},
"created_date": "2018-12-26T20:26:09.000+0000",
"approved_date": "2018-12-26T20:26:09.000+0000",
"status": "PENDING",
"status_detail": "The payment is pending 3D Secure authentication.",
"status_code": "101",
"order_id": "657434343",
"notification_url": "http://merchant.com/notifications"
}

3rd-party Authentication (MPI)

3rd-party Authentication is only available in Brazil at the moment.

Submit a payment, using authentication data from a third-party 3D Secure 1.0 provider.

To authorize a 3D-Secure authenticated payment, you need to include the three_dsecure object in your payment request.

three_dsecure Object

three_dsecure Object
Example three_dsecure Object
three_dsecure Object

Property

Type

Description

mpi

Boolean

TRUE if you are going to use a 3rd-party 3D Secure provider.

If null, then mpi = FALSE

three_dsecure_version

String

Note: At the moment only 3DS 1.0 is supported.

If null, then three_dsecure_version = "1.0"

cavv

String

The cardholder authentication value for the 3D Secure authentication session. The returned value is a base64-encoded 20-byte array.

Required if mpi = TRUE andthree_dsecure_version = "1.0"

eci

String

The electronic commerce indicator.

Required if mpi = TRUE andthree_dsecure_version = "1.0"

xid

String

The transaction identifier assigned by the Directory Server (base64 encoded, 20 bytes in a decoded form).

Required if mpi = TRUE andthree_dsecure_version = "1.0"

enrollment_response

String

The enrollment response from the VERes message from the Directory Server.

"Y": Authentication available "N" Cardholder not participating "U": Unable to authenticate/Card not eligible

Optional

authentication_response

String

From the PARes from the issuer's Access Control System.

"Y": Authentication successful

"A": Attempts processing performed

"N": Authentication failed "U": Authentication could not be performed

Optional

Example three_dsecure Object
"three_dsecure":{
"mpi": TRUE,
"three_dsecure_version": "1.0",
"cavv": "3q2+78r+ur7erb7vyv66vv\/\/\/\/8=",
"eci": "05",
"xid": "ODUzNTYzOTcwODU5NzY3Qw==",
"enrollment_response": "Y"
"authentication_response": "Y"
}

Example Authorization with 3rd-party Authentication

Example Request
Example Response
Example Request

Example Request

curl -X POST \
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
-H 'X-Login: sak223k2wdksdl2' \
-H 'X-Trans-Key: fm12O7G9' \
-H 'Content-Type: application/json' \
-H 'X-Version: 2.1' \
-H 'User-Agent: MerchantTest / 1.0 ' \
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
-d '{body}'
https://api.dlocal.com/secure_payments

Example Request Body

{
"amount": 120.00,
"currency" : "BRL",
"country": "BR",
"payment_method_id" : "CARD",
"payment_method_flow" : "DIRECT",
"payer":{
"name" : "Thiago Gabriel",
"email" : "thiago@example.com",
"document" : "53033315550",
"user_reference": "12345",
"address": {
"state" : "Rio de Janeiro",
"city" : "Volta Redonda",
"zip_code" : "27275-595",
"street" : "Servidao B-1",
"number" : "1106"
},
"ip" : "179.27.83.210",
"device_id" : "2fg3d4gf234"
},
"card":{
"holder_name" : "Thiago Gabriel",
"number" : "4111111111111111",
"cvv" : "123",
"expiration_month" : 10,
"expiration_year" : 2040,
"capture" : FALSE
},
"three_dsecure":{
"mpi" : TRUE,
"three_dsecure_version" : "1.0",
"cavv" : "3q2+78r+ur7erb7vyv66vv\/\/\/\/8=",
"eci" : "05",
"xid" : "ODUzNTYzOTcwODU5NzY3Qw==",
"enrollment_response" : "Y",
"authentication_response" : "Y"
}
"order_id": "657434343",
"notification_url": "http://merchant.com/notifications"
}
Example Response
{
"id": "D-4-cf8eef6b-52d5-4320-b5ea-f5e0bbe4343f",
"amount": 120,
"currency": "BRL",
"payment_method_id": "CARD",
"payment_method_type": "CARD",
"payment_method_flow": "DIRECT",
"country": "BR",
"card": {
"holder_name": "Thiago Gabriel",
"expiration_month": 10,
"expiration_year": 2040,
"brand": "VI",
"last4": "1111"
},
"created_date": "2018-12-26T20:26:09.000+0000",
"approved_date": "2018-12-26T20:26:09.000+0000",
"status": "AUTHORIZED",
"status_detail": "The payment was authorized",
"status_code": "600",
"order_id": "657434343",
"notification_url": "http://merchant.com/notifications"
}