Using dLocal Direct

Step 1: Set up dLocal Direct

dLocal Direct is available as part of dLocal.js. To get started, include this script on your pages —it should always be loaded directly from https://js.dlocal.com/direct. For testing purposes, you can use https://js-sandbox.dlocal.com/direct

<script src="https://js.dlocal.com/direct/"></script>

Next, create an instance of dLocal Direct:

var dlocal = dlocal('your_API_key');

To initialize the dLocal helper you will need an API Key. Please contact your Technical Account Manager to obtain one.

Step 2: Create a token to securely transmit card information

The payment details collected using dLocal Direct can then be converted into a token. Create an event handler that handles the submit event on the form. The handler sends the sensitive information to dLocal for tokenization and prevents the form’s submission (the form is submitted by JavaScript in the next step).

// Create a token or display an error when the form is submitted.
var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
  event.preventDefault();
var name = document.getElementById('card-holder').value;
var pan = document.getElementById('pan').value;
var expirationYear = document.getElementById('expiration-year').value;
var expirationMonth = document.getElementById('expiration-month').value;
var cvv = document.getElementById('cvv').value;
var country = 'BR';
  dlocal.createToken( {
    name, pan, expirationYear, expirationMonth, cvv, country
  }).then(function(result) {
      // Send the token to your server.
      dlocalTokenHandler(result.token);
  }).catch((result) => {
    if (result.error) {
      // Inform the customer that there was an error.
      var errorField = document.getElementById('card-errors');
      errorField.textContent = result.error.message;
    }
  });
});

dlocal.createToken returns a Promise which resolves with a result object. This object has result.token the token that was successfully created.

createToken function parameters

In order to use the createToken function you should send the following parameters

Step 3: Submit the token and the rest of your form to your server

The last step is to submit the token, along with any additional information that has been collected, to your server.

function dlocalTokenHandler(token) {
// Insert the token ID into the form so it gets submitted to the server
var form = document.getElementById('payment-form');
var tokenInput = document.createElement('input');
tokenInput.setAttribute('type', 'hidden');
tokenInput.setAttribute('name', 'dlocalToken');
tokenInput.setAttribute('value', token);
form.appendChild(tokenInput);

// Submit the form
form.submit();
}

ℹ️

Note

Tokens created with this method expire after 10 minutes, or after one operation with that token is made (eg: Payment or Save Card). If you want to save the card to make other payments later, you need to save the card. Learn more about saving cards.

Handling errors

Expected errors

Unexpected errors

Unexpected errors may occur during the card tokenization process in Dlocal Direct. These issues are not caused by incorrect usage or invalid input but result from internal problems, downstream service dependencies, or temporary disruptions.

While Dlocal Direct is designed for high availability and reliability, these scenarios, typically reflected in HTTP 5xx and 4xx status codes, require robust handling to ensure resilient integrations.

Common 5xx and 4xx status codes

Recommended handling methods

To ensure stability and fault tolerance, implement the following recommendations:

Initial delay: 1 second
Backoff factor: x2
Maximum attempts: 5

Contacting support

If persistent 5xx or 4xx errors occur, or a specific request consistently fails, contact your designated Technical Account Manager or email us at [email protected] with the following information:

• Transaction ID from the error response
• API endpoint and request parameters
• Timestamp and timezone
• Relevant logs or screenshots

Unexpected errors are rare, but possible in distributed systems. Dlocal Direct actively monitors and responds to these issues to maintain reliable service.