Example of a signature

How to generate signatures?

Security

All the communication against and from our API will be signed and the signature must be included as header. This signature allows us to certificate data integrity within the communication.

Prerequisites

Java

String platformId = "your-platform-id";
String secret = "your-api-key";

JSONObject body = new JSONObject();
body.put("orderId", "your-transaction-identifier");
body.put("paymentId", "90");
body.put("amount", "100.00");
body.put("platformId", platformId);

Python

PHP

JS

C#

Note: The previous body is an example, since it is dynamic and the signature can change according to the body of the request or response.

Step 1 - Create signature.

Java

    ...
    ObjectMapper objectMapper = new ObjectMapper();
    String bodyJson = objectMapper.writeValueAsString(body);
    String signatureContract = platformId + ";" + bodyJson + ";" + secret;
    String signature = generateSignature(signatureContract, secret);
    ...
    
// Helper function to generate HMAC-SHA256 signature
private String generateSignature(String signatureContract, String secret) throws NoSuchAlgorithmException, InvalidKeyException {
    Mac sha256HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
    sha256HMAC.init(secretKey);
    byte[] hash = sha256HMAC.doFinal(signatureContract.getBytes(StandardCharsets.UTF_8));
    StringBuilder result = new StringBuilder();
    for (byte b : hash) {
        result.append(String.format("%02x", b));
    }
    return result.toString();
}
    

Python

PHP

JS

C#

Step 2 - Execution of the Request

Java

String signature = "your-signature";  // Replace with the generated signature

// Open connection
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setConnectTimeout(10000); // 10 seconds timeout
conn.setReadTimeout(10000);
conn.setDoOutput(true);  // Allow sending data

// Set headers
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("x-signature", signature);

// Send the request body
try (OutputStream os = conn.getOutputStream()) {
    byte[] input = jsonBody.getBytes(StandardCharsets.UTF_8);
    os.write(input, 0, input.length);
}

// Get response code
int responseCode = conn.getResponseCode();

// Read the response
BufferedReader br;
if (responseCode == HttpURLConnection.HTTP_OK) {
    br = new BufferedReader(new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8));
} else {
    br = new BufferedReader(new InputStreamReader(conn.getErrorStream(), StandardCharsets.UTF_8));
}

StringBuilder response = new StringBuilder();
String responseLine;
while ((responseLine = br.readLine()) != null) {
    response.append(responseLine.trim());
}

// Close connection
conn.disconnect();

// Parse JSON response (if needed)
Map<String, Object> result = objectMapper.readValue(response.toString(), Map.class);

// Print result
System.out.println(result);

Python

PHP

JS

C#

Signature use cases:

1. When you call us, you should send the x-signature header, so we can validate the payload data integrity.

2. When you receive a response, you must validate the x-signature header presence and validate that it is valid.

3. When you receive a callback, you must validate the x-signature header presence and validate that it is valid.

Postman create signature Pre-request Script:

const crypto = require('crypto-js');

try {
    const platformId = 0;
    const secret = '000000-000000-000000-000000-000000';

    if (!platformId || !secret) {
        throw new Error('Missing required environment variables: platform_id or api_secret');
    }

    const requestBody = pm.request.body.raw;
    let bodyJson;

    if (requestBody) {
        try {
            bodyJson = JSON.parse(requestBody);
        } catch (e) {
            throw new Error('Invalid JSON in request body');
        }
    } else {
        bodyJson = {};
    }

    const signatureContract = `${platformId};${JSON.stringify(bodyJson).replace(/\//g, "\\/")};${secret}`;

    const signature = crypto.HmacSHA256(signatureContract, secret).toString();

    pm.request.headers.add({
        key: 'x-signature',
        value: signature
    });

} catch (error) {
    console.error('Error in pre-request script:', error.message);
    pm.environment.set('signature_error', error.message);
}