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.
1
<script src="https://js.dlocal.com/"></script>
Copied!

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).
1
var fields = dlocal.fields({
2
locale: 'en',
3
country: 'BR'
4
});
Copied!
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 can safely pass to your server for 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.
1
dlocal.createToken(card,tokenData)
2
.then(function(result) {
3
// Handle result.token
4
}
5
.catch(function(result) {
6
// Handle result.error
7
}););
Copied!
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 nam
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.
1
dlocal.createInstallmentsPlan(card, amount, currency)
2
.then(function(result) {
3
// Handle result.installments
4
}
5
.catch(function(result) {
6
// Handle result.error
7
}););
Copied!
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
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.
1
{
2
"id" : "INS54434",
3
"country" : "BR",
4
"currency" : "BRL",
5
"bin" : "435921",
6
"amount": 1500,
7
"installments" : [
8
{
9
"id" : "INS54434-3",
10
"installment_amount" : 550,
11
"installments" : 3,
12
"total_amount" : 1650
13
},
14
{
15
"id" : "INS54434-6",
16
"installment_amount" : 350,
17
"installments" : 6,
18
"total_amount" : 2100
19
},
20
{
21
"id" : "INS54434-8",
22
"installment_amount" : 250,
23
"installments" : 12,
24
"total_amount" : 3000
25
}
26
]
27
}
Copied!

dlocal.getBinInformation(field)

Use dlocal.getBinInformation(field)to retrieve information from that card number.
Example Response
1
"bin": {
2
"bin": "430307",
3
"brand": "VI",
4
"type": "DEBIT",
5
"category": "CLASSIC",
6
"issuer": "RIAS REDBANC, S.A.",
7
"country": "UY"
8
}
Copied!

The Fields Object

fields.create(type, options)

1
var card = fields.create('card');
Copied!
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.
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>.
    1
    <label>Card
    2
    <div id="card-field"></div>
    3
    </label>
    Copied!
    2.
    Create a <label> with a for attribute, referencing the ID of your container.
    1
    <label for="card-field">Card</label>
    2
    <div id="card-field"></div>
    Copied!
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.
1
cardField.mount('#card-field');
Copied!

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 reported errors:
1
card.addEventListener('change', function(event) {
2
var displayError = document.getElementById('card-errors');
3
if (event.error) {
4
displayError.textContent = event.error.message;
5
} else {
6
displayError.textContent = '';
7
}
8
});
Copied!

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.
1
window.addEventListener('resize', function(event) {
2
if (window.innerWidth <= 320) {
3
card.update({style: {base: {fontSize: '13px'}}});
4
} else {
5
card.update({style: {base: {fontSize: '16px'}}});
6
}
7
});
8
9
var previousBrand;
10
card.on('change', function(event) {
11
if (event.brand !== previousBrand && event.brand === 'mastercard') {
12
card.update({style: {base: {color: 'orange'}}});
13
previousBrand = event.brand;
14
}
15
});
Copied!

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:
1
<style>
2
.my-input {
3
padding: 10px;
4
border: 1px solid #ccc;
5
}
6
</style>
7
8
<form>
9
<div>
10
<label>Name</label>
11
<input class="my-input">
12
</div>
13
<div>
14
<label>Card</label>
15
<!-- Using the same "my-input" class on the -->
16
<!-- regular input above and on this container. -->
17
<div class="my-input" id="card-field"></div>
18
</div>
19
</form>
Copied!
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.
Last modified 1yr ago