Skip to content

3D-Secure

Use 3D-Secure In Credit Card Payment

To use 3D-Secure, you probably need to integrate the vendor based 3D-Secure JavaScript library first. Then you should specify "use3ds = true" in the card3dsInfo object of the payment request, and provide required parameters based on the vendor you are requesting.

After receiving the 3D-Secure request, an IN_PROGRESS payment response with authentication information will be returned. You should proceed with the 3D-Secure flow according to this information. Once the payer completes the authentication, the payment will be SETTLED.

In Brazil, 3D-Secure availability are listed below:

Vendor Supported Version Document JS Library
Tuna - - -
Adiq 2.0 Click to read adiq-3ds-package-1.0.1-hml-min.js
adiq-3ds-package-1.0.1-min.js

Integrate 3D-Secure From Adiq

1) To initiate the 3D-Secure flow for a new card payment, you must start by integrating the Adiq JavaScript library into the browser webpage.

2) The browser must accept a card number into a text field. The element ID and a callback function must be passed to the Adiq library constructor in order for Adiq to retrieve the card number and register the callback function.

3) The browser must then call Authorization3ds() for Adiq to complete the setup and generate a code3ds, which can be retrieved by then calling getThreeDsCode().

4) Using the code3ds, a Pay-In card request can be made. Example request and response are:

Create A Payment With 3D-Secure

POST /v1/payments/charges/card

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "paymentMethod": "CREDIT_CARD",
    ...  # other basic request fields
    "card3dsInfo": {
        "use3ds": true,
        "code3ds": "a88e307cc7c0415494a1e306b4471d46",  // Provided by Adiq JS library
        "merchantSite3ds": "estabelecimento.com.br"     // Merchant website domain
    },
    "subMerchantId": "UUID",
    ...  # other basic request fields
}
Response
{
    "transferStatusCode": 200,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "CREDIT_CARD",
    "amount": 1000,
    "currency": "BRL",
    "finalAmount": 1000,
    "finalCurrency": "BRL",
    "country": "BR",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    ...  # other basic response fields
    "transferDetails": {
        "card": {
            "cardInfo": {
                "cardHolderName": "card_holder_name",
                "expirationMonth": 9,
                "expirationYear": 2024,
                "brand": "VISA",
                "bin": "458124",
                "last4": "0000"
            },
            "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237",
            "card3dsInfo": {
                "use3ds": true,
                "code3ds": "a88e307cc7c0415494a1e306b4471d46",
                "merchantSite3ds": "estabelecimento.com.br",
                "vendor3dsChallengeInfo": {
                    "adiq3dsChallengeInfo": {
                        "acsUrl": "https://emv3dsauth1.secureacs.com/acs2web/acs2nubankbr/authentication",
                        "pareq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6",
                        "authenticationTransactionId": "mBNpR2zF2dkdFICP6NU1"
                    }
                }
            }
        }
    },
    "transferStatus": "IN_PROGRESS",
    "description": "this is a test pay",
    "subMerchantId": "UUID"
}

5) As seen in the example response above, if a 3D-Secure challenge is required for authentication, the vendorDsChallengeInfo field will be populated with the required information.

6) Using the acsUrl, pareq, and authenticationTransactionId from the vendorDsChallengeInfo field in the response, the browser must now call InitChallenge(acsUrl, pareq, authenticationTransactionId), which will invoke a popup to appear containing the issuer bank's authentication page.

7) Once the payer has completed the authentication, the popup will disappear, and the callback function registered in Step 2 will receive a payments.validated event containing a JWT (validation token) and the ChallengeStatus.

8) The validation token from Step 7 and the code3ds must be sent in the endpoint /card/confirm/{idempotencyKey}, and the payment will be settled. Example request and response are:

Confirm The Authentication

POST /v1/payments/charges/card/confirm/{idempotencyKey}

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "adiqValidationInfo": {
        "code3ds": "a88e307cc7c0415494a1e306b4471d46",
        "validateToken": "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1ZjM2Y2"
    }
}
Response
{
    "transferStatusCode": 200,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "CREDIT_CARD",
    "amount": 1000,
    "currency": "BRL",
    "finalAmount": 1000,
    "finalCurrency": "BRL",
    "country": "BR",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    ...  # other basic response fields
    "transferDetails": {
        "card": {
            "cardInfo": {
                "cardHolderName": "card_holder_name",
                "expirationMonth": 9,
                "expirationYear": 2024,
                "brand": "VISA",
                "bin": "458124",
                "last4": "0000"
            },
            "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237",
            "card3dsInfo": {
                "use3ds": true,
                "code3ds": "a88e307cc7c0415494a1e306b4471d46",
                "merchantSite3ds": "estabelecimento.com.br",
                "vendor3dsChallengeInfo": {
                    "adiq3dsChallengeInfo": {
                        "acsUrl": "https://emv3dsauth1.secureacs.com/acs2web/acs2nubankbr/authentication",
                        "pareq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6",
                        "authenticationTransactionId": "mBNpR2zF2dkdFICP6NU1"
                    }
                }
            }
        }
    },
    "transferStatus": "SETTLED",
    "description": "this is a test pay",
    "subMerchantId": "UUID"
}
Back to top