Get Started

Welcome to the Voluti SPEI API! This page will guide you through the first steps to integrate and use our payment platform via SPEI.

Overview

The Voluti SPEI API allows companies to perform payment operations, check balances, reconcile transactions, and receive notifications via webhooks, all in a secure and scalable way. Authentication is performed using HMAC-SHA256, ensuring maximum security for your transactions.

Step-by-Step Guide

1. Obtain Your Credentials

Request access to the API through our support or onboarding channel. You will receive:

• API Key: your public client identifier
• API Secret: your secret key for signature generation (NEVER share or send this in requests)

2. Generate the HMAC Authentication Header

Every request to API v1 must include the following header:

HTTP

Authorization: {apiKey}:{nonce}:{signature}

Components:

• apiKey: your public key
• nonce: unique timestamp (e.g., Date.now())
• signature: HMAC-SHA256 signature of the request

Example of signature generation (Node.js):

JavaScript

const crypto = require('crypto');

function generateSignature(nonce, method, path, payload, apiSecret) {
  const message = `${nonce}${method}${path}${payload}`;
  return crypto.createHmac('sha256', apiSecret)
               .update(message)
               .digest('hex');
}

// Parameters
const nonce = Date.now();
const method = 'GET';
const path = '/api/v1/transaction/balance';
const payload = '';
const signature = generateSignature(nonce, method, path, payload, apiSecret);

// Final header
const authorization = `${apiKey}:${nonce}:${signature}`;

3. Make Your First Request

Example: balance inquiry

Bash

curl -X GET https://api-spei.production.volutipay.com.br/api/v1/transaction/balance \
  -H "Content-Type: application/json" \
  -H "Authorization: ak_123456:1625097600:abc123def456..."

Response:

JSON

{
    "total": 20.5,
    "avaliable": 21.5,
    "blocked": -1
}

4. Explore the Endpoints

• Authentication
• API Reference
• Webhooks
• Cash In
• Cash Out
• Get Balance
• Conciliation
• Webhook Subscribe

Support

If you have any questions, please refer to our documentation or contact technical support.

---

Tip: Never send your API Secret in requests. Always use HTTPS and generate a unique nonce for each call.