Full PCI Compliant Merchants

If the merchant comply with the Payment Card Industry Data Security Standard (PCI DSS), Sensitive Card Data, the PIN can be send encrypted inside the JSON Request Body using JWE.

When sending the PIN data, the following parameter should be received encrypted using these instructions.

Properties

Property	Type	Description
`encrypted_data`	String	Encrypted previous and new PIN.

Example - Update PIN Encrypted Request

{ 
    "encrypted_data":"[encrypted old pin and new pin]"
}

Where "encrypted_data": 
{ 
    "old_pin":"1234", 
    "new_pin":"4321"
}

Non PCI Compliant Merchants

Prerequisites to get started

HTTPS requirements

All information using Smart Fields is 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.

1. Set up Smart Fields

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>

Next, create an instance of Smart Fields (referred to as just fields()):

var dlocalInstance = dlocal('your_API_key');
var fields = dlocalInstance.fields({
    locale: 'es',
    country: 'CO'
});

❗
To initialize the dLocal helper you will need an API key. You can generate it in the Merchant Dashboard.

📘
For more information on dLocal.js, please visit our dLocal.js Reference page.

2. Create your form

To securely show card details from your customers, Smart Fields creates UI components for you that are hosted by dLocal. They are then placed into your form, rather than you creating them directly.

To determine where to insert these components, create empty DOM elements (containers) with unique IDs within your form.

For example:

<form>
    <div id="old-pin-field">
        <!-- A dLocal Smart Field will be inserted here. -->
    </div>
    <div id="new-pin-field">
        <!-- A dLocal Smart Field will be inserted here. -->
    </div>
</form>

When the form above has loaded, create an instance of a Field and mount it to the Field container created above:

// Custom styling can be passed to options when creating a Smart Field.
var style = {
    // Add your base input styles here. For example:
    base: {
        fontSize: '16px',
        fontFamily: "'Inter UI medium', sans-serif",
        lineHeight: '18px',
        fontSmoothing: 'antialiased',
        color: '#333',
        '::placeholder': {
            color: '#aab7c4'
        }
    }
};
// Create an instance of the old PIN Field.
var oldPinField = fields.create('old-pin', { style });
// Add an instance of the old-pin Field into the `old-pin-field` <div>.
oldPinField.mount(document.getElementById('old-pin-field'));
// Create an instance of the new PIN Field.
var newPinField = fields.create('new-pin', { style, maskInput: true });
// Add an instance of the new-pin Field into the `new-pin-field` <div>.
newPinField.mount(document.getElementById('new-pin-field'));

3. Tokenize PINs

Then you need to tokenize both old and new pins values obtained from the smart field. It’s possible with the createPinToken method.

dlocalInstance.createPinToken(newPinField)
    .then(function(result) {
        const oldPinToken = result.oldPinToken; // result.oldPinToken is the old pin tokenized
        const newPinToken = result.newPinToken; // result.newPinToken is the new pin tokenized
    })

4. Change PIN

Once you have the PINs tokenized, you need to request a POST to /cards/{card_id}/pin/change with the following body payload:

{
    "old_pin_token": "oldPinToken",
    "new_pin_token": "newPinToken"
}

{
   "old_pin_token": "J/wrMTkUecFHqouycWas/cbljhfw29QCY04V+CbZIi1vgX4LwDfc5NyoS0fv6S1ASLt2URNTx9ifuv+64iBUBEVd4G91/GNCdo/GUYJlwRExsY6qaUsWorO9R3d2UfNp8h5Es1oOuOo/MtSLawdoolEYR0JZjnMKg3xNAyGAE8q4V75oLeMjo2QQpvqg2pW+BWLRjyNHioy94Wbw/GfSuA4WxAK/DoAAOqCbSCyLTq+C5LD3VjWCASSu4HEuz3bw/i4nyxik9htTOGhN3qMYylOgmGVVS9i4wZstQbaSKqpxuPS9+SHjxG+rjPFY6pi6V076zaqu0ARxF5UktNtW5A==",
   "new_pin_token": "foxDOTczYBMFIu8zkDb1Q+cM/iElcIT5YccgvxssyRxBs+IULTXbq2gnYQqfN82U+VUuNFAxVv+vjBOrrz1TS8scgYt2Gt15yuX6XPNSKw2UiiYDUKV6z61fINhidpAerW+fcVcFo8pZ7QpJvNj+c2XD3/P7BnoBiUTK5a5WtCqpnyCXnne4syY5NgXCgROmJHxJ7+SG9Pyx04NZt96AI7ldGz9QApEIdlOWeYdoVGd5VuldDOsabNTYsHLFD1yj7hlFNdqLAS1SstE/FWi4CU91e4stprX70flA9QI0OG2L7Y39b+lfriNdq7ouJ25/Jx7gYU95ZS6AMc6s7gAxlQ=="
}

Attribute Detail

Attribute	Description
`token`	PIN tokenized (successful response of createPinToken method).