The dLocal Object


Create pre-built UI components to collect payment information with Smart Fields (simply referred to as fields in 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:

localeStringThe 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.
countryStringUser’s country code. ISO 3166-1 alpha-2 codes.
fontsArray (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.

cssSrc attribute

cssSrcStringA relative or absolute URL pointing to a CSS file with @font-face definitions, for example: ""

The Font object

familyStringThe name to give the font.
srcStringA 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.
displayString (Optional)A valid font-display value.
styleStringOne of 'normal', 'italic', 'oblique'. Defaults to 'normal'.
unicodeRangeString (Optional)A valid unicode-range value.
weightString (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.

.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:
nameString (Required)Cardholder name.
currencyString (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


Using Smart Fields token for Save + Payment

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

fieldSmartFieldThe 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.
amountPositive FloatThe amount of the installments plan.
currencyStringThe currency of the installments plan.

Installments Plan Object

idStringThe installments plan ID.
countryStringThe country of the installments plan (this is the same you specified when you created the field).
currencyStringThe currency of the installments plan.
binStringThe credit card bin.
amountPositive FloatThe amount of the installments plan.
installmentsInstallment Object[ ]The installments plan information.

Installments Object

idStringThe installment ID.
installment_amountPositive FloatInstallment amount.
total_amountPositive FloatInstallments total amount.
installmentsIntegerNumber of installments.

Example Installments Plan Object

    "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


Use dlocal.getBinInformation(field) to retrieve information from that card number.

Example Response

"bin": {
        "bin": "430307",
        "brand": "VI",
        "type": "DEBIT",
        "category": "CLASSIC",
        "issuer": "RIAS REDBANC, S.A.",
        "country": "UY"