dLocal.js issuing reference
Check the dLocal.js issuing 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.createPinToken(field)

Use dlocalInstance.createPinToken() 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 the operation is made.
dlocalInstance.createPinToken(field)
.then(function(result) {
// Handle result.token
})
.catch(function(result) {
// Handle result.error
});
This method takes one argument.
  • 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 (i.e: change pin operation).
dlocalInstance.createPinToken returns a Promise which resolves with a result object. This object has either:
Result
Description
result.token
Token was created successfully
result.error
There was an error. This includes client-side validation errors.

The Fields object

fields.create(type, options)

var card = fields.create('pin');
This method creates an instance of a specific Smart Field. It takes thetype of Smart Field to create as well as an options object.

field.mount(domElement)

You need to create a container DOM element to mount a Smart Field.
<div id="virtual-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('#virtual-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 a fieldType property with the type of the Field that emitted the event.
Event
Description
ready
Triggered when the Field is mounted and loaded in the DOM.
external-error
Triggered when an error occurs getting data from the server (e.g: virtual card data).

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.

Smart Field Types

Virtual Card

Type
Description
read-only-pan
The card’s PAN.
read-only-expiration
The card’s expiration date.
read-only-cvv
The card’s CVV2.

PIN

Type
Description
pin
Allows cardholders to set their PIN code.
new-pin
Allows cardholders to set their new PIN code (change PIN method).
old-pin
Allows cardholders to enter their current PIN code (change PIN method).

Field options

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

Common options

Option
Type
Description
classes
Object
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.
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
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
panStyle
Object (Optional)
Customize the PAN style: - separatedEach: to set card number intervals. - spaceBetween : quantity of spaces (in pixels) between intervals. Eg. if you need to expose the card PAN like '1111 2222 3333 4444' * separatedEach: 4 * spaceBetween : 1
maskInput
Boolean (Optional)
Mask the value like an input type password.
hideIcon
Bolean (Optional)
Hide the card scheme icon.

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.
Copy link
On this page
Including dLocal.js
The dLocal object
dlocal.fields([options])
dlocal.createPinToken(field)
The Fields object
fields.create(type, options)
field.mount(domElement)
field.on(event, handler)
The Field container
Smart Field Types
Virtual Card
PIN
Field options
Supported browsers