3D-Secure

Redirect 3D-Secure

⚠️

Mandatory

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

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

{
    "amount": 120.00,
    "currency" : "BRL",
    "country": "BR",
    "payment_method_id" : "CARD",
    "payment_method_flow" : "DIRECT",
    "payer":{
        "name" : "Thiago Gabriel",
        "email" : "[email protected]",
        "document" : "53033315550",
        "user_reference": "12345",
        "address": {
            "state"  : "Rio de Janeiro",
            "city" : "Volta Redonda",
            "zip_code" : "27275-595",
            "street" : "Servidao B-1",
            "number" : "1106"
        },
        "ip" : "2001:0db8:0000:0000:0000:ff00:0042:8329",
        "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"
}
{
    "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",
    "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)

⚠️

Availability

Version 2.x is currently supported for Brazil, Mexico, India, Dominican Republic, Guatemala, Kenya, South Africa and Nigeria.

Submit a payment, using authentication data from a third-party 3Ds provider.

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

Example authorization with 3rd-party authentication

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

{
    "amount": 120.00,
    "currency" : "BRL",
    "country": "BR",
    "payment_method_id" : "CARD",
    "payment_method_flow" : "DIRECT",
    "payer":{
        "name" : "Thiago Gabriel",
        "email" : "[email protected]",
        "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"
}
{
    "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": {
        "eci" : "05"
    },
    "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"
}

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.

⚠️

Availability

Optional 3D-Secure is available in Mexico, Turkey, Egypt, Nigeria, Dominican Republic, Indonesia, and Brazil (For credit cards).

Example authorization with optional 3D-Secure

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

{
    "amount": 120.00,
    "currency" : "BRL",
    "country": "BR",
    "payment_method_id" : "CARD",
    "payment_method_flow" : "DIRECT",
    "payer":{
        "name" : "Thiago Gabriel",
        "email" : "[email protected]",
        "document" : "53033315550",
        "user_reference": "12345",
        "address": {
            "state"  : "Rio de Janeiro",
            "city" : "Volta Redonda",
            "zip_code" : "27275-595",
            "street" : "Servidao B-1",
            "number" : "1106"
        },
        "ip" : "2001:0db8:0000:0000:0000:ff00:0042:8329",
        "device_id" : "2fg3d4gf234"
    },
    "card":{
        "holder_name" : "Thiago Gabriel",
        "number" : "4111111111111111",
        "cvv" : "123",
        "expiration_month" : 10,
        "expiration_year" : 2040
    },
    "three_dsecure":{
        "force" : true
    },
    "order_id": "657434343",
    "notification_url": "http://merchant.com/notifications"
}
{
    "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",
    "status": "PENDING",
    "status_detail": "The payment is pending 3D Secure authentication.",
    "status_code": "101",
    "order_id": "657434343",
    "notification_url": "http://merchant.com/notifications"
}

Electronic Commerce Indicator (ECI) Value

brandECIDescription
VI, VD05Authenticated by Issuer - Chargeback risk shifted to Issuer.
VI, VD06Authenticated by Network - Chargeback risk shifted to Issuer.
VI, VDOtherNot authenticated.
MC, MD, MS00Not authenticated.
MC, MD, MS01Attempted but not completed.
MC, MD, MS02Authenticated by Issuer - Chargeback risk shifted to Issuer.
MC, MD, MSOtherNot authenticated.
EL05Authenticated by Issuer - Chargeback risk shifted to Issuer.
EL06Authenticated by Network - Chargeback risk shifted to Issuer.
EL07Not authenticated.