Autenticação

A Void Payments API utiliza HTTP Basic Auth para autenticar todas as requisições. Além disso, há uma camada adicional de segurança via validação de IP de origem.

Credenciais

Ao criar sua conta, você recebe duas credenciais:

⚠️

Atenção

O clientSecret é exibido apenas uma vez no momento da criação. Salve-o em um local seguro imediatamente. Se você perder o secret, será necessário gerar um novo par de credenciais.

Como Autenticar

Passo 1: Codificar as credenciais

Concatene o clientId e o clientSecret separados por : (dois-pontos) e codifique o resultado em Base64:

base64(clientId:clientSecret)

Exemplo:

clientId:     ck_live_a1b2c3d4e5f6
clientSecret: sk_live_f6e5d4c3b2a1

Concatenado:  ck_live_a1b2c3d4e5f6:sk_live_f6e5d4c3b2a1
Base64:       Y2tfbGl2ZV9hMWIyYzNkNGU1ZjY6c2tfbGl2ZV9mNmU1ZDRjM2IyYTE=

Passo 2: Enviar no header Authorization

Inclua o valor Base64 no header Authorization com o prefixo Basic :

Authorization: Basic Y2tfbGl2ZV9hMWIyYzNkNGU1ZjY6c2tfbGl2ZV9mNmU1ZDRjM2IyYTE=

Exemplo completo com cURL

A maioria dos clientes HTTP suporta Basic Auth nativamente. Com cURL, use a flag -u:

curl -X GET "https://api.voidxpay.com/v1/balance" \
  -u "ck_live_a1b2c3d4e5f6:sk_live_f6e5d4c3b2a1"

O cURL codifica automaticamente em Base64. O header gerado será:

GET /v1/balance HTTP/1.1
Host: api.voidxpay.com
Authorization: Basic Y2tfbGl2ZV9hMWIyYzNkNGU1ZjY6c2tfbGl2ZV9mNmU1ZDRjM2IyYTE=

Exemplos por Linguagem

Node.js

const axios = require('axios');

const clientId = 'ck_live_a1b2c3d4e5f6';
const clientSecret = 'sk_live_f6e5d4c3b2a1';

const response = await axios.get('https://api.voidxpay.com/v1/balance', {
  auth: {
    username: clientId,
    password: clientSecret,
  },
});

console.log(response.data);
// { balance: 15000, currency: "BRL" }

Python

import requests

client_id = 'ck_live_a1b2c3d4e5f6'
client_secret = 'sk_live_f6e5d4c3b2a1'

response = requests.get(
    'https://api.voidxpay.com/v1/balance',
    auth=(client_id, client_secret)
)

print(response.json())
# {'balance': 15000, 'currency': 'BRL'}

PHP

<?php
$clientId = 'ck_live_a1b2c3d4e5f6';
$clientSecret = 'sk_live_f6e5d4c3b2a1';

$ch = curl_init('https://api.voidxpay.com/v1/balance');
curl_setopt($ch, CURLOPT_USERPWD, "$clientId:$clientSecret");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
// ['balance' => 15000, 'currency' => 'BRL']

Java

import java.net.http.*;
import java.util.Base64;

String clientId = "ck_live_a1b2c3d4e5f6";
String clientSecret = "sk_live_f6e5d4c3b2a1";

String credentials = Base64.getEncoder()
    .encodeToString((clientId + ":" + clientSecret).getBytes());

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.voidxpay.com/v1/balance"))
    .header("Authorization", "Basic " + credentials)
    .GET()
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
// {"balance":15000,"currency":"BRL"}

Validação de IP

Além do Basic Auth, a API valida o IP de origem de cada requisição contra a lista de IPs autorizados configurada na sua conta.

Como funciona

1. Sua conta possui uma lista de IPs permitidos (configurada no cadastro)
2. A cada requisição, o IP de origem é extraído e comparado com a lista
3. Se o IP não estiver na lista, a requisição é rejeitada com 403 Forbidden

Configuração

A lista de IPs permitidos é definida no momento do cadastro da conta. Para adicionar ou remover IPs, entre em contato com o suporte.

Formatos suportados:

🚧

Recomendação de segurança

Em produção, sempre configure IPs específicos. O wildcard * deve ser usado apenas em ambientes de desenvolvimento/teste.

Exemplo de erro

Se o IP não estiver autorizado:

// HTTP 403 Forbidden
{
  "error": "IP_NOT_ALLOWED",
  "message": "Request from unauthorized IP address."
}

Fluxo Completo de Autenticação

A cada requisição, a API executa as seguintes verificações na ordem:

Requisição recebida
       │
       ▼
┌─────────────────────┐     ┌─────────────────────────────────┐
│ Header Authorization│─NO─►│ 401 - Missing Authorization     │
│ presente?           │     │ header. Use Basic Auth.          │
└────────┬────────────┘     └─────────────────────────────────┘
         │ YES
         ▼
┌─────────────────────┐     ┌─────────────────────────────────┐
│ Formato Basic Auth  │─NO─►│ 401 - Invalid Authorization     │
│ válido?             │     │ header format.                   │
└────────┬────────────┘     └─────────────────────────────────┘
         │ YES
         ▼
┌─────────────────────┐     ┌─────────────────────────────────┐
│ clientId e           │─NO─►│ 401 - Invalid credentials.      │
│ clientSecret válidos?│     │                                  │
└────────┬────────────┘     └─────────────────────────────────┘
         │ YES
         ▼
┌─────────────────────┐     ┌─────────────────────────────────┐
│ Usuário está ativo? │─NO─►│ 403 - User is inactive          │
│                     │     │ or suspended.                    │
└────────┬────────────┘     └─────────────────────────────────┘
         │ YES
         ▼
┌─────────────────────┐     ┌─────────────────────────────────┐
│ IP está na           │─NO─►│ 403 - Request from unauthorized │
│ whitelist?           │     │ IP address.                      │
└────────┬────────────┘     └─────────────────────────────────┘
         │ YES
         ▼
┌─────────────────────┐     ┌─────────────────────────────────┐
│ Conta (account)      │─NO─►│ 403 - Account is inactive       │
│ está ativa?          │     │ or not found.                    │
└────────┬────────────┘     └─────────────────────────────────┘
         │ YES
         ▼
   ✅ Requisição autorizada
   (prossegue para o endpoint)

Erros de Autenticação

401 Unauthorized

Indica que as credenciais estão ausentes, mal formatadas ou inválidas.

Exemplo de resposta:

// HTTP 401 Unauthorized
{
  "error": "INVALID_CREDENTIALS",
  "message": "Missing Authorization header. Use Basic Auth (client_id:client_secret)."
}

403 Forbidden

Indica que as credenciais são válidas, mas a requisição foi bloqueada por uma restrição de segurança.

Exemplo de resposta:

// HTTP 403 Forbidden
{
  "error": "IP_NOT_ALLOWED",
  "message": "Request from unauthorized IP address."
}

Boas Práticas de Segurança

1. Nunca exponha o clientSecret no frontend

O clientSecret deve ser mantido exclusivamente no backend. Nunca inclua em:

• Código JavaScript executado no navegador
• Aplicativos mobile (Android/iOS)
• Repositórios públicos (GitHub, GitLab)
• Logs de aplicação

// ❌ ERRADO - Credenciais no frontend
fetch('https://api.voidxpay.com/v1/balance', {
  headers: {
    'Authorization': 'Basic ' + btoa('client_id:client_secret')
  }
});

// ✅ CORRETO - Chamada via seu backend
fetch('/api/balance');  // Seu backend faz a chamada para a Void Payments API

2. Use variáveis de ambiente

Armazene as credenciais em variáveis de ambiente, nunca hardcoded no código:

# .env (NÃO commitar este arquivo)
VOIDXPAY_CLIENT_ID=ck_live_a1b2c3d4e5f6
VOIDXPAY_CLIENT_SECRET=sk_live_f6e5d4c3b2a1

// Uso no código
const clientId = process.env.VOIDXPAY_CLIENT_ID;
const clientSecret = process.env.VOIDXPAY_CLIENT_SECRET;

3. Configure IPs específicos em produção

Evite usar wildcard (*) na lista de IPs. Configure apenas os IPs dos servidores que realmente precisam acessar a API.

4. Rotacione credenciais periodicamente

Solicite a geração de novas credenciais periodicamente e atualize suas configurações. Mantenha apenas credenciais ativas.

5. Monitore acessos não autorizados

Fique atento a respostas 401 e 403 nos logs da sua aplicação. Um volume alto pode indicar tentativas de acesso indevido ou configuração incorreta de IP.

Testando a Autenticação

A maneira mais simples de testar se suas credenciais estão funcionando é consultar o saldo:

curl -X GET "https://api.voidxpay.com/v1/balance" \
  -u "seu_client_id:seu_client_secret"

Se autenticado com sucesso:

// HTTP 200 OK
{
  "balance": 15000,
  "currency": "BRL"
}

Se as credenciais forem inválidas:

// HTTP 401 Unauthorized
{
  "error": "INVALID_CREDENTIALS",
  "message": "Invalid credentials."
}

Se o IP não estiver autorizado:

// HTTP 403 Forbidden
{
  "error": "IP_NOT_ALLOWED",
  "message": "Request from unauthorized IP address."
}

Suporte

Problemas com autenticação? Verifique os pontos mais comuns:

Em caso de dúvidas, entre em contato:

• 📧 Email: [email protected]