Security

OUR SOLUTION COUNTRIES CUSTOMERS CONTACT US
Search…
Security
Signature
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
Header
Type
Description
X-Date
String
ISO8601 Datetime with Timezone. Eg 2018-07-12T13:46:28.629Z
X-Login
String
Merchant xLogin
X-Trans-Key
String
Merchant xTransKey
Content-Type
String
application/json
X-Version
String
API Version
User-Agent
String
Used to identify the application type, operating system, software vendor or software version of the requesting software user agent.
Authorization
String
<auth version>, Signature: <hmac(secretKey, "X-Login+X-Date+RequestBody")>
Examples of HMAC signature generation in the most popular languages
Java
Other Languages
1
import java.io.ByteArrayOutputStream;
2
import java.io.IOException;
3
import java.security.InvalidKeyException;
4
import java.security.NoSuchAlgorithmException;
5
import java.util.Formatter;
6
import javax.crypto.Mac;
7
import javax.crypto.spec.SecretKeySpec;
8
​
9
public final class SignatureCalculator {
10
​
11
    private static final String HMAC_ALGORITHM = "HmacSHA256";
12
    private static final String CHARSET = "UTF-8";
13
​
14
    public static String calculateSignature(String x_Login, String x_Date, String secretKey, String body)
15
        throws IOException, InvalidKeyException, NoSuchAlgorithmException {
16
​
17
        // Create byte array with the required data for the signature.
18
        ByteArrayOutputStream bout = new ByteArrayOutputStream();
19
        bout.write(x_Login.getBytes(CHARSET));
20
        bout.write(x_Date.getBytes(CHARSET));
21
        bout.write(body.getBytes(CHARSET));
22
​
23
        // Calculate the signature.
24
        SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes(), HMAC_ALGORITHM);
25
        Mac mac = Mac.getInstance(HMAC_ALGORITHM);
26
        mac.init(signingKey);
27
        byte[] signature = mac.doFinal(bout.toByteArray());
28
​
29
        // Create a String with the signature value.
30
        Formatter formatter = new Formatter();
31
        for (byte b : signature) {
32
            formatter.format("%02x", b);
33
        }
34
        return formatter.toString();
35
    }
36
}
Copied!
Language
Code
PHP
$signature = hash_hmac("sha256", "$X-Login$X-Date$RequestBody", $secretKey);
Python
signature = hmac.new(secretKey, X-Login+X-Date+RequestBody, hashlib.sha256).hexdigest()
Ruby
signature = OpenSSL::HMAC.hexdigest('sha256', secretKey, $X-Login + $X-Date + RequestBody)
We strongly suggest testing your generated signature using the Search Payment Methods call 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
Example Credit Card Encrypted Body
Property
Type
Description
cvv
String
Credit Card security code
number
String
Credit Card number
1
"card": {
2
    "holder_name": "Thiago Gabriel",
3
    "expiration_month": 10,
4
    "expiration_year": 2040,
5
    "encrypted_data": "[encrypted JSON goes here]"
6
}
Copied!
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. Ask your Technical Account Manager for more information.
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 request can be sent unencrypted.
4.dLocal decrypts the message using the private key. 
Idempotent Requests
To perform an idempotent request, provide an additional X-Idempotency-Key header to the request.
Header
Type
Description
X-Idempotency-Key
String
Key used for perform an idempotent request. Optional.
Example Request
1
curl -X POST \
2
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
    -H 'X-Login: sak223k2wdksdl2' \
4
    -H 'X-Trans-Key: fm12O7G9' \
5
    -H 'Content-Type: application/json' \
6
    -H 'X-Version: 2.1' \
7
    -H 'User-Agent: MerchantTest / 1.0 ' \
8
    -H 'X-Idempotency-Key: a8a85bce-5733-4a6c-91b5-553ed4b3de16' \
9
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
10
    -d '{body}'
11
    https://api.dlocal.com/payments
Copied!
API DOCUMENTATION - Previous
Payins API Reference
Payment Methods
Last modified 23d ago
Copy link
Contents
Signature
Sensitive data encryption
Idempotent Requests