HomeGuidesAPI ReferenceStatus Page
API Reference

Security

Learn how to set up the headers for making API requests, and encrypt sensitive information.

Each request to the dLocal API must include a signature. The signature is necessary to verify that the information that is being sent is valid and secure.

Signature

Required information

  • API credentials. Access the dLocal Merchant Dashboard with your dLocal account to obtain your API keys credentials.
  • Custom information. Calculate and complete the necessary data such as the payment date information.
  • Hash. Convert all the information (letters and numbers) into an encrypted output of a fixed length using the HMAC-SHA256 algorithm.

How does it work

All calls to the Payins API should be signed using the HMAC-SHA256 algorithm, and the contents of the signature included in the Authorization header as documented below. This header should have as prefix the signature version and the hash function used, which is currently V2-HMAC-SHA256.

Headers

HeaderTypeDescription
X-DateStringISO8601 Datetime with Timezone. Eg: 2018-07-12T13:46:28.629Z.
X-LoginStringAPI key necessary to authenticate your request. Find your keys in the Merchant Dashboard.
X-Trans-KeyStringAPI key necessary to authenticate your request. Find your keys in the Merchant Dashboard.
Content-TypeStringAlways complete application/json
X-VersionStringCurrent API Version number: 2.1
User-AgentStringUsed to identify the application type, operating system, software vendor, or software version of the requesting software user agent.
AuthorizationStringUse the required information mention before and set this field with the following structure: V2-HMAC-SHA256, Signature: <hmac(secretKey, "X-Login+X-Date+RequestBody")>

ℹ️

Secret key credential

Do not forget to use your Secret key for masking your signature. Read more information in the Get your API test credentials section.

Example Request

curl -X POST \
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
    -H 'X-Login: {X-Login}' \
    -H 'X-Trans-Key: {X-Trans-Key}' \
    -H 'Content-Type: application/json' \
    -H 'X-Version: 2.1' \
    -H 'User-Agent: MerchantTest / 1.0 ' \
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
    -d '{body}'
    https://api.dlocal.com/payments

Examples of HMAC signature generation

Our GitHub repository hosts a variety of signature examples, which can be a valuable resource for understanding implementation details and for reference in your development process.

Check out signature examples on GitHub > 

import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Formatter;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class SignatureCalculator {

    private static final String HMAC_ALGORITHM = "HmacSHA256";
    private static final String CHARSET = "UTF-8";

    public static String calculateSignature(String x_Login, String x_Date, String secretKey, String body)
        throws IOException, InvalidKeyException, NoSuchAlgorithmException {

        // Create byte array with the required data for the signature.
        ByteArrayOutputStream bout = new ByteArrayOutputStream();
        bout.write(x_Login.getBytes(CHARSET));
        bout.write(x_Date.getBytes(CHARSET));
        bout.write(body.getBytes(CHARSET));

        // Calculate the signature.
        SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes(), HMAC_ALGORITHM);
        Mac mac = Mac.getInstance(HMAC_ALGORITHM);
        mac.init(signingKey);
        byte[] signature = mac.doFinal(bout.toByteArray());

        // Create a String with the signature value.
        Formatter formatter = new Formatter();
        for (byte b : signature) {
            formatter.format("%02x", b);
        }
        return formatter.toString();
    }
}

$signature = hash_hmac("sha256", "$X-Login$X-Date$RequestBody", $secretKey);

signature = hmac.new(secretKey, X-Login+X-Date+RequestBody, hashlib.sha256).hexdigest()

signature = OpenSSL::HMAC.hexdigest('sha256', secretKey, $X-Login + $X-Date + RequestBody)


import * as crypto from 'crypto';

class SignatureCalculator {
    calculateSignature(timestamp: string, body?: string): string {
        let message: string = process.env.DLOCAL_X_LOGIN + timestamp;

        if (body) {
            message += body;
        }

        const hmac = crypto.createHmac('sha256', process.env.DLOCAL_SECRET_KEY);
        hmac.update(message, 'utf-8');
        const signature: string = hmac.digest('hex');

        return `V2-HMAC-SHA256, Signature: ${signature}`;
    }
}

// Example usage
const calculator = new SignatureCalculator();
const timestamp = new Date().toISOString(); // Corrected the timestamp
const body = "yourRequestBody";
const result = calculator.calculateSignature(timestamp, body);
console.log(result);

function calculateSignature(timestamp, body) {
    let message = process.env.DLOCAL_X_LOGIN + timestamp;

    if (body) {
        message += body;
    }

    const hmac = crypto.createHmac('sha256', process.env.DLOCAL_SECRET_KEY);
    hmac.update(message, 'utf-8');
    const signature = hmac.digest('hex');

    return `V2-HMAC-SHA256, Signature: ${signature}`;
}

// Example usage
const timestamp = new Date().toISOString(); // Set timestamp to current time
const body = "yourRequestBody";
const result = calculateSignature(timestamp, body);
console.log(result);

static string SignatureCalculator(string x_Login, string x_Date, string secretKey, string body)
    {
        string concatenatedData = x_Login + x_Date + body;
        byte[] data = Encoding.UTF8.GetBytes(concatenatedData);
        byte[] keyBytes = Encoding.UTF8.GetBytes(secretKey);

        using (var hmacsha256 = new HMACSHA256(keyBytes))
        {
            byte[] hashBytes = hmacsha256.ComputeHash(data);
            StringBuilder signatureBuilder = new StringBuilder();

            foreach (byte b in hashBytes)
            {
                signatureBuilder.Append(b.ToString("x2"));
            }

            return signatureBuilder.ToString();
        }
    }

ℹ️

Signature testing

We strongly suggest testing your generated signature by making a test payment to make sure your signature is working before moving forward with the integration.

Sensitive data encryption

Credit Card data, such as number and cvv, can be encrypted inside the JSON Request Body using JWE. This standard is being widely used in the market, and most programming languages have libraries to support it.
The following parameters can be encrypted and added to a encrypted_data field:

Properties

PropertyTypeDescription
cvvStringCredit card security code
numberStringCredit card number

Example Credit Card Encrypted Body

"card": {
    "holder_name": "Thiago Gabriel",
    "expiration_month": 10,
    "expiration_year": 2040,
    "encrypted_data": "[encrypted JSON goes here]"
}

The encryption flow is the following:

  1. dLocal creates an RSA key pair and issue a certification with a 3rd party authority.
  2. dLocal shares the public key to the merchant using an encrypted method.
  3. The merchant uses this public key to encrypt the number and cvv into a JSON using JWE, and send it in the API request within the encrypted_data field. The rest of the requests can be sent unencrypted.
  4. dLocal decrypts the message using the private key.

Additional request headers

Idempotent Requests

To perform an idempotent request, provide an additional X-Idempotency-Key header to the request.

HeaderTypeDescription
X-Idempotency-KeyStringKey used to perform an idempotent request. Optional.

Max. length: 42 characters.

Example Request

curl -X POST \
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
    -H 'X-Login: {X-Login}' \
    -H 'X-Trans-Key: {X-Trans-Key}' \
    -H 'Content-Type: application/json' \
    -H 'X-Version: 2.1' \
    -H 'User-Agent: MerchantTest / 1.0 ' \
    -H 'X-Idempotency-Key: {Idempotency-Key}' \
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
    -d '{body}'
    https://api.dlocal.com/payments

Payment source

Include the X-Dlocal-Payment-Source header in your request to specify the entity managing the payment.

Only for Payment Orchestrators, PSPs & Gateways.

HeaderTypeDescription
X-Dlocal-Payment-SourceStringUsed to identify the party requesting the payment. Should always have the same value.

Max. length: 100 characters.

Example Request

curl -X POST \
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
    -H 'X-Login: {X-Login}' \
    -H 'X-Trans-Key: {X-Trans-Key}' \
    -H 'Content-Type: application/json' \
    -H 'X-Version: 2.1' \
    -H 'X-Dlocal-Payment-Source: {PaymentSourceName}', \
    -H 'User-Agent: MerchantTest / 1.0 ' \
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
    -d '{body}'
    https://api.dlocal.com/payments

© 2024 DLOCAL. ALL RIGHTS RESERVED

Dlocal LLP (Company Number UK OC413287) is a limited liability partnership incorporated in England and Wales. DLocal Limited (Company Registration Number C77538) is authorised by the Malta Financial Services Authority under the Financial Institutions Act for the issuance of electronic money and the provision of payment services. Dlocal Corp LLP (Company Number UK OC 424987) is registered as a Money Service Business (MSB) with Financial Crime Enforcement Network in United States of America (USA) under MSB Registration Numbers 31000193620515. Dlocal Corp LLP acts as agent of e-commerce merchants based in the USA, and collects payments from end users based in emerging markets, on behalf of the merchants.