dlocal.js Reference

Including dlocal.js

However you’re using dlocal.js, you always begin by including the library and setting your API key. To get started, include this script on your pages—it should always be loaded directly from https://js.dlocal.com. For testing purposes, you can use https://js-sandbox.dlocal.com.

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

The dLocal Object

dlocal.fields([options])

Create pre-built UI components to collect payment information with Smart Fields (simply referred to as fieldsin the API).

var fields = dlocal.fields({
locale: 'en',
country: 'BR'
});

This method creates an instance of fields, which manages a group of Smart Fields. It receives an options object. Available options are documented below:

Option

Type

Description

locale

String

The IETF language tag of the locale to display placeholders and error strings in. Default is Spanish(es). Supported values are: es, en, pt, zh, cv, tr.

country

String

User’s country code. ISO 3166-1 alpha-2 codes.

fonts

Array (Optional)

An array of custom fonts, which Smart Fields created from the fields object can use. Fonts can either be loaded via a CSS file by passing an object with the cssSrc attribute, or they can be loaded directly by passing a Font object.

Parameter

Type

Description

cssSrc

String

A relative or absolute URL pointing to a CSS file with @font-face definitions, for example: "https://fonts.googleapis.com/css?family=Open+Sans"

The Font object

Parameter

Type

Description

family

String

The name to give the font.

src

String

A valid src value pointing to your custom font file. This is usually (though not always) a link to a file with a .woff, .otf, or .svg suffix.

display

String (Optional)

A valid font-display value.

style

String

One of 'normal', 'italic', 'oblique'. Defaults to 'normal'.

unicodeRange

String (Optional)

A valid unicode-range value.

weight

String (Optional)

A valid font-weight . Note that this is a string, not a number.

dlocal.createToken(field, tokenData)

Use dlocal.createToken() to convert information collected by Smart Fields into a token that you safely pass to your server to use in an API call. This token expires 10 minutes after it has been created, or after one operation with the token is made, such as a Payment or Card Save, so you need to make sure that the payment (or other operation) is made within that timeframe.

Using Smart Fields token for Save + Payment If you use Smart Fields to first Save the Card, and then make a Payment, you'll need to tokenize the card using Smart Fields twice. The first time, you'll use the Smart Fields token to Create a Card, and then tokenize again and use the second token to make the Payment.

dlocal.createToken(card,tokenData)
.then(function(result) {
// Handle result.token
}
.catch(function(result) {
// Handle result.error
}););

This method takes two arguments.

  • field, the Smart Field you wish to tokenize data from. If applicable, the Smart Field pulls data from other Smart Fields you’ve created on the same instance of fields to tokenize.

  • tokenData, an object containing additional payment information you might have collected. In the case of cards, it can contain any of the following parameters:

Parameter

Type

Description

name

String (Required)

Cardholder name

address_line1

address_line2

address_city address_state

address_zip address_country

String (Optional)

Fields for billing address information.

The address_country field is a two character country code (for example, 'BR').

currency

String (Optional)

Currency of the transaction

dlocal.createToken returns a Promise which resolves with a result object. This object has either:

  • result.token: a Token was created successfully.

  • result.error: there was an error. This includes client-side validation errors.

dlocal.createInstallmentsPlan(field, amount, currency)

Use dlocal.createInstallmentsPlan(field, amount, currency)to specify an installment plan, to guarantee the surcharge per installment that will be charged.

dlocal.createInstallmentsPlan(card, amount, currency)
.then(function(result) {
// Handle result.installments
}
.catch(function(result) {
// Handle result.error
}););

It is highly recommended that you include the createInstallmentsPlan on the brand event. This is because the installment plan only depends on the amount and card brand.

Installments Arguments
Installments Plan Object
Installment Object
Example Installments Plan Object

Parameter

Type

Description

field

SmartField

The Smart Field you wish to create the installments plan, if you are not using a card Field we recommend to use number Field to create installments, but any of the Fields will work.

amount

Positive Float

The amount of the installments plan.

currency

String

The currency of the installments plan.

Property

Type

Description

id

String

The installments plan id.

country

String

The country of the installments plan (this is the same you specified when you created the field).

currency

String

The currency of the installments plan.

bin

String

The credit card bin.

amount

Positive Float

The amount of the installments plan.

installments

Installment Object[ ]

The installments plan information

Property

Type

Description

id

String

The installment id.

installment_amount

Positive Float

Installment amount.

total_amount

Positive Float

Installments total amount.

installments

Integer

Number of installments.

{
"id" : "INS54434",
"country" : "BR",
"currency" : "BRL",
"bin" : "435921",
"amount": 1500,
"installments" : [
{
"id" : "INS54434-3",
"installment_amount" : 550,
"installments" : 3,
"total_amount" : 1650
},
{
"id" : "INS54434-6",
"installment_amount" : 350,
"installments" : 6,
"total_amount" : 2100
},
{
"id" : "INS54434-8",
"installment_amount" : 250,
"installments" : 12,
"total_amount" : 3000
}
]
}

The Fields Object

fields.create(type, options)

var card = fields.create('card');

This method creates an instance of a specific Smart Field. It takes thetype of Smart Field to create as well as an options object.

Smart Field Types

Type

Description

card

A flexible single-line input that collects cardNumber, cardExpiry and cardCvc.

pan

The card‘s number. Use alongside the expiration and cvv Smart Fields.

expiration

The card‘s expiration date. Use alongside the pan and cvv Smart Fields.

cvv

The card‘s CVC number. Use alongside the pan and expiration Smart Fields.

cvv-only

Use this Smart Field if you are only going to tokenize the CVV. At the moment this feature is not compatible with installments.

Example Checkout with `card` Smart Field
Example Checkout with `pan`, `expiration`, and `cvv` Smart Fields

Field Options

All Smart Fields accept a common set of options, and then some Field-specific options.

Common options:

Option

Type

Description

placeholder

String or Object

Set custom placeholder for Field. For number, expiration or cvv Fields this option is a string with the corresponding placeholder value, if the Field is a card this option is an object with the corresponding placeholder value for each input:

{

cvv: "cvv placeholder",

number: "number placeholder",

expiration: "expiration placeholder"

}

classes

Object (Optional)

Set custom class names on the container DOM element when the dLocal Field is in a particular state.

  • base - The base class applied to the container. Defaults to DlocalField.

  • complete- The class name to apply when the Field is complete. Defaults to DlocalField--complete.

  • empty - The class name to apply when the Field is empty. Defaults to DlocalField--empty.

  • focus - The class name to apply when the Field is focused. Defaults to DlocalField--focus.

  • invalid - The class name to apply when the Field is invalid. Defaults to DlocalField--invalid.

  • webkitAutofill - The class name to apply when the Field has its value autofilled by the browser (only on Chrome and Safari). Defaults to DlocalField--autofilled.

style

Object (Optional)

Customize appearance using CSS properties. Style is specified as an object for any of the variants below.

  • base, base style—all other variants inherit from this style

  • complete, applied when the Field has valid input

  • empty, applied when the Field has no customer input

  • invalid, applied when the Field has invalid input

  • autofilled, applied when the Field is autofilled

For each of the above, the properties below can be customized.

  • color

  • fontFamily

  • fontSize

  • fontSmoothing

  • fontStyle

  • fontVariant

  • iconColor

  • lineHeight, to avoid cursors being rendered inconsistently across browsers, consider using a padding on the Field's container instead.

  • letterSpacing

  • textDecoration

  • textShadow

  • textTransform

The following pseudo-classes and pseudo-elements can also be styled with the above properties, as a nested object inside the variant.

  • :hover

  • :focus

  • ::placeholder

  • ::selection

  • :disabled

Options available exclusively to the card or number Field

Option

Type

Description

iconStyle

String (Optional)

Appearance of the icon in the Field. Either 'solid' or 'default'.

hideIcon

Boolean (Optional)

Hides the icon in the Field. Default is false.

The Field Object

field.mount(domElement)

You need to create a container DOM element to mount a Smart Field. If the container DOM element has a label, the Field is automatically focused when its label is clicked. There are two ways to do this:

  1. Mount the instance within a <label>.

    <label>Card
    <div id="card-field"></div>
    </label>
  2. Create a <label> with a for attribute, referencing the ID of your container.

    <label for="card-field">Card</label>
    <div id="card-field"></div>

The field.mount() method attaches your Field to the DOM. field.mount() accepts either a CSS Selector (e.g., '#card-field') or a DOM element.

cardField.mount('#card-field');

field.on(event, handler)

The only way to communicate with your Smart Field is by listening to an event. Fields might emit any of the events below. All events have a payload object that has an fieldType property with the type of the Field that emitted the event.

Event

Description

blur

Triggered when any of the Fields elements loses focus. The event payload always contains certain keys:

  • empty - Boolean - true if the value is empty.

  • complete - Boolean -true if the value is well-formed and complete:

    • complete can be used to progressively disclose the next parts of your form or to enable form submission.

    • complete is not an indicator of whether a customer is done with their input—it only indicates that the Field contains a complete, well-formed value.

  • error - The current validation error, if any. Comprised of message, code, and type set to validation_error.

  • brand - String - The detected card brand, if any.

  • element - String - The name of the field that triggered the event: 'number', 'expiration', 'cvv'.

  • hasFocus - Boolean - true if any of the Fields elements has focus (always false in pan, expiration and cvv Fields).

  • autofilled - Boolean - true if any of the Fields is autofilled.

focus

Triggered when any of the Fields elements gains focus. The event payload always contains certain keys:

  • empty - Boolean - true if the value is empty.

  • complete - Boolean -true if the value is well-formed and complete:

    • complete can be used to progressively disclose the next parts of your form or to enable form submission.

    • complete is not an indicator of whether a customer is done with their input—it only indicates that the Field contains a complete, well-formed value.

  • error - The current validation error, if any. Comprised of message, code, and type set to validation_error.

  • brand - String - The detected card brand, if any.

  • element - String - The name of the field that triggered the event: 'number', 'expiration', 'cvv'.

  • autofilled - Boolean - true if any of the Fields is autofilled.

error

Triggered when a client-side validation error is detected. The event payload always contains error key which contains the current validation error. Comprised of: message, code and type, set to validation_error.

complete

Triggered when the Field changes its complete status. The event payload always containscomplete - Boolean - key, which is true when the Field is complete and well-formed, and false otherwise.

Important Note: The complete event will only be triggered for cards with BINs identified by Smart Field's BIN detector. Some BINs might not yet be supported by the BIN detector so this event might not be triggered for those. Therefore, you should not expect this event for all cards.

empty

Triggered when the Field changes its empty status. The event payload always contains empty - Boolean - key, which is true when the Field is empty, and false otherwise.

ready

Triggered when the Field is mounted and loaded in the DOM.

change

Triggered when any of the following values changes on the Field. The event payload always contains certain keys, in addition to some Field-specific keys.

  • empty - Boolean - true if the value is empty.

  • complete - Boolean -true if the value is well-formed and complete:

    • complete can be used to progressively disclose the next parts of your form or to enable form submission.

    • complete is not an indicator of whether a customer is done with their input—it only indicates that the Field contains a complete, well-formed value.

  • error - The current validation error, if any. Comprised of message, code, and type set to validation_error.

  • brand - The detected card brand, if any.

  • autofilled - Boolean - true if any of the Fields is autofilled.

brand

Triggered when the Field detects a change in the card brand. This event can only be listened in number and card Smart Fields (it wont work in cvv and expiration Fields). The event payload always contains brand - String - key, which has the name of the detected brand if any, null otherwise.

If using installments, it is highly recommended that you include the createInstallmentsPlan on the brand event. This is because the installment plan only depends on the amount and card brand.

autofilled

Triggered when the Field detects a change in it's autofilled status. The event payload always contains autofilled - Boolean - key, which is true if the field is autofilled.

Input validation

Smart Fields validates customer input as it is typed. To help your customers catch mistakes, listen to changeevents on the Field and display any errors:

card.addEventListener('change', function(event) {
var displayError = document.getElementById('card-errors');
if (event.error) {
displayError.textContent = event.error.message;
} else {
displayError.textContent = '';
}
});

Other Methods

Method

Description

blur()

Blurs the Field

clear()

Clears the value(s) of the Field.

destroy()

Removes the Field from the DOM and destroys it. Note: a destroyed Field cannot be re-activated or re-mounted to the DOM.

focus()

Focuses the Field. In a card Field it will focus in the number field.

unmount()

Unmounts the Field from the DOM. Call field.mount() to re-attach it to the DOM.

update(options)

Updates the options the Field was initialized with. Updates are merged into the existing configuration. Accepts the same options as fields.create().

The styles of a Smart Field can be dynamically changed using update(). This method can be used to simulate CSS media queries that automatically adjust the size of Fields when viewed on different devices.

window.addEventListener('resize', function(event) {
if (window.innerWidth <= 320) {
card.update({style: {base: {fontSize: '13px'}}});
} else {
card.update({style: {base: {fontSize: '16px'}}});
}
});
var previousBrand;
card.on('change', function(event) {
if (event.brand !== previousBrand && event.brand === 'mastercard') {
card.update({style: {base: {color: 'orange'}}});
previousBrand = event.brand;
}
});

The Field container

Style the container you mount a Smart Field to, as if it were an <input> on your page. For example, to control padding and border on a Field, set these properties on the container. This is usually done by re-using the classes that you have applied to your DOM <input> elements. Example:

<style>
.my-input {
padding: 10px;
border: 1px solid #ccc;
}
</style>
<form>
<div>
<label>Name</label>
<input class="my-input">
</div>
<div>
<label>Card</label>
<!-- Using the same "my-input" class on the -->
<!-- regular input above and on this container. -->
<div class="my-input" id="card-field"></div>
</div>
</form>

After the Field is mounted, the .DlocalField class is added to the container. Additionally, the following classes are automatically added to the container when the Field is complete, empty, focused, invalid, or autofilled by the browser:

  • .DlocalField--complete

  • .DlocalField--empty

  • .DlocalField--focus

  • .DlocalField--invalid

  • .DlocalField--autofilled (Chrome and Safari only)

These class names can be customized using the classes option when you create a Smart Field.

Supported browsers

dLocal.js strives to support all recent versions of major browsers. For the sake of security and providing the best experience to the majority of customers, we do not support browsers that are no longer receiving security updates and represent a small minority of traffic.

  • We support Chrome and Safari on all platforms and Firefox on desktop platforms.

  • We support Internet Explorer and Edge per Microsoft's lifecycle policy. As of January 12, 2016, we support Internet Explorer 9 and above.

  • We support the Android native browser on Android 4.4 and later.

  • We require TLS 1.2 to be supported by the browser.

If you have an issue with dLocal.js on a specific browser, please contact us so we can improve its support.