Bravive — Portal

Início — credenciais e autenticação

Todas as rotas públicas da API v1 exigem o header Authorization. O valor não é um JWT: você envia um token fixo derivado do par Client ID + Secret gerados no Developer Hub.

Formato do Bearer

Concatene clientId, dois-pontos e secret.
Codifique em Base64 (standard, sem quebras de linha).
Envie Authorization: Bearer <base64>.

Base URL

…

Mesmo domínio desta página + /api/v1.

Obter credenciais

No Developer Hub, gere ou copie Client ID e Secret.

Montar o token

Buffer.from(clientId + ':' + secret).toString('base64')

Chamar a API

Header Authorization: Bearer <base64> em todas as requisições.

Exemplo (fetch)

const token = Buffer.from(`${clientId}:${secret}`).toString("base64");

await fetch(`${window.location.origin}/api/v1/balance`, {
  headers: { Authorization: `Bearer ${token}` },
});

PIX

Transferencias, cobranca por QR Code e consulta de chave PIX.

POST/api/v1/pix/sendwebhookidempotente

Envia um PIX para uma chave (CPF, CNPJ, email, telefone ou EVP).

Suporta webhookUrl inline — passe uma URL HTTPS no body para receber o callback desta operação específica, independente do webhook cadastrado no painel.

Suporta idempotencyKey — gere um UUID antes de enviar e reutilize-o em retries. O servidor retorna o registro já existente sem criar duplicatas nem debitar novamente.

Request

{ key: string; amount: number; description?: string; webhookUrl?: string; idempotencyKey?: string }

Campos de Request

Campo

Tipo

Obrigatorio

Descricao

key

string

Sim

Chave PIX de destino.

amount

number

Sim

Valor em centavos.

description

string

Nao

Descricao da transferencia no extrato.

webhookUrl

string

Nao

URL HTTPS para receber o callback desta operação. Substitui o webhook cadastrado para esta requisição.

idempotencyKey

string

Nao

Chave de idempotência (máx. 64 chars). Se enviada em um retry, o servidor retorna o registro já criado sem criar um novo nem debitar novamente.

Exemplo de Request

{
  "key": "[email protected]",
  "amount": 15990,
  "description": "Pagamento de servico",
  "webhookUrl": "https://meusite.com/webhooks/pix"
}

Response 200

{ id: string; status: "pending" | "processing" }

Exemplo de Response

{
  "id": "pix_01JABCDEF12345",
  "status": "pending"
}

POST/api/v1/pix/qrcodewebhookidempotente

Gera uma cobranca PIX com retorno de payload EMV e imagem QR em base64.

Suporta webhookUrl inline — passe uma URL HTTPS no body para receber o callback desta operação específica, independente do webhook cadastrado no painel.

Suporta idempotencyKey — gere um UUID antes de enviar e reutilize-o em retries. O servidor retorna o registro já existente sem criar duplicatas nem debitar novamente.

Request

{ amount: number; description?: string; split?: SplitItem[]; webhookUrl?: string; idempotencyKey?: string }

Campos de Request

Campo

Tipo

Obrigatorio

Descricao

amount

number

Sim

Valor em centavos. Use 0 para QR aberto.

description

string

Nao

Descricao opcional da cobranca.

split

SplitItem[]

Nao

Lista de repasses automáticos ao confirmar o pagamento. Máx. 10 itens. A soma dos amounts não pode exceder o valor líquido (após taxa). Veja a seção Splits.

split[].recipientId

string

Sim

ID público do destinatário (prefixo rec_), obtido ao ativar split receiving na conta.

split[].amount

number

Sim

Valor a repassar em centavos.

split[].description

string

Nao

Descrição do repasse (máx. 140 chars).

webhookUrl

string

Nao

URL HTTPS para receber o callback desta operação. Substitui o webhook cadastrado para esta requisição.

idempotencyKey

string

Nao

Chave de idempotência (máx. 64 chars). Se enviada em um retry, o servidor retorna o registro já criado sem criar um novo nem debitar novamente.

Exemplo de Request

{
  "amount": 19990,
  "description": "Cobranca de pedido #123",
  "split": [
    { "recipientId": "rec_abc123", "amount": 5000, "description": "Comissao vendedor" }
  ],
  "webhookUrl": "https://meusite.com/webhooks/pagamento"
}

Response 200

{ id: string; code: string; qrcode: string } — `id` = UUID do pagamento (igual ao webhook `payment`).

Exemplo de Response

{
  "id": "f112f47f-bd7a-4801-af57-44a058f10864",
  "code": "00020126580014BR.GOV.BCB.PIX...",
  "qrcode": "iVBORw0KGgoAAAANSUhEUgAA..."
}

amount: 0 = QR aberto
code=EMV, qrcode=base64 PNG
`id` = UUID do pagamento (mesmo valor no webhook `payment`).

GET/api/v1/pix/info/:key

Consulta dados do favorecido pela chave PIX informada.

Response 200

{ name: string; taxNumber: string; bank: string; institution: string }

Exemplo de Response

{
  "name": "Maria Santos",
  "taxNumber": "***.123.***-**",
  "bank": "033",
  "institution": "Banco Santander"
}

TED

TED para conta de terceiros; mesmo fluxo de aprovação que o PIX out (admin ou auto-approve).

POST/api/v1/ted/sendwebhookidempotente

Cria saque TED pendente (centavos). O envio à instituição ocorre após aprovação, como no PIX out.

Suporta webhookUrl inline — passe uma URL HTTPS no body para receber o callback desta operação específica, independente do webhook cadastrado no painel.

Suporta idempotencyKey — gere um UUID antes de enviar e reutilize-o em retries. O servidor retorna o registro já existente sem criar duplicatas nem debitar novamente.

Request

{ amount: number; to: { name: string; taxNumber: string; bank: string; branch: string; account: string; accountDigit: string; accountType: "checking" | "savings" }; description?: string; scheduleDate?: string; webhookUrl?: string; idempotencyKey?: string }

Campos de Request

Campo

Tipo

Obrigatorio

Descricao

amount

number

Sim

Valor em centavos.

to.name

string

Sim

Nome do favorecido.

to.taxNumber

string

Sim

CPF ou CNPJ do favorecido.

to.bank

string

Sim

Codigo COMPE do banco (3 digitos, ex.: 033).

to.branch

string

Sim

Agencia bancaria.

to.account

string

Sim

Numero da conta sem digito.

to.accountDigit

string

Sim

Digito da conta.

to.accountType

"checking" | "savings"

Sim

Tipo da conta.

description

string

Nao

Descricao da TED.

scheduleDate

string

Nao

Nao suportado — se enviado, a API responde erro. Omita o campo.

webhookUrl

string

Nao

URL HTTPS para receber o callback desta operação. Substitui o webhook cadastrado para esta requisição.

idempotencyKey

string

Nao

Chave de idempotência (máx. 64 chars). Se enviada em um retry, o servidor retorna o registro já criado sem criar um novo nem debitar novamente.

Exemplo de Request

{
  "amount": 289900,
  "to": {
    "name": "Fornecedor XPTO LTDA",
    "taxNumber": "12345678000199",
    "bank": "033",
    "branch": "0001",
    "account": "123456",
    "accountDigit": "7",
    "accountType": "checking"
  },
  "webhookUrl": "https://meusite.com/webhooks/ted"
}

Response 200

{ id: string; status: "pending" }

Exemplo de Response

{
  "id": "f112f47f-bd7a-4801-af57-44a058f10864",
  "status": "pending"
}

`id` = UUID do saque (mesmo `id` no webhook `withdrawal`).
Agendamento (`scheduleDate`) não é suportado.

BOLETO

Geracao e consulta de boletos com multa, juros e desconto.

POST/api/v1/boleto/generatewebhookidempotente

Gera boleto com pagador, vencimento e regras opcionais de multa/juros/desconto.

Suporta webhookUrl inline — passe uma URL HTTPS no body para receber o callback desta operação específica, independente do webhook cadastrado no painel.

Suporta idempotencyKey — gere um UUID antes de enviar e reutilize-o em retries. O servidor retorna o registro já existente sem criar duplicatas nem debitar novamente.

Request

{ amount: number; dueDate: string; customer: { name: string; taxNumber: string; email: string; phone?: string; address: { street: string; city: string; state: string; zipCode: string } }; description?: string; webhookUrl?: string; idempotencyKey?: string }

Campos de Request

Campo

Tipo

Obrigatorio

Descricao

amount

number

Sim

Valor em centavos.

dueDate

string

Sim

Data de vencimento em ISO 8601.

customer.name

string

Sim

Nome do pagador.

customer.taxNumber

string

Sim

CPF ou CNPJ do pagador.

customer.email

string

Sim

Email para envio do boleto.

customer.address.street

string

Sim

Logradouro.

customer.address.city

string

Sim

Cidade.

customer.address.state

string

Sim

UF com 2 letras.

customer.address.zipCode

string

Sim

CEP.

description

string

Nao

Descricao da cobranca.

webhookUrl

string

Nao

URL HTTPS para receber o callback desta operação. Substitui o webhook cadastrado para esta requisição.

idempotencyKey

string

Nao

Chave de idempotência (máx. 64 chars). Se enviada em um retry, o servidor retorna o registro já criado sem criar um novo nem debitar novamente.

Exemplo de Request

{
  "amount": 19990,
  "dueDate": "2026-04-15",
  "customer": {
    "name": "Joao Silva",
    "taxNumber": "12345678909",
    "email": "[email protected]",
    "address": { "street": "Rua A, 123", "city": "Sao Paulo", "state": "SP", "zipCode": "01001000" }
  },
  "webhookUrl": "https://meusite.com/webhooks/boleto"
}

Response 200

{ id: string; barcode: string; digitableLine: string; pdfUrl: string; dueDate: string; amount: number }

Exemplo de Response

{
  "id": "bol_01JABCDE123",
  "barcode": "23793381286000300004509000123456781234567890",
  "digitableLine": "23790.90001 23456.781234 56789.012345 6 00030000450000",
  "pdfUrl": "https://api.bravive.com/boletos/bol_01JABCDE123.pdf",
  "dueDate": "2026-04-15",
  "amount": 19990
}

GET/api/v1/boleto/:id

Retorna os dados e status atual de um boleto pelo ID.

Response 200

{ id: string; status: "pending" | "paid" | "expired" | "cancelled"; amount: number; paidAmount?: number; paidAt?: string; dueDate: string; barcode: string; pdfUrl: string }

Exemplo de Response

{
  "id": "bol_01JABCDE123",
  "status": "paid",
  "amount": 19990,
  "paidAmount": 19990,
  "paidAt": "2026-04-14T11:20:10.000Z",
  "dueDate": "2026-04-15"
}

SALDO E EXTRATO

Consulta de saldo disponivel, pagamentos e saques.

GET/api/v1/balance

Consulta saldo disponivel e saldo bloqueado da conta.

Response 200

{ available: number; blocked: number }

Exemplo de Response

{
  "available": 1567430,
  "blocked": 50000
}

Valores em centavos

GET/api/v1/payments

Lista pagamentos com filtros por periodo/metodo/status e paginacao por cursor.

Query Params

?from=2024-01-01&to=2024-01-31&method=pix|boleto|card|crypto&status=paid|pending&limit=50&cursor=xxx

Campos de Query

Campo

Tipo

Obrigatorio

Descricao

from

string

Nao

Data inicial (YYYY-MM-DD).

string

Nao

Data final (YYYY-MM-DD).

method

string

Nao

Método: pix, boleto, card, crypto.

status

string

Nao

Status: pending, paid, failed, cancelled, expired, refunded.

limit

number

Nao

Maximo de itens por pagina.

cursor

string

Nao

Cursor de paginacao.

Response 200

{ data: Payment[]; nextCursor?: string }

Exemplo de Response

{
  "data": [
    {
      "id": "pay_01JABCDE",
      "method": "pix",
      "status": "paid",
      "amount": 1200,
      "fee": 50,
      "payerName": "João Silva",
      "payerDocument": "12345678909",
      "description": "Pagamento de teste",
      "pixCopyPaste": "000201...",
      "createdAt": "2026-03-27T12:00:00.000Z"
    }
  ],
  "nextCursor": "pay_01JABCDE"
}

Paginacao por cursor

GET/api/v1/payments/:id

Retorna o detalhe de um pagamento especifico.

Response 200

Payment

Exemplo de Response

{
  "id": "pay_01JABCDE",
  "method": "pix",
  "status": "paid",
  "amount": 1200,
  "fee": 50,
  "payerName": "João Silva",
  "payerDocument": "12345678909",
  "description": "Pagamento de teste",
  "pixCopyPaste": "000201...",
  "createdAt": "2026-03-27T12:00:00.000Z"
}

GET/api/v1/withdrawals

Lista saques com filtros por periodo/metodo/status e paginacao por cursor.

Query Params

?from=2024-01-01&to=2024-01-31&method=pix|ted&status=completed|pending&limit=50&cursor=xxx

Campos de Query

Campo

Tipo

Obrigatorio

Descricao

from

string

Nao

Data inicial (YYYY-MM-DD).

string

Nao

Data final (YYYY-MM-DD).

method

string

Nao

Método: pix, ted.

status

string

Nao

Status: pending, processing, completed, failed, cancelled.

limit

number

Nao

Maximo de itens por pagina.

cursor

string

Nao

Cursor de paginacao.

Response 200

{ data: Withdrawal[]; nextCursor?: string }

Exemplo de Response

{
  "data": [
    {
      "id": "wth_01JABCDE",
      "method": "pix",
      "status": "completed",
      "amount": 10000,
      "fee": 100,
      "pixKey": "[email protected]",
      "pixKeyType": "email",
      "accountHolderName": "Maria Souza",
      "document": "98765432100",
      "description": "Saque PIX",
      "createdAt": "2026-03-27T12:00:00.000Z"
    }
  ],
  "nextCursor": "wth_01JABCDE"
}

Paginacao por cursor

GET/api/v1/withdrawals/:id

Retorna o detalhe de um saque especifico.

Response 200

Withdrawal

Exemplo de Response

{
  "id": "wth_01JABCDE",
  "method": "pix",
  "status": "completed",
  "amount": 10000,
  "fee": 100,
  "pixKey": "[email protected]",
  "pixKeyType": "email",
  "accountHolderName": "Maria Souza",
  "document": "98765432100",
  "description": "Saque PIX",
  "createdAt": "2026-03-27T12:00:00.000Z"
}

CARTÃO (LINK / IFRAME)

Cobrança no cartão em checkout hospedado, com 3D Secure, antifraude e parcelamento. Pode ser aberto em nova aba ou embutido em iframe.

POST/api/v1/card/link

Cria uma cobrança no cartão e devolve a URL do checkout (`url`) e a URL para iframe (`embedUrl`). O cartão é digitado no checkout da Bravive: o número nunca passa pelo seu servidor.

Request

{ amount: number; title: string; description?: string; expiresInDays?: number; maxInstallments?: number; acceptPix?: boolean; payer?: { name: string; email: string; document: string }; embedOrigin?: string }

Campos de Request

Campo

Tipo

Obrigatorio

Descricao

amount

number

Sim

Valor em centavos (ex: 15000 = R$ 150,00).

title

string

Sim

Nome do produto ou serviço (máx. 120 chars). Também é usado como descritor na fatura.

description

string

Nao

Descrição adicional (máx. 140 chars).

expiresInDays

number

Nao

Validade do link em dias (padrão 7, máx. 30).

maxInstallments

number

Nao

Teto de parcelas desta cobrança. O limite real ainda respeita as regras da conta e do tenant.

acceptPix

boolean

Nao

Se true, o checkout também oferece PIX. Padrão: false (somente cartão).

payer

object

Nao

{ name, email, document }. Se enviado, o checkout pula a etapa 'Seus dados' e vai direto ao cartão.

embedOrigin

string

Nao

Origem do seu site que vai embutir o iframe (ex: https://loja.com). Habilita o aviso por postMessage. Obrigatório para receber o evento.

Exemplo de Request

{
  "amount": 15000,
  "title": "Plano Pro",
  "expiresInDays": 3,
  "maxInstallments": 3,
  "payer": {
    "name": "João Silva",
    "email": "[email protected]",
    "document": "12345678909"
  },
  "embedOrigin": "https://loja.com"
}

Response 200

{ id: string; url: string; embedUrl: string; amount: number; expiresAt: string }

Exemplo de Response

{
  "id": "e4a2c10b-5f12-4e09-8b01-a2bc3d4e5f67",
  "url": "https://pay.suaplataforma.com/pay/Ab3xK9...",
  "embedUrl": "https://pay.suaplataforma.com/pay/Ab3xK9...?embed=1&origin=https%3A%2F%2Floja.com",
  "amount": 15000,
  "expiresAt": "2026-10-15T18:00:00.000Z"
}

Disponível apenas para contas com cartão habilitado (Marlim configurada no tenant e chave PIX ativa na conta). Caso contrário retorna PRECONDITION_FAILED.
IFRAME: use `embedUrl` como `src`. Ex: <iframe src="{embedUrl}" style="width:100%;max-width:440px;height:760px;border:0" allow="payment"></iframe>. O modo embed mostra só o formulário de pagamento, sem o painel de resumo.
EVENTO: ao concluir, o iframe envia ao seu site (apenas para a origem informada em `embedOrigin`) `{ type: 'bravive:payment', status: 'paid' | 'review', token }`. `review` = antifraude analisando; o cartão já foi cobrado, NÃO ofereça nova tentativa.
Ouça com: window.addEventListener('message', (e) => { if (e.origin !== 'https://pay.suaplataforma.com') return; if (e.data?.type === 'bravive:payment') { /* ... */ } }). Sempre valide `e.origin` com o domínio do checkout.
O postMessage é só uma conveniência de tela. Confirme o pagamento no seu backend com GET /payments/:id (status 'paid') ou pelo webhook de payment antes de liberar o produto.
Se `embedOrigin` não for enviado, nenhum evento é emitido. O link também funciona normalmente aberto em nova aba (`url`).

CRIPTO (SOLANA PAY)

Cobranças em USDT, USDC (SPL Tokens) e SOL nativo na Solana, sem conversão cambial.

POST/api/v1/crypto/chargewebhookidempotente

Gera uma cobrança em USDT, USDC (SPL Tokens) ou SOL nativo na rede Solana com URL padrão Solana Pay e QR Code.

Suporta webhookUrl inline — passe uma URL HTTPS no body para receber o callback desta operação específica, independente do webhook cadastrado no painel.

Suporta idempotencyKey — gere um UUID antes de enviar e reutilize-o em retries. O servidor retorna o registro já existente sem criar duplicatas nem debitar novamente.

Request

{ amount: number | string; currency?: 'usdt_sol' | 'usdc_sol' | 'sol'; title?: string; description?: string; payerName?: string; payerEmail?: string; payerDocument?: string; webhookUrl?: string; idempotencyKey?: string; expiresInMinutes?: number }

Campos de Request

Campo

Tipo

Obrigatorio

Descricao

amount

number | string

Sim

Valor nominal da criptomoeda (ex: 15.50 para USDT/USDC ou 0.25 para SOL).

currency

string

Nao

Ativo: 'usdt_sol' (Tether USD), 'usdc_sol' (USD Coin) ou 'sol' (Solana Nativo). Padrão: 'usdt_sol'.

title

string

Nao

Título do produto ou serviço (máx. 120 chars).

description

string

Nao

Descrição adicional da cobrança (máx. 140 chars).

payerName

string

Nao

Nome do pagador.

payerEmail

string

Nao

E-mail do pagador.

payerDocument

string

Nao

CPF ou CNPJ do pagador.

expiresInMinutes

number

Nao

Tempo de expiração em minutos (padrão: 1440 = 24h, mín: 5, máx: 10080).

webhookUrl

string

Nao

URL HTTPS para receber o callback desta operação. Substitui o webhook cadastrado para esta requisição.

idempotencyKey

string

Nao

Chave de idempotência (máx. 64 chars). Se enviada em um retry, o servidor retorna o registro já criado sem criar um novo nem debitar novamente.

Exemplo de Request

{
  "amount": "15.00",
  "currency": "usdt_sol",
  "title": "Licença Software",
  "description": "Assinatura mensal",
  "webhookUrl": "https://meusite.com/webhooks/crypto"
}

Response 200

{ id: string; status: 'pending'; currency: 'usdt_sol' | 'usdc_sol' | 'sol'; cryptoAmount: string; cryptoAmountRaw: string; fee: string; recipientAddress: string; reference: string; solanaPayUrl: string; qrCode: string; expiresAt: string }

Exemplo de Response

{
  "id": "e4a2c10b-5f12-4e09-8b01-a2bc3d4e5f67",
  "status": "pending",
  "currency": "usdt_sol",
  "cryptoAmount": "15.000000",
  "cryptoAmountRaw": "15000000",
  "fee": "0.150000",
  "recipientAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "reference": "9zW1kRt9oP2mNx...",
  "solanaPayUrl": "solana:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU?amount=15.000000&spl-token=Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB&reference=9zW1kRt9oP2mNx...",
  "qrCode": "data:image/png;base64,iVBORw0KGgo...",
  "expiresAt": "2026-09-23T18:00:00.000Z"
}

100% nativo: sem conversão cambial para Real ou oráculos de preço.
O campo `qrCode` retorna uma imagem PNG pronta em base64 com a URL Solana Pay.
O campo `reference` é uma chave pública única efêmera monitorada on-chain para liquidação automática.

GET/api/v1/crypto/charge/:id

Consulta o status de uma cobrança cripto com verificação on-chain em tempo real na Solana.

Response 200

{ id: string; status: 'pending' | 'paid' | 'expired' | 'canceled' | 'failed'; cryptoStatus: string | null; currency: string; cryptoAmount: string; recipientAddress: string; reference: string | null; txSignature: string | null; slot: number | null; explorerUrl: string | null; paidAt: string | null; expiresAt: string | null; createdAt: string }

Exemplo de Response

{
  "id": "e4a2c10b-5f12-4e09-8b01-a2bc3d4e5f67",
  "status": "paid",
  "cryptoStatus": "finalized",
  "currency": "usdt_sol",
  "cryptoAmount": "15.000000",
  "cryptoAmountRaw": "15000000",
  "recipientAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "reference": "9zW1kRt9oP2mNx...",
  "txSignature": "5wKzN7...v3yP",
  "slot": 298471920,
  "explorerUrl": "https://solscan.io/tx/5wKzN7...v3yP",
  "paidAt": "2026-09-22T18:15:32.000Z",
  "expiresAt": "2026-09-23T18:00:00.000Z",
  "createdAt": "2026-09-22T18:00:00.000Z"
}

Quando chamada enquanto pendente, verifica automaticamente na blockchain se a transação foi confirmada.
`explorerUrl` fornece o link direto para visualização pública no Solscan.

SPLITS DE PAGAMENTO

Repasse automático de parte do valor recebido para contas de sub-merchants.

O split permite que, ao confirmar um pagamento PIX, parte do valor seja automaticamente repassada para uma ou mais contas cadastradas na plataforma. Ideal para marketplaces, plataformas e modelos de comissão.

Ativar conta receptora

A conta destino deve ter split receiving habilitado no painel. Ao ativar, ela recebe um recipient_id com prefixo rec_.

Criar cobrança com split

Passe o campo split[] em POST /pix/qrcode com recipientId, amount e description opcional.

Confirmação automática

Ao confirmar o pagamento, o sistema executa o repasse e credita o saldo na conta receptora.

Regras e limites

Máximo de 10 splits por pagamento.
A soma de todos os amounts não pode exceder o valor líquido do pagamento (valor total menos a taxa transacional).
O recipientId deve estar com split receiving ativo.
O repasse é processado após confirmação do pagamento. Em caso de falha, o sistema realiza até 5 tentativas com backoff exponencial.
O saldo do recipient é creditado somente após confirmação do repasse pelo sistema.

Exemplo — cobrança de R$ 199,90 com split de R$ 50,00

POST /api/v1/pix/qrcode

{
  "amount": 19990,
  "description": "Pedido #4521",
  "split": [
    {
      "recipientId": "rec_abc123def456",
      "amount": 5000,
      "description": "Comissao do vendedor"
    }
  ],
  "webhookUrl": "https://meusite.com/webhooks/pagamento"
}

Campos do objeto split[]

Campo

Tipo

Obrigatório

Descrição

recipientId

string

Sim

ID público da conta receptora (prefixo rec_).

amount

number

Sim

Valor em centavos a repassar.

description

string

Não

Descrição do repasse (máx. 140 chars).

Status do split (interno)

Status

Significado

pending

Criado junto com o pagamento; aguardando confirmação do pagamento.

processing

Repasse em processamento; aguardando confirmação.

sent

Repasse confirmado; saldo creditado na conta receptora.

failed

Falhou após todas as tentativas; aguarda intervenção manual.

skipped

Conta receptora desativou split receiving ou dados inválidos.

WEBHOOKS

Pagamentos e saques (mudanças de status) mais movimentações de conta.

Cadastrar Webhook

Webhook global

Cadastre uma URL no painel de webhooks. Todos os eventos do tipo selecionado serão enviados para ela automaticamente.

Webhook inline

Passe webhookUrl no body de qualquer requisição marcada com webhook. O callback desta operação vai para essa URL, independente do webhook global.

Transporte HTTP

POST na URL configurada, corpo JSON, header Content-Type: application/json.

Validação de segredo

O header X-Webhook-Secret vale o mesmo que o cadastro quando o disparo vai para uma URL registrada em webhooks. Quando apenas webhookUrl inline é usada (sem registro próprio na fila webhooks), o segredo pode ser o webhook secret cadastrado, se estiver configurado; caso não haja segredo configurado em nenhuma das pontas, o header pode ficar omitido (receptor não deve conferir contra string vazia).

// Validação (Node.js)
const secret = req.headers["x-webhook-secret"];
if (secret !== process.env.WEBHOOK_SECRET) {
  return res.status(401).end();
}

Estrutura do payload raiz

O servidor monta sempre { event, …campos específicos, occurredAt }. Os campos após event dependem do tipo (veja exemplos nos separadores).

Campo

Tipo

Descrição

event

"payment" | "withdrawal" | "account_movement"

Nome do tipo de webhook.

occurredAt

string (ISO 8601)

Gerado quando o sistema enfileira a entrega (UTC).

string (UUID)

Só em payment e withdrawal: ID Bravive do recurso (pagamento ou saque), não um "id de disparo".

previousStatus

string

Só payment/withdrawal: estado anterior à transição notificada.

status

string

Só payment/withdrawal: novo estado do recurso após a transição.

method

string

Só payment: ex.: "pix", "boleto".

amount

number (centavos)

Payment e withdrawal.

endToEndId

string | null

Só withdrawal, opcional: presente em alguns fluxos (ex.: após PIX out).

movement

object

Só account_movement: detalhes do movimento; formato varia conforme o tipo (PixIn, PixOut, etc.).

Tipos de evento

No cadastro global você escolhe um ou mais tipos. Para payment e withdrawal, cada envio reflete uma transição de status; já account_movement repassa movimentações recebidas do provedor.

Cobrança (PIX, boleto, etc.) na conta: disparado quando o status **mudou** (`previousStatus` → `status`). O `id` é o UUID do pagamento na Bravive — o mesmo retornado em `POST /pix/qrcode` e `POST /boleto/generate`.

O webhook não é disparado periodicamente só por existir o status; apenas na transição. Os valores possíveis de status seguem o modelo de cobrança.

Status do recurso (payment / withdrawal)

Status

Descrição

pending

Aguardando pagamento

paid

Pago e confirmado

expired

Expirou sem pagamento

canceled

Cancelado

reversed

Estornado

failed

Falhou

Exemplo de payload

{
  "event": "payment",
  "id": "f112f47f-bd7a-4801-af57-44a058f10864",
  "previousStatus": "pending",
  "status": "paid",
  "method": "pix",
  "amount": 100,
  "occurredAt": "2026-05-12T22:53:35.414Z"
}

Responda rápido

Retorne HTTP 200 imediatamente e processe o payload de forma assíncrona.

Idempotência

Reenvios podem repetir o mesmo estado. Dedupe usando o id do recurso (payment/withdrawal) em conjunto com status e occurredAt quando necessário.

Somente HTTPS

Endpoints HTTP sem TLS são rejeitados — tanto no cadastro quanto no inline.

Timeout ~15 s

Requisição com timeout de 15 s; falha de rede ou status HTTP não 2xx agendam retentativa (backoff).

Convencoes Gerais

Autenticação: Authorization: Bearer <base64(clientId:secret)>(veja Início). Valores monetários em centavos, datas em ISO 8601, erros no formato { error: string; code: string } e taxNumber mascarado nas respostas.

API Documentation

Arquivo llm.txt

Início — credenciais e autenticação

PIX

TED

BOLETO

SALDO E EXTRATO

CARTÃO (LINK / IFRAME)

CRIPTO (SOLANA PAY)

SPLITS DE PAGAMENTO

WEBHOOKS