Pra agentes de IA
Esta documentação é otimizada para LLMs. Cada endpoint tem request/response COMPLETOS, sem omissões. Use os exemplos cURL como ponto de partida para geração de SDK em qualquer linguagem. O servidor responde JSON (UTF-8). Não há paginação por offset; use cursor nos endpoints de listagem.
Resumo rápido
| Base URL | https://bravopay.club/api/v1 |
| Auth | Authorization: Bearer bp_live_... |
| Content-Type | application/json |
| Encoding | UTF-8 |
| Rate limit | 60 req/min por chave |
| Idempotência | Header Idempotency-Key em POST |
| Webhook | HMAC-SHA256 no header X-Bravopay-Signature |
Autenticação
Toda chamada requer uma chave de API no header Authorization com esquema Bearer.
Gere a chave em Dashboard → API Keys. A chave começa com bp_live_ e aparece UMA VEZ — copie e guarde.
curl https://bravopay.club/api/v1/me \
-H "Authorization: Bearer bp_live_seu_token"Resposta 401 quando o token é inválido. Resposta 429 com header Retry-After quando excede o rate limit.
Formato de erro
Erros sempre vêm com este formato. Use o campo error.code pra branching no código (estável); o error.message é pra humanos.
{
"error": {
"code": "validation_error",
"message": "One or more fields are invalid",
"details": { "amount_cents": ["amount_cents min R$5,00 (500 cents)"] }
}
}Códigos comuns
| unauthorized | 401 · Token ausente, inválido ou expirado |
| forbidden | 403 · Token válido mas sem permissão pro recurso |
| validation_error | 422 · Campo com formato/valor inválido (veja details) |
| product_not_found | 404 · product_id não pertence à conta |
| product_inactive | 422 · Produto existe mas está desativado |
| rate_limited | 429 · Excedeu 60 req/min (veja header Retry-After) |
| acquirer_error | 502 · O adquirente (Stripe/SafePix/MP) falhou; veja details.attempts |
| internal_error | 500 · Bug servidor; reportar ao suporte |
POST /transactions — Criar cobrança
Endpoint principal. Cria uma cobrança (PIX ou cartão) sem precisar de produto/checkout pré-cadastrado. A maioria dos casos cabe aqui.
/transactionsCria PIX ou cobrança de cartão. Retorna copy-paste do PIX ou URL hospedada do cartão.
Request body (JSON)
| Campo | Tipo | Descrição |
|---|---|---|
amount_cents | integer (req) | Valor em centavos. Mínimo 500 (R$ 5,00). |
method | "pix" | "card" | Default "pix". Ambos permitidos sem product_id. |
customer.email | string | Email do cliente. Default gerado automaticamente. |
customer.name | string | Nome do cliente. |
customer.cpf | string | CPF/CNPJ (com ou sem máscara). |
customer.phone | string | Telefone (E.164 ou formato BR). |
product_id | string | ID do produto. Opcional. Sem ele usa produto interno "ghost". |
description | string | Texto livre que aparece no extrato/recibo. Max 300 chars. |
external_reference | string | Seu ID interno pra correlacionar. Max 120 chars. |
expires_in | integer | Segundos até expirar (PIX). 60-86400. Default 3600. |
utm.source | string | UTM tracking. |
utm.medium | string | UTM tracking. |
utm.campaign | string | UTM tracking. |
utm.content | string | UTM tracking. |
utm.term | string | UTM tracking. |
utm.fbclid | string | Facebook click ID. |
utm.gclid | string | Google click ID. |
utm.ttclid | string | TikTok click ID. |
Exemplo cURL — PIX simples
curl -X POST https://bravopay.club/api/v1/transactions \
-H "Authorization: Bearer bp_live_seu_token" \
-H "Content-Type: application/json" \
-d '{
"amount_cents": 1990,
"method": "pix",
"customer": {
"email": "joao@example.com",
"name": "João Silva",
"cpf": "11144477735"
},
"description": "Mensalidade Plano Pro",
"external_reference": "order_42"
}'Resposta sucesso (PIX) · HTTP 200
{
"id": "tx_clxabc123",
"object": "transaction",
"status": "PENDING",
"method": "PIX",
"amount_cents": 1990,
"fee_cents": 449,
"net_cents": 1541,
"currency": "BRL",
"pix": {
"copy_paste": "00020126580014BR.GOV.BCB.PIX...",
"expires_at": "2026-06-01T16:30:00.000Z"
},
"created_at": "2026-06-01T15:30:00.000Z"
}Exemplo cURL — Cartão
curl -X POST https://bravopay.club/api/v1/transactions \
-H "Authorization: Bearer bp_live_seu_token" \
-H "Content-Type: application/json" \
-d '{
"amount_cents": 9990,
"method": "card",
"customer": {
"email": "maria@example.com",
"name": "Maria Souza",
"cpf": "52998224725"
},
"description": "Curso Premium"
}'Resposta sucesso (CARD) · HTTP 200
{
"id": "tx_clxdef456",
"object": "transaction",
"status": "PENDING",
"method": "CARD",
"amount_cents": 9990,
"fee_cents": 1349,
"net_cents": 8641,
"currency": "BRL",
"card": {
"hosted_url": "https://bravopay.club/api/v1/transactions/tx_clxdef456/card-redirect",
"message": "Redirect customer to hosted_url to enter card details (Stripe Elements, PCI-compliant)."
},
"created_at": "2026-06-01T15:30:00.000Z"
}GET /transactions — Listar
/transactionsLista transações em ordem decrescente. Paginação por cursor.
Query params
| Campo | Tipo | Descrição |
|---|---|---|
limit | integer | Máx 100. Default 20. |
cursor | string | ID da última transação da página anterior. |
status | PENDING|PAID|EXPIRED|REFUNDED|CHARGEBACK|FAILED | Filtra por status. |
method | PIX|CARD|APPLE_PAY|GOOGLE_PAY|MB_WAY|MULTIBANCO | Filtra por método. |
curl https://bravopay.club/api/v1/transactions?status=PAID&limit=50 \
-H "Authorization: Bearer bp_live_seu_token"{
"data": [
{
"id": "tx_clxabc123",
"object": "transaction",
"product_id": "prd_xxx",
"checkout_id": "ck_xxx",
"customer": { "email": "...", "name": "...", "cpf": "...", "phone": "..." },
"amount_cents": 1990,
"fee_cents": 449,
"net_cents": 1541,
"currency": "BRL",
"method": "PIX",
"status": "PAID",
"provider": "safepix",
"provider_id": "tx_safepix_xxx",
"pix": { "qr_code": "...", "copy_paste": "...", "expires_at": "..." },
"card": null,
"tracking": { "utm_source": "...", "utm_medium": "...", "fbclid": "..." },
"paid_at": "2026-06-01T15:32:00.000Z",
"created_at": "2026-06-01T15:30:00.000Z",
"updated_at": "2026-06-01T15:32:00.000Z"
}
],
"has_more": true,
"next_cursor": "tx_clxabc123"
}GET /me — Conta atual
/meRetorna info da conta dona da API key.
curl https://bravopay.club/api/v1/me -H "Authorization: Bearer bp_live_seu_token"{
"id": "usr_xxx",
"email": "voce@example.com",
"name": "Você",
"balance_cents": 12345,
"api_card_enabled": false
}Produtos
/productsLista produtos da conta.
/productsCria produto. Preço mínimo R$ 5,00 (500 cents).
/products/{id}Detalha produto por ID.
/products/{id}Atualiza campos do produto.
POST /products · body
| Campo | Tipo | Descrição |
|---|---|---|
name | string (req) | Nome do produto. Max 200. |
price_cents | integer (req) | Preço em centavos. Min 500 = R$ 5,00. |
description | string | Descrição. Max 2000. |
image | string (url) | URL HTTPS de imagem (jpg/png/webp). |
type | "DIGITAL" | "PHYSICAL" | "SUBSCRIPTION" | Default DIGITAL. |
interval_days | integer | Só se type=SUBSCRIPTION. Default 30. |
active | boolean | Default true. |
curl -X POST https://bravopay.club/api/v1/products \
-H "Authorization: Bearer bp_live_seu_token" \
-H "Content-Type: application/json" \
-d '{
"name": "Plano Pro Mensal",
"price_cents": 1990,
"description": "Acesso completo por 30 dias",
"type": "SUBSCRIPTION",
"interval_days": 30
}'Checkouts
Um Checkout é uma página de venda pública hospedada em bravopay.club/c/{slug}. Cada produto pode ter vários checkouts (ofertas diferentes).
/checkoutsLista checkouts da conta.
/checkoutsCria checkout. Requer product_id existente.
/checkouts/{id}Detalha checkout.
/checkouts/{id}Atualiza checkout.
POST /checkouts · body
| Campo | Tipo | Descrição |
|---|---|---|
product_id | string (req) | ID do produto. |
slug | string | Slug da URL. Auto-gerado se omitido. |
payment_methods | array | ["pix", "card", "apple_pay", "google_pay"] |
price_cents_override | integer | Sobrescreve o preço do produto pra esse checkout. |
thank_you_url | string (url) | Pra onde redirecionar após pagar. |
back_redirect_url | string (url) | Back-redirect quando user sai sem pagar. |
video_url | string (url) | VSL no topo do checkout. |
facebook_pixel_id | string | Override do pixel global. |
tiktok_pixel_id | string | Override do pixel global. |
Webhooks (eventos)
Eventos são enviados POST pra URL configurada em Dashboard → Integrações. Cada chamada tem assinatura HMAC-SHA256 no header X-Bravopay-Signature usando o secret cadastrado.
Eventos disponíveis
| transaction.created | Tx criada (PIX gerado ou cartão iniciado) |
| transaction.paid | Pagamento confirmado |
| transaction.refunded | Reembolsada |
| transaction.chargebacked | Chargeback (cartão) |
| transaction.expired | PIX expirou ou cartão falhou |
| withdrawal.completed | Saque processado |
Payload (todos os eventos)
{
"id": "evt_xxx",
"type": "transaction.paid",
"created_at": "2026-06-01T15:32:00.000Z",
"data": {
"object": "transaction",
"id": "tx_clxabc123",
"status": "PAID",
"amount_cents": 1990,
"currency": "BRL",
"method": "PIX",
"customer": { "email": "...", "name": "...", "cpf": "..." },
"external_reference": "order_42",
"paid_at": "2026-06-01T15:32:00.000Z"
}
}Verificação de assinatura (Node.js)
import crypto from "node:crypto";
function verifyWebhook(rawBody, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
);
}Taxas (referência)
As taxas variam por conta. Consulte GET /me pra ver os números atuais da sua conta, ou Dashboard → Perfil.
| PIX (default) | 5,99% + R$ 2,00 |
| Cartão (white) | 9,90% + R$ 3,60 · retenção 10% × 90 dias |
| Cartão (black) | 35% + R$ 10,00 · retenção 20% × 90 dias |
| Saque PIX | R$ 9,90 (fixo) |
| Mínimo saque | R$ 10,00 |
Quickstart (Node.js)
// 1. Cria PIX (sem produto, funciona pra qualquer conta)
const res = await fetch("https://bravopay.club/api/v1/transactions", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BRAVOPAY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
amount_cents: 1990,
method: "pix",
customer: {
email: "cliente@example.com",
name: "Cliente Exemplo",
cpf: "11144477735",
},
description: "Pedido #42",
external_reference: "order_42",
}),
});
const tx = await res.json();
if (!res.ok) throw new Error(tx.error.message);
// 2. Mostra QR pro cliente
console.log("Copia-cola PIX:", tx.pix.copy_paste);
console.log("Expira em:", tx.pix.expires_at);
// 3. Espera webhook 'transaction.paid' chegar no seu endpoint
// OU pollie GET /transactions/{id} periodicamente
// OU melhor: configure o webhook em Dashboard → Integrações