3D-Secure

OUR SOLUTION COUNTRIES CUSTOMERS CONTACT US
Search…
3D-Secure
Redirect 3D-Secure
Redirect 3D-Secure is mandatory in India, South Africa, the Philippines, Malaysia, and debit cards in Brazil.
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
1
curl -X POST \
2
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
    -H 'X-Login: sak223k2wdksdl2' \
4
    -H 'X-Trans-Key: fm12O7G9' \
5
    -H 'Content-Type: application/json' \
6
    -H 'X-Version: 2.1' \
7
    -H 'User-Agent: MerchantTest / 1.0 ' \
8
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
9
    -d '{body}'
10
    https://api.dlocal.com/secure_payments
Copied!
Example Request Body
1
{
2
    "amount": 120.00,
3
    "currency" : "BRL",
4
    "country": "BR",
5
    "payment_method_id" : "VD",
6
    "payment_method_flow" : "DIRECT",
7
    "payer":{
8
        "name" : "Thiago Gabriel",
9
        "email" : "[email protected]",
10
        "document" : "53033315550",
11
        "user_reference": "12345",
12
        "address": {
13
            "state"  : "Rio de Janeiro",
14
            "city" : "Volta Redonda",
15
            "zip_code" : "27275-595",
16
            "street" : "Servidao B-1",
17
            "number" : "1106"
18
        },
19
        "ip" : "179.27.83.210",
20
        "device_id" : "2fg3d4gf234"
21
    },
22
    "card":{
23
        "holder_name" : "Thiago Gabriel",
24
        "number" : "4111111111111111",
25
        "cvv" : "123",
26
        "expiration_month" : 10,
27
        "expiration_year" : 2040,
28
        "capture" : false
29
    },
30
    "order_id": "657434343",
31
    "notification_url": "http://merchant.com/notifications",
32
    "callback_url": "http://merchant.com/callback"
33
}
Copied!
1
​
2
    "id": "D-4-cf8eef6b-52d5-4320-b5ea-f5e0bbe4343f",
3
    "amount": 120,
4
    "currency": "BRL",
5
    "payment_method_id": "CARD",
6
    "payment_method_type": "CARD",
7
    "payment_method_flow": "DIRECT",
8
    "country": "BR",
9
    "card": {
10
        "holder_name": "Thiago Gabriel",
11
        "expiration_month": 10,
12
        "expiration_year": 2040,
13
        "brand": "VI",
14
        "last4": "1111"
15
    },
16
    "three_dsecure" : {
17
        "redirect_url" : "http://api.dlocal.com/three-ds/M-64356345634587b3495"
18
    },
19
    "created_date": "2018-12-26T20:26:09.000+0000",
20
    "status": "PENDING",
21
    "status_detail": "The payment is pending 3D Secure authentication.",
22
    "status_code": "101",
23
    "order_id": "657434343",
24
    "notification_url": "http://merchant.com/notifications"
25
}
Copied!
3rd-party Authentication (MPI)
3rd-party Authentication is only available in Brazil, Panama, Costa Rica, and Guatemala at the moment, for version 1.0.
Version 2.x is currently only supported for Brazil.
Submit a payment, using authentication data from a third-party 3D Secure 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
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
Options: 1.0, 2.0, 2.1.0, 2.2.0 . 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
eci
String
The electronic commerce indicator.
Required if mpi = TRUE 
*See possible values and descriptions here​
xid
String
The transaction identifier assigned by the Directory Server for v1 authentication (base64 encoded, 20 bytes in a decoded form).
Required if mpi = TRUE andthree_dsecure_version = "1.0"
ds_transaction_id
String
The transaction identifier assigned by the 3DS Server for v2 authentication (36 characters, commonly in UUID format).
Required if mpi = TRUE andthree_dsecure_version = 2.x
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
1
"three_dsecure":{
2
    "mpi": true,
3
    "three_dsecure_version": "1.0",
4
    "cavv": "3q2+78r+ur7erb7vyv66vv\/\/\/\/8=",
5
    "eci": "05",
6
    "xid": "ODUzNTYzOTcwODU5NzY3Qw==",
7
    "enrollment_response": "Y"
8
    "authentication_response": "Y"
9
}
Copied!
Example Authorization with 3rd-party Authentication
Example Request
Example Response
Example Request
1
curl -X POST \
2
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
    -H 'X-Login: sak223k2wdksdl2' \
4
    -H 'X-Trans-Key: fm12O7G9' \
5
    -H 'Content-Type: application/json' \
6
    -H 'X-Version: 2.1' \
7
    -H 'User-Agent: MerchantTest / 1.0 ' \
8
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
9
    -d '{body}'
10
    https://api.dlocal.com/secure_payments
Copied!
Example Request Body
1
{
2
    "amount": 120.00,
3
    "currency" : "BRL",
4
    "country": "BR",
5
    "payment_method_id" : "VD",
6
    "payment_method_flow" : "DIRECT",
7
    "payer":{
8
        "name" : "Thiago Gabriel",
9
        "email" : "[email protected]",
10
        "document" : "53033315550",
11
        "user_reference": "12345",
12
        "address": {
13
            "state"  : "Rio de Janeiro",
14
            "city" : "Volta Redonda",
15
            "zip_code" : "27275-595",
16
            "street" : "Servidao B-1",
17
            "number" : "1106"
18
        },
19
        "ip" : "179.27.83.210",
20
        "device_id" : "2fg3d4gf234"
21
    },
22
    "card":{
23
        "holder_name" : "Thiago Gabriel",
24
        "number" : "4111111111111111",
25
        "cvv" : "123",
26
        "expiration_month" : 10,
27
        "expiration_year" : 2040,
28
        "capture" : false
29
    },
30
    "three_dsecure":{
31
        "mpi" : true,
32
        "three_dsecure_version" : "1.0",
33
        "cavv" : "3q2+78r+ur7erb7vyv66vv\/\/\/\/8=",
34
        "eci" : "05",
35
        "xid" : "ODUzNTYzOTcwODU5NzY3Qw==",
36
        "enrollment_response" : "Y",
37
        "authentication_response" : "Y"
38
    },
39
    "order_id": "657434343",
40
    "notification_url": "http://merchant.com/notifications"
41
}
Copied!
1
{
2
    "id": "D-4-cf8eef6b-52d5-4320-b5ea-f5e0bbe4343f",
3
    "amount": 120,
4
    "currency": "BRL",
5
    "payment_method_id": "CARD",
6
    "payment_method_type": "CARD",
7
    "payment_method_flow": "DIRECT",
8
    "country": "BR",
9
    "card": {
10
        "holder_name": "Thiago Gabriel",
11
        "expiration_month": 10,
12
        "expiration_year": 2040,
13
        "brand": "VI",
14
        "last4": "1111"
15
    },
16
    "three_dsecure": {
17
        "eci" : "05"
18
    },
19
    "created_date": "2018-12-26T20:26:09.000+0000",
20
    "approved_date": "2018-12-26T20:26:09.000+0000",
21
    "status": "AUTHORIZED",
22
    "status_detail": "The payment was authorized",
23
    "status_code": "600",
24
    "order_id": "657434343",
25
    "notification_url": "http://merchant.com/notifications"
26
}
Copied!
Test an Authorization with 3rd-party Authentication
Simulate a payment to check the approved or rejected status using the dLocal Sandbox environment.
For using the Sandbox environment, the endpoint should start with https://sandbox.dlocal.com/​
It is mandatory to send the param mpi as true.
​
Use the following data according to the card you want to try and the result you want to get:
Card
Approved Status
Rejected Satus
VISA or American Express 
Set param eci as 05.
Set param eci as 07.
MasterCard
Set param eci as 02.
Set param eci as 04.
Optional 3D-Secure
Submit a payment and choose whether you want to force the user to go through a 3D-Secure authentication.
To force a 3D-Secure authenticated payment, you need to create a payment with the parameter force = TRUE within the three_dsecure object.
Optional 3D-Secure  is available in Mexico, Turkey, Egypt, Nigeria, Dominican Republic, Indonesia, and Brazil (For credit cards).
Example Authorization with Optional 3D-Secure 
Example Request
Example Response
Example Request
1
    curl -X POST \
2
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
    -H 'X-Login: sak223k2wdksdl2' \
4
    -H 'X-Trans-Key: fm12O7G9' \
5
    -H 'Content-Type: application/json' \
6
    -H 'X-Version: 2.1' \
7
    -H 'User-Agent: MerchantTest / 1.0 ' \
8
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
9
    -d '{body}'
10
    https://api.dlocal.com/secure_payments
Copied!
Example Request body
1
{
2
    "amount": 120.00,
3
    "currency" : "BRL",
4
    "country": "BR",
5
    "payment_method_id" : "VD",
6
    "payment_method_flow" : "DIRECT",
7
    "payer":{
8
        "name" : "Thiago Gabriel",
9
        "email" : "[email protected]",
10
        "document" : "53033315550",
11
        "user_reference": "12345",
12
        "address": {
13
            "state"  : "Rio de Janeiro",
14
            "city" : "Volta Redonda",
15
            "zip_code" : "27275-595",
16
            "street" : "Servidao B-1",
17
            "number" : "1106"
18
        },
19
        "ip" : "179.27.83.210",
20
        "device_id" : "2fg3d4gf234"
21
    },
22
    "card":{
23
        "holder_name" : "Thiago Gabriel",
24
        "number" : "4111111111111111",
25
        "cvv" : "123",
26
        "expiration_month" : 10,
27
        "expiration_year" : 2040,
28
    },
29
    "three_dsecure":{
30
        "force" : true,
31
    },
32
    "order_id": "657434343",
33
    "notification_url": "http://merchant.com/notifications"
34
}
Copied!
1
{
2
    "id": "D-4-cf8eef6b-52d5-4320-b5ea-f5e0bbe4343f",
3
    "amount": 120,
4
    "currency": "BRL",
5
    "payment_method_id": "CARD",
6
    "payment_method_type": "CARD",
7
    "payment_method_flow": "DIRECT",
8
    "country": "BR",
9
    "card": {
10
        "holder_name": "Thiago Gabriel",
11
        "expiration_month": 10,
12
        "expiration_year": 2040,
13
        "brand": "VI",
14
        "last4": "1111"
15
    },
16
    "three_dsecure" : {
17
        "redirect_url" : "http://api.dlocal.com/three-ds/M-64356345634587b3495"
18
    },
19
    "created_date": "2018-12-26T20:26:09.000+0000",
20
    "status": "PENDING",
21
    "status_detail": "The payment is pending 3D Secure authentication.",
22
    "status_code": "101",
23
    "order_id": "657434343",
24
    "notification_url": "http://merchant.com/notifications"
25
}
Copied!
​
Electronic Commerce Indicator (ECI) Values
brand
ECI
Description
VI, VD
05
Authenticated by Issuer - Chargeback risk shifted to Issuer
VI, VD
06
Authenticated by Network - Chargeback risk shifted to Issuer
VI, VD
Other
Not authenticated
MC, MD, MS
00
Not authenticated
MC, MD, MS
01
Authenticated by Network - Chargeback risk shifted to Issuer
MC, MD, MS
02
Authenticated by Issuer - Chargeback risk shifted to Issuer
MC, MD, MS
Other
Not authenticated
EL
05
Authenticated by Issuer - Chargeback risk shifted to Issuer
EL
06
Authenticated by Network - Chargeback risk shifted to Issuer
EL
07
Not authenticated
Chargebacks
Saving Cards
Last modified 18d ago
Copy link
Contents
Redirect 3D-Secure
Example Authorization with Redirect
3rd-party Authentication (MPI)
three_dsecure Object
Example Authorization with 3rd-party Authentication
Test an Authorization with 3rd-party Authentication
Optional 3D-Secure
Example Authorization with Optional 3D-Secure
Electronic Commerce Indicator (ECI) Values