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:

Credenciais de acesso (clientId e clientSecret) — fornecidas no cadastro da sua conta
URL de webhook configurada — para receber notificações de status em tempo real
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

Ambiente	URL Base
Produção	`https://api.voidxpay.com/v1`

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.

Endpoint	Descrição
`POST /v1/pix-in`	Gera um QR Code PIX para recebimento
`GET /v1/pix-in`	Consulta uma transação por `id` ou `externalRef`

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.

Endpoint	Descrição
`POST /v1/cashout`	Cria uma transferência PIX para a chave de destino
`GET /v1/cashout`	Consulta uma transação por `id` ou `reference` (end-to-end)

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.

Endpoint	Descrição
`GET /v1/balance`	Retorna o saldo atual em centavos

Webhooks

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

Endpoint	Descrição
`GET /v1/webhooks`	Consulta o histórico de webhooks por transação

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.

Valor Real	Valor em centavos	Campo JSON
R$ 1,00	`100`	`"amount": 100`
R$ 50,00	`5000`	`"amount": 5000`
R$ 100,00	`10000`	`"amount": 10000`
R$ 1.250,99	`125099`	`"amount": 125099`

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

HTTP Status	Código	Descrição
`400`	`INVALID_REQUEST`	Dados inválidos no payload da requisição
`400`	`VALIDATION_ERROR`	Erro de validação em campos específicos
`400`	`INSUFFICIENT_BALANCE`	Saldo insuficiente para a operação
`401`	`INVALID_CREDENTIALS`	Credenciais ausentes ou inválidas
`403`	`IP_NOT_ALLOWED`	IP de origem não autorizado
`403`	`USER_INACTIVE`	Usuário inativo ou suspenso
`403`	`ACCOUNT_INACTIVE`	Conta inativa ou suspensa
`404`	`TRANSACTION_NOT_FOUND`	Transação não encontrada
`409`	`DUPLICATE_REQUEST`	Requisição duplicada (idempotencyKey)
`500`	`INTERNAL_ERROR`	Erro interno do servidor
`502`	`PROCESSING_ERROR`	Falha no processamento do pagamento

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
  }
}

Campo	Descrição
`totalFee`	Taxa total cobrada em centavos
`netAmount`	Valor líquido em centavos (`amount - totalFee`)

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}:

Tipo	Exemplo de eventos
PIX IN	`pix-in.waiting_payment`, `pix-in.paid`, `pix-in.expired`, `pix-in.refunded`
Cashout	`cashout.pending`, `cashout.processing`, `cashout.completed`, `cashout.failed`

Para detalhes completos sobre payloads e exemplos, consulte:

Limites

Recurso	Limite
Requisições por segundo	10.000 req/s
Burst máximo	5.000 requisições
Valor mínimo PIX IN	R$ 1,00 (100 centavos)
Valor mínimo Cashout	R$ 0,01 (1 centavo)
Descrição do pagamento	500 caracteres
Informação adicional PIX	140 caracteres
URLs de webhook por conta	Até 10
Histórico de webhooks	Até 100 por consulta
Timeout de resposta	29 segundos

Próximos Passos

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

Autenticação — Configure suas credenciais e entenda o fluxo de segurança
API Reference — Explore todos os endpoints com exemplos interativos
Webhooks PIX IN — Configure o recebimento de notificações de pagamento
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: suporte@voidxpay.com