Security

How to make secure payment requests.

API Key

API Keys are required for all requests you make to Tu Cambio and should be included in the HTTP header x-tucambio-api-key. We will provide you with these keys, and you must keep them secure.

HMAC Signature

All requests to the Payouts API must be signed with the signature included in the Authorization request header to be accepted. This signature is generated using a shared secret (secretKey) and the HMAC-SHA256 algorithm.

We use this algorithm to confirm that a given message originates from the sender and that the data in the message has not been altered.

The signature should be calculated using a timestamp concatenated with the request payload and the shared secret key, using the HMAC SHA256 algorithm. The resulting signature should be provided to the Payouts API in hexadecimal format. For GET requests, the payload should be replaced with an empty string "".

Examples of HMAC signature generation

JavaScript

import { HmacSHA256 } from 'crypto-js';

const secretKey = "the shared secret key";

const timestamp = new Date().toISOString();
const requestPayload = { message: "Hi there" };
const payload = JSON.stringify(requestPayload);

const concatenatedData = `${timestamp}${payload}`;

const hash = HmacSHA256(concatenatedData, secretKey).toString();

PHP

<?php

$key = 'the shared secret key here';
$message = 'the message to hash here';

// to lowercase hexits
hash_hmac('sha256', "$X-Date$RequestBody", $key);

Example Headers

Header	Descripción
X-TuCambio-Api-Key	API key necessary to authenticate your request. Find your keys in the Merchant Dashboard.
X-Date	ISO8601 Datetime with Timezone. Ejemplo 2024-05-24T20:37:10.492Z
Authorization	, Signature: <hmac(secretKey, "X-Date+RequestBody")>

JWS Signature

Operations that you send to Tu Cambio that involve automated money movement (or other very sensitive operations) will require a signature using RSA private keys. These private keys are managed solely by you. You will share with TuCambio a certificate that contains only the public key.

This signature is sent in the HTTP header jws-signature.

You must also verify this signature when you receive messages from Tu Cambio in your webhooks. The header will be the same, but it will be signed with a Tu Cambio private key, and you must verify it according to the certificates we will provide for this purpose.

❗️

Let us know if you suspect that an RSA key, API key, or secret key has been compromised so we can rotate them and prevent potential vulnerabilities.