Vexa Pay

Esta documentação descreve como pagar boleto de terceiro com o saldo da conta através da API do Vexa Pay. Você aprenderá os pré-requisitos, como consultar o título, confirmar o pagamento e interpretar as respostas — incluindo a taxa Vexa.

Visão Geral

O fluxo de Pagar boleto liquida um título de terceiro com o saldo PIX da conta. O valor do boleto é enviado ao liquidante e a taxa Vexa é splittada automaticamente para a conta Vexa Pagamentos. Isso é diferente de POST /api/v1/boleto, que emite uma cobrança.

Endpoints: POST /api/v1/bill-payments/quote · POST /api/v1/bill-payments · GET /api/v1/bill-payments/:id

Autenticação: Bearer Token (OAuth)

Content-Type: application/json

Base URL (Produção): https://api.vexapagamentos.com.br/api/v1

Autenticação

Antes de fazer requisições, você precisa obter um token de acesso OAuth 2.0. Consulte a documentação de autenticação para mais detalhes. Não há PIN transacional na API pública: a credencial OAuth autentica a operação.

Headers necessários:

Authorization: Bearer <seu-access-token>
Content-Type: application/json

Pré-requisitos

Credenciais de API ativas: Client ID, Client Secret e API Key válidos
Token de acesso válido: obtido em /api/v1/oauth
Módulo boletos habilitado na conta
Saldo suficiente: o débito é amount_total (valor do boleto + taxa Vexa), o mesmo saldo de GET /api/v1/balance
Conta ativa: sem restrições de cash-out / pagamentos

Taxa Vexa (split)

Cada pagamento de boleto tem uma taxa configurada no catálogo Pagamento eletrônico de boleto. No processamento, a plataforma faz o split automático:

Valor do boleto (amount) — enviado ao liquidante para quitar o título
Taxa Vexa (fee) — PIX direto para a conta Vexa Pagamentos

O saldo debitado do cliente é sempre amount_total = amount + fee. Se a taxa Vexa configurada for zero, o split da taxa não é enviado. Valores nas respostas da API pública estão em reais.

Fluxo

Consulte a linha digitável ou o código de barras (quote)
Confirme com o quote_id e uma chave de idempotência
A plataforma reserva o saldo, envia o valor do boleto ao liquidante e faz o split da taxa Vexa
Consulte o status em GET /api/v1/bill-payments/:id ou receba os webhooks bill_payment.paid / bill_payment.failed

1. Consultar boleto (quote)

POST /api/v1/bill-payments/quote

Consulta o título no liquidante e devolve valor atualizado, juros, multa, vencimento e a taxa Vexa. Não reserva saldo. A cotação expira em poucos minutos.

Body (JSON)

Campo obrigatório:

barcode — linha digitável ou código de barras (com ou sem formatação)

{
  "barcode": "23793381286000000000000000000000000000000000"
}

Resposta de sucesso (200)

{
  "quote_id": "550e8400-e29b-41d4-a716-446655440000",
  "barcode": "23793381286000000000000000000000000000000000",
  "linha_digitavel": "23793381286000000000000000000000000000000000",
  "beneficiary_name": "Companhia de Energia",
  "beneficiary_document": "12345678000199",
  "amount": 150.5,
  "fee": 2.5,
  "amount_total": 153.0,
  "original_amount": 148.0,
  "interest_amount": 2.5,
  "fine_amount": 0,
  "discount_amount": 0,
  "due_date": "2026-12-31",
  "provider": "onz",
  "status": "ACTIVE",
  "expires_at": "2026-08-18T12:10:00.000Z"
}

2. Confirmar pagamento

POST /api/v1/bill-payments

Reserva amount_total e enfileira a liquidação. Envie o header Idempotency-Key ou o campo idempotency_key no corpo.

Body (JSON)

Campos:

quote_id — ID retornado no quote (obrigatório)
idempotency_key — opcional se o header Idempotency-Key for enviado

{
  "quote_id": "550e8400-e29b-41d4-a716-446655440000",
  "idempotency_key": "pedido-9981-boleto"
}

Resposta de sucesso (200)

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "quote_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING_QUEUE",
  "amount": 150.5,
  "fee": 2.5,
  "amount_total": 153.0,
  "barcode": "23793381286000000000000000000000000000000000",
  "linha_digitavel": "23793381286000000000000000000000000000000000",
  "provider": "onz",
  "provider_transaction_id": null,
  "funding_status": null,
  "fee_sweep_status": null,
  "reserved_at": "2026-08-18T12:05:01.000Z",
  "paid_at": null,
  "created_at": "2026-08-18T12:05:01.000Z"
}

Status comuns: PENDING_QUEUE, SENT_TO_PROVIDER (PIX em processamento), PAID, FAILED.

3. Consultar pagamento

GET /api/v1/bill-payments/:id

Use o id retornado na confirmação. O corpo segue o mesmo formato do POST.

Path:

id — UUID do pagamento

Erros comuns

HTTP	Quando
400	Linha digitável inválida ou quote expirada
402	Saldo insuficiente para `amount_total`
404	Boleto ou pagamento não encontrado

Webhooks

Após a confirmação a API dispara bill_payment.created. O resultado assíncrono chega em bill_payment.paid ou bill_payment.failed. Veja a página de Webhooks para cabeçalhos e assinatura.