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

Example Set - PIN encrypted request

{
    "last_digits": "360686",
    "encrypted_data": "[encrypted pin]"
}

Where "encrypted_data": 
{ 
    "pin":"1234"
}

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.

PIN Setting

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.

<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="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 PIN Field.
var pinField = fields.create('pin', { style, maskInput: true });
// Add an instance of the pin Field into the `pin-field` <div>.
pinField.mount(document.getElementById('pin-field'));

3. Tokenize the PIN

Then you need to tokenize the PIN value obtained from the Smart Field through the createPinToken method.

dlocalInstance.createPinToken(pinField)
    .then(function(result) {
        const pin_token = result.token; // result.token is the PIN tokenized
    })

4. Set PIN

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

{
    "last_digits": "123456",
    "token": "pin_token"
}

{
   "token": "AQICAHjajCjj_m_SHvhC9QhV2CT_N062EgS6-BUD2Ddfq2y_iAGnPrZc9FWX_dJtzzWg5hzQAAAAhjCBgwYJKoZIhvcNAQcGoHYwdAIBADBvBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDAkzOBqmTYxlvgXg8wIBEIBCaT0WCmX7UbMq2F6fjWa1bhjTgHzxpFk0vXtZwYwB15p9m1MqgRWMLumxuJUIGqn12D0pqdT6JMGGh3HNOktCDSu8"
}

Attribute Detail