v2.1
Solutions
GUIDES
Smart Fields Setup Guide
Introduction
This guide will walk you through the creation of a payment form using dLocal's all-in-one
card Smart Field (also referred to as 'cardField'). The card Field simplifies the form and minimizes the number of fields required by inserting a single, flexible input field that securely collects all necessary card details.You can make use of Smart Fields (our pre-built UI components) to create a payment form that securely collects your customer’s card information without you needing to handle sensitive card data. The card details are then converted to a representative token that you can safely send to your servers.
Below is a live demo of the
cardSmart Field. Try changing the width of the browser to see how the Field adapts. You can make changes to the code on CodePen:Card Smart Field (below) matching the style of the merchant's form
Creating a custom payment form with Smart Fields requires five steps:
- 3.
Before you start: HTTPS requirements
All submissions of payment info using Smart Fields are made via a secure HTTPS connection. However, to protect yourself from certain forms of man-in-the-middle attacks, and to prevent your customers from seeing Mixed Content warnings in modern browsers, you must serve the page containing the payment form over HTTPS as well.
Step 1: Set up Smart Fields
Smart Fields 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. For testing purposes, you can use https://js-sandbox.dlocal.com.
1
<script src="https://js.dlocal.com/"></script>
Copied!
Next, create an instance of Smart Fields (referred to as just
fields()):1
var dlocal = dlocal('your_API_key');
2
var fields = dlocal.fields({
3
locale: 'en',
4
country: 'BR'
5
});
Copied!
To initialize the dlocal helper you will need an API Key. Please contact your Technical Account Manager to obtain one.
Step 2: Create your payment form
To securely collect card details from your customers, Smart Fields creates UI components for you that are hosted by dLocal. They are then placed into your payment form, rather than you creating them directly.
To determine where to insert these components, create empty DOM elements (containers) with unique IDs within your payment form. We recommend placing your container within a
<label>or next to a <label> with a for attribute that matches the unique id of the Smart Field container. By doing so, the Field automatically gains focus when the customer clicks on the corresponding label.For example:
1
<form action="/charge" method="post" id="payment-form">
2
<div class="form-row">
3
<label for="card-field">
4
Credit or Debit card
5
</label>
6
<div id="card-field">
7
<!-- A dLocal Smart Field will be inserted here. -->
8
</div>
9
10
<!-- Used to display Smart Field errors. -->
11
<div id="card-errors" role="alert"></div>
12
</div>
13
<div class="form-rowd">
14
<label>Cardholder name</label>
15
<input id="card-holder" type="text" name="card-holder" placeholder="John Doe" />
16
</div>
17
<button>Pay</button>
18
</form>
Copied!
When the form above has loaded, create an instance of a Field and mount it to the Field container created above:
1
// Custom styling can be passed to options when creating a Smart Field.
2
var style = {
3
base: {
4
// Add your base input styles here. For example:
5
fontSize: '16px',
6
color: "#32325d",
7
}
8
};
9
10
// Create an instance of the card Field.
11
var card = fields.create('card', {style: style});
12
13
// Add an instance of the card Field into the `card-field` <div>.
14
card.mount(document.getElementById('card-field'));
Copied!
Smart Fields validate user input as it is typed. To help your customers catch mistakes, you should listen to
change events on the card Field and display any 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!
Step 3: Create installments plan (Optional)
You can specify an installment plan, to guarantee the surcharge per installment that will be charged.
1
<!-- Add to your form -->
2
<div class="form-row">
3
<label>Fees to pay</label>
4
<div class="select-wrapper">
5
<span>▼</span>
6
<select id="installments" disabled>
7
<option value="">Enter the card number first</option>
8
</select>
9
</div>
10
</div>
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.1
let actualBrand = null;
2
card.on('brand', function (event) {
3
document.getElementById('card-errors').innerHTML = "";
4
if (event.brand) {
5
//when card brand changes
6
actualBrand = cardStatus.brand;
7
//totalAmount & currency of the purchase
8
dlocal.createInstallmentsPlan(card, totalAmount, currency)
9
.then((result) => {
10
var installmentsSelect = document.getElementById('installments');
11
buildInstallments(installmentsSelect, result.installments);
12
}).catch((result) => {
13
console.error(result);
14
});
15
}
16
});
17
18
function buildInstallments(installmentsInput, installmentsPlan) {
19
const installmentsOptions = installmentsPlan.installments.reduce(function (options, plan) {
20
options += "<option value=" + plan.id + ">" + plan.installments + " of " + currency + " " + plan.installment_amount + " (Total : " + currency + " " + plan.total_amount + ")</option>";
21
return options;
22
}, "");
23
installmentsInput.disabled = false;
24
installmentsInput.innerHTML = installmentsOptions;
25
}
Copied!
Step 4: Create a token to securely transmit card information
The payment details collected using Smart Fields 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).
1
// Create a token or display an error when the form is submitted.
2
var form = document.getElementById('payment-form');
3
form.addEventListener('submit', function(event) {
4
event.preventDefault();
5
var cardHolderName = document.getElementById('card-holder').value;
6
dlocal.createToken(card, {
7
name: cardHolderName
8
}).then(function(result) {
9
// Send the token to your server.
10
dlocalTokenHandler(result.token);
11
}).catch((result) => {
12
if (result.error) {
13
// Inform the customer that there was an error.
14
var errorField = document.getElementById('card-errors');
15
errorField.textContent = result.error.message;
16
}
17
});
18
});
Copied!
dlocal.createToken returns a Promise which resolves with a result object. This object has result.token the token that was successfully created.Step 5: 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.
1
function dlocalTokenHandler(token) {
2
// Insert the token ID into the form so it gets submitted to the server
3
var form = document.getElementById('payment-form');
4
var tokenInput = document.createElement('input');
5
tokenInput.setAttribute('type', 'hidden');
6
tokenInput.setAttribute('name', 'dlocalToken');
7
tokenInput.setAttribute('value', token);
8
form.appendChild(tokenInput);
9
10
// Submit the form
11
form.submit();
12
}
Copied!
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. You can learn more about saving cards here.
What's next? Create a Payment
Last modified 2yr ago
Copy link
Contents
Introduction
Before you start: HTTPS requirements
Step 1: Set up Smart Fields
Step 2: Create your payment form
Step 3: Create installments plan (Optional)
Step 4: Create a token to securely transmit card information
Step 5: Submit the token and the rest of your form to your server
What's next? Create a Payment