VizumVizum

VIZUM Payments-as-a-Service

Explore the capabilities of our API and learn how to integrate it into your applications.

Vizum API

Version: 1.0.0

This API provides access to our Vizums's data, allowing you to retrieve user information, check FX rates, and manage your account.

Formatting the Signature

The API signature should be included in the header of your request. Here's an example of how to format the signature headers:

GET /api/v1/utils/rates
HTTP/1.1
Host: sandbox.vizum.mx
Content-Type: application/json
access_key: <<your-vizum-client-id>>
signature: YzU0NmYwMGUzMDI1NDI5YTAyOTI1NDk0OWMzNjI1MzM5ZWE1OTRiYTZhMWEyY2JiZGVmYzk2NzZlNDg0OWU1OQ==
timestamp:1712245993
salt: 4eeae17d389859c83c64e493
idempotency: 1712246003304

Real-Time FX Rates

Stay up-to-date with the latest foreign exchange rates to make informed financial decisions.

View FX Rates
Current FX Rates
Updated every 15 minutes.
Deposit USD/MXN
17.93
Withdraw USD/MXN
17.63

Powerful API for Developers

Integrate our financial services seamlessly into your applications with our comprehensive API documentation and examples.

View API DocsGet API Key
API Endpoint
https://sandbox.vizum.mx
curl -X GET -H "vizum-client-id: <<your-vizum-client-id>>" https://sandbox.vizum.mx
API Response
Example JSON response from the transactions endpoint.

{
    "id": "da7d8e08-4223-4113-a23b-ed1ea82bd93e",
    "body": {
      "vizum_id": "d1f04813-6e9f-42cd-a070-2f8b0bafb514",
      "beneficiary_account": "638180000152900340",
      "beneficiary_name": "ND",
      "beneficiary_rfc": "ND",
      "concept": "prueba",
      "usd_requested_amount": 0.1,
      "created_at": "2024-05-31T11:38:23.404-06:00",
      "mxn_requested_amount": -5.85,
      "vizum_fx": 16.58,
      "fixed_fee_mxn": 7.5,
      "variable_fee_mxn": -0.05
  },
    "status": 200,
    "message": "Payout created successfully"
}
Calculation of Signature
The signature is calculated as a hash of a concatenation of specific strings.

The signature is calculated according to the following formula:

signature = BASE64 ( HASH ( httpmethod + urlpath + salt + timestamp + accesskey + secretkey + bodystring ) )

  • BASE64 is a Base-64 encoding algorithm.
  • HASH is the HMAC-SHA256 algorithm.
  • httpmethod is the HTTP method, in lower-case letters.
  • urlpath is the portion of the URL after the base URI, such as https://sandbox.vizum.mx. The URL path starts with /api/v1.
  • salt is a random string for each request. Recommended length: 8-16 characters.
  • timestamp is the time of the request, in Unix time (seconds).
  • accesskey is a unique string assigned by Vizum for each user.
  • secretkey is a unique string for each user, assigned by Vizum. The secret key is like a password, and is transmitted only as part of the calculated signature. Do not share it with your customers or partners, and do not transmit it in plaintext.
  • bodystring is a valid JSON string (relevant to requests that contain a body). If the body is empty, it must be empty in the request and in the signature calculation, and not empty curly braces.
API Signature
How to create a cryptographic signature for the API requests.

To ensure the integrity and authenticity of API requests, we require a cryptographic signature to be included in the request headers. Here's how to create the signature:

  1. Prepare the request payload (e.g., JSON body or query parameters) and convert it to a string.
  2. Generate a random string (salt) for each request. Recommended length: 8-16 characters.
  3. Get the current time in Unix time (seconds) format.
  4. Concatenate the HTTP method (in lower-case letters), request URL path, salt, timestamp, access key, secret key, and the payload string.
  5. Calculate the SHA-256 hash of the concatenated string using your API secret key as the HMAC key.
  6. Encode the resulting hash value in Base64 format.
  7. Include the Base64-encoded signature in the "signature" header of your API request.
  8. Include the access key in the "access_key" header of your API request.
  9. Include the salt in the "salt" header of your API request.
  10. Include the timestamp in the "timestamp" header of your API request.

Here's an example in Javascript using the "hmac" and "CryptoJS" libraries:

script.js

    import CryptoJS from 'crypto-js';

    const accessKey = '<VIZUM_CLIENT_ID>' 
    const secretKey = '<YOUR_SECRET_KEY>' 
    const log = true; 
    
    /**
     * @param {string} method - HTTP method
     * @param {string} url - URL path
     * @param {object} body - Body of the request
     */
    export async function buildRequest(method, urlPath, body = null) {
      try {
        let headers = {}
    
       //console.log('body |', body);
    
        const salt = generateRandomString();
        const idempotency = new Date().getTime().toString();
        const timestamp = (Math.floor(new Date().getTime() / 1000) - 10).toString();
        const signature = await sign(method, urlPath, salt, timestamp, body);
    
        headers = {
          path: urlPath,
          port: 443,
          method: method,
          headers: {
            'Content-Type': 'application/json',
            access_key: accessKey,
            signature: signature,
            timestamp: timestamp,
            salt: salt,
            idempotency: idempotency
          },
          body: body ? JSON.stringify(body) : body
        }
        
        return headers;
    
      }
      catch(err) {
        log && console.log('buildRequest |', err)
      }
    }
    
    function generateRandomString(size = 12) {
      try {
        let salt = CryptoJS.lib.WordArray.random(size);
        return salt.toString();
      }
      catch (error) {
        log && console.log('salt error |', error)
      }
    }
    
    /**
     * @param {string} httpMethod - HTTP method
     * @param {string} urlPath - URL path
     * @param {string} salt - Salt for the signature
     * @param {string} timestamp - Timestamp in ISO format
     * @param {object} body - Body of the request
     */
    async function sign(httpMethod, urlPath, salt, timestamp, body) {
      try {
        let bodyString = "";
            if (body) {
                bodyString = JSON.stringify(body);
                bodyString = bodyString == "{}" ? "" : bodyString;
            }
        //console.log('bodyString |', bodyString);
        const toSign = httpMethod.toLowerCase() + urlPath + salt + timestamp + accessKey + secretKey + bodyString;
        //console.log('toSign |', toSign);
        let signature = CryptoJS.enc.Hex.stringify(
          CryptoJS.HmacSHA256(toSign, secretKey)
        );
        signature = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(signature));
        
       //console.log('signature |', signature);
        return signature;
      }
      catch (error) {
        throw error
      }
    }
    
    
    // # How to use this function
    //   const url = {VIZUM_URL}{urlPath};
    //    return await fetch(url, headers)
    //      .then();
    //    console.log(headers);