3-D Secure (3DS)

Initialize the script

Include the following script in your web page to load the script responsible for communicating with the card networks and the issuing banks:

<script src="https://static.payzu.io/scripts/3ds20.min.js"></script>

After loading the script on your page, you must initialize it as follows:

const config = {
  amount: 350,
  currency: 'BRL',
  options: {
    enabled: true,
    sandbox: true,
    debug: true,
    suppressChallenge: false
  }
};

payzu3DS.init(config);

Register the authentication events

Register the event listeners to handle each possible authentication result:

payzu3DS.on("ready", function (e) {

});

ready

This event fires when all script loading procedures have completed successfully, including the access token validation. It indicates that the checkout is ready to start the authentication process.

Authentication results

The liability shift happens only when authentication completes successfully: in that case, chargeback liability shifts to the issuer or the card network. In every other scenario, liability stays with the merchant.

unsupportedBrand

This event fires when the card network of the card being used is not compatible with the 3DS protocol. In this case, authentication is not performed.

Returned attributes

Request the challenge

Instantiate the paymentObject, paying attention to the fields that are strictly required in the table below. When the checkout runs, the authentication process starts and its result is returned through the events.

const paymentObject = {
  installments: '01',
  cardnumber: '4000000000001091',
  cardexpirationmonth: '01',
  cardexpirationyear: '2027',
  cardalias: 'JOAO SOUZA',
  paymentmethod: 'Credit'
}

payzu3DS.checkout(paymentObject)

If authentication completes successfully, the success event fires. In that case, the Cavv, Xid and Eci variables are returned: they must be sent to your backend and later included in the request at authorization time. In this case, the liability shift goes to the issuer.

Use the result in the charge

To create a charge using 3DS, you must set the authenticate field to true and provide the externalAuthentication field inside creditCardPayment:

{
  "creditCardPayment": {
    "authenticate": true,
    "externalAuthentication": {
      "cavv": "Ag5zZ2ElCIUbLFj6gS0J9gByv//rRg5qGTqWqf8vTjt5",
      "xid": "198b924ea7db1014b64c8b426a0e6f1e",
      "eci": "05",
      "version": "2.2",
      "referenceId": "abcd1234-efgh-5678-ijkl-9012mnopqrst"
    }
  }
}

See Create charge for the remaining request fields.