Visão Geral

A Void Payments API permite que sua aplicação receba e envie pagamentos PIX de forma programática. Com ela, você pode gerar cobranças PIX (QR Code), realizar transferências para qualquer chave PIX e acompanhar todas as transações em tempo real via webhooks.

Início Rápido

Para começar a usar a API, você precisa de:

1. Credenciais de acesso (clientId e clientSecret) — fornecidas no cadastro da sua conta
2. URL de webhook configurada — para receber notificações de status em tempo real
3. IP de origem autorizado — seu IP deve estar na lista de IPs permitidos da conta

📘

Primeira integração?

Recomendamos consultar a página de Autenticação para configurar suas credenciais antes de começar.

URL Base

Todas as URLs de endpoint são relativas à URL base. Por exemplo:

POST https://api.voidxpay.com/v1/pix-in
GET  https://api.voidxpay.com/v1/balance

Principais Funcionalidades

PIX IN (Recebimento)

Crie cobranças PIX e receba pagamentos diretamente na sua conta.

Fluxo resumido:

1. POST /v1/pix-in → QR Code gerado (status: waiting_payment)
2. Pagador escaneia e paga o QR Code
3. Webhook pix-in.paid → Saldo creditado automaticamente

Cashout (Saque / Transferência PIX)

Envie dinheiro para qualquer chave PIX a partir do saldo da sua conta.

Fluxo resumido:

1. POST /v1/cashout → Saldo debitado (status: pending)
2. Banco processa a transferência (status: processing)
3. Webhook cashout.completed → PIX enviado com sucesso

🚧

Importante

Em caso de falha no cashout (failed, rejected, cancelled), o saldo é devolvido automaticamente à sua conta.

Saldo

Consulte o saldo disponível da sua conta a qualquer momento.

Webhooks

Receba notificações em tempo real sobre mudanças de status nas transações.

Autenticação

Todas as requisições à API utilizam HTTP Basic Auth. Envie suas credenciais clientId e clientSecret codificadas em Base64 no header Authorization.

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

⚠️

Segurança

Nunca exponha o clientSecret em código frontend (JavaScript no navegador, apps mobile). A API deve ser consumida exclusivamente por seu backend.

Além do Basic Auth, o IP de origem da requisição é validado contra a lista de IPs autorizados da sua conta. Requisições de IPs não autorizados recebem 403 Forbidden.

Para mais detalhes, consulte a página Autenticação.

Convenções da API

Valores monetários

Todos os valores monetários são representados em centavos (inteiros). Isso evita problemas de arredondamento com números decimais.

Moeda

A moeda padrão (e única suportada atualmente) é BRL (Real Brasileiro). O campo currency sempre retorna "BRL".

Formato de data e hora

Todos os timestamps utilizam o formato ISO 8601 com fuso UTC:

2026-02-15T07:09:26.615Z

IDs de transação

Todas as transações possuem um UUID v4 como identificador único:

7427a0dd-2c05-4e73-be21-b4809a77e35f

Referência externa (externalRef)

O campo externalRef permite que você associe uma transação a um identificador do seu sistema (ex: ID do pedido, número da fatura). Ele é:

• Opcional na criação de transações PIX IN
• Retornado em consultas e webhooks
• Pesquisável via GET /v1/pix-in?externalRef=pedido-123

{
  "externalRef": "pedido-123",
  "amount": 10000,
  "paymentMethod": "PIX"
}

Idempotência (Cashout)

O endpoint POST /v1/cashout suporta o campo idempotencyKey para evitar transferências duplicadas. Se uma requisição com a mesma chave já existir, a API retorna 409 Conflict com o ID da transação existente.

{
  "amount": 5000,
  "idempotencyKey": "order-456-payout",
  "pix": {
    "pixKeyType": "CPF",
    "pixKey": "12345678909"
  }
}

Formato de Requisição e Resposta

Content-Type

Todas as requisições com body (POST) devem usar Content-Type: application/json. Todas as respostas são retornadas em JSON.

Resposta de sucesso

// POST /v1/pix-in → 201 Created
{
  "id": "7427a0dd-2c05-4e73-be21-b4809a77e35f",
  "amount": 10000,
  "status": "waiting_payment",
  "pix": {
    "qrcode": "00020101021226850014br.gov.bcb.pix..."
  }
}

Resposta de erro

Todos os erros seguem o mesmo formato:

{
  "error": "ERROR_CODE",
  "message": "Descrição legível do erro."
}

Códigos de erro comuns

Taxas

As taxas são calculadas automaticamente na criação de cada transação e informadas na resposta dentro do objeto fee:

{
  "fee": {
    "totalFee": 2800,
    "netAmount": 7200
  }
}

• PIX IN: O valor líquido (netAmount) é creditado no saldo da conta
• Cashout: O valor total + taxa é debitado do saldo da conta

Webhooks

A API envia notificações automáticas via webhook sempre que o status de uma transação é atualizado. Os eventos seguem o formato {tipo}.{status}:

Para detalhes completos sobre payloads e exemplos, consulte:

• Eventos e Webhooks (PIX IN)
• Eventos e Webhooks (Cashout)

Limites

Próximos Passos

Agora que você conhece a API, siga os próximos passos para completar sua integração:

1. Autenticação — Configure suas credenciais e entenda o fluxo de segurança
2. API Reference — Explore todos os endpoints com exemplos interativos
3. Webhooks PIX IN — Configure o recebimento de notificações de pagamento
4. Webhooks Cashout — Configure o recebimento de notificações de saque

Suporte

Em caso de dúvidas sobre a integração, entre em contato com nossa equipe:

• 📧 Email: [email protected]