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 URLhttps://bravopay.club/api/v1
AuthAuthorization: Bearer bp_live_...
Content-Typeapplication/json
EncodingUTF-8
Rate limit60 req/min por chave
IdempotênciaHeader Idempotency-Key em POST
WebhookHMAC-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.

bash
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.

json
{
  "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

unauthorized401 · Token ausente, inválido ou expirado
forbidden403 · Token válido mas sem permissão pro recurso
validation_error422 · Campo com formato/valor inválido (veja details)
product_not_found404 · product_id não pertence à conta
product_inactive422 · Produto existe mas está desativado
rate_limited429 · Excedeu 60 req/min (veja header Retry-After)
acquirer_error502 · O adquirente (Stripe/SafePix/MP) falhou; veja details.attempts
internal_error500 · 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.

Sem product_id: tanto PIX quanto cartão funcionam pra TODA conta. O servidor cria um ghost product automaticamente pra acoplar a tx.
POST/transactions

Cria PIX ou cobrança de cartão. Retorna copy-paste do PIX ou URL hospedada do cartão.

Request body (JSON)

CampoTipoDescrição
amount_centsinteger (req)Valor em centavos. Mínimo 500 (R$ 5,00).
method"pix" | "card"Default "pix". Ambos permitidos sem product_id.
customer.emailstringEmail do cliente. Default gerado automaticamente.
customer.namestringNome do cliente.
customer.cpfstringCPF/CNPJ (com ou sem máscara).
customer.phonestringTelefone (E.164 ou formato BR).
product_idstringID do produto. Opcional. Sem ele usa produto interno "ghost".
descriptionstringTexto livre que aparece no extrato/recibo. Max 300 chars.
external_referencestringSeu ID interno pra correlacionar. Max 120 chars.
expires_inintegerSegundos até expirar (PIX). 60-86400. Default 3600.
utm.sourcestringUTM tracking.
utm.mediumstringUTM tracking.
utm.campaignstringUTM tracking.
utm.contentstringUTM tracking.
utm.termstringUTM tracking.
utm.fbclidstringFacebook click ID.
utm.gclidstringGoogle click ID.
utm.ttclidstringTikTok click ID.

Exemplo cURL — PIX simples

bash
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

json
{
  "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

bash
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

json
{
  "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

GET/transactions

Lista transações em ordem decrescente. Paginação por cursor.

Query params

CampoTipoDescrição
limitintegerMáx 100. Default 20.
cursorstringID da última transação da página anterior.
statusPENDING|PAID|EXPIRED|REFUNDED|CHARGEBACK|FAILEDFiltra por status.
methodPIX|CARD|APPLE_PAY|GOOGLE_PAY|MB_WAY|MULTIBANCOFiltra por método.
bash
curl https://bravopay.club/api/v1/transactions?status=PAID&limit=50 \
  -H "Authorization: Bearer bp_live_seu_token"
json
{
  "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

GET/me

Retorna info da conta dona da API key.

bash
curl https://bravopay.club/api/v1/me -H "Authorization: Bearer bp_live_seu_token"
json
{
  "id": "usr_xxx",
  "email": "voce@example.com",
  "name": "Você",
  "balance_cents": 12345,
  "api_card_enabled": false
}

Produtos

GET/products

Lista produtos da conta.

POST/products

Cria produto. Preço mínimo R$ 5,00 (500 cents).

GET/products/{id}

Detalha produto por ID.

PATCH/products/{id}

Atualiza campos do produto.

POST /products · body

CampoTipoDescrição
namestring (req)Nome do produto. Max 200.
price_centsinteger (req)Preço em centavos. Min 500 = R$ 5,00.
descriptionstringDescrição. Max 2000.
imagestring (url)URL HTTPS de imagem (jpg/png/webp).
type"DIGITAL" | "PHYSICAL" | "SUBSCRIPTION"Default DIGITAL.
interval_daysintegerSó se type=SUBSCRIPTION. Default 30.
activebooleanDefault true.
bash
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).

GET/checkouts

Lista checkouts da conta.

POST/checkouts

Cria checkout. Requer product_id existente.

GET/checkouts/{id}

Detalha checkout.

PATCH/checkouts/{id}

Atualiza checkout.

POST /checkouts · body

CampoTipoDescrição
product_idstring (req)ID do produto.
slugstringSlug da URL. Auto-gerado se omitido.
payment_methodsarray["pix", "card", "apple_pay", "google_pay"]
price_cents_overrideintegerSobrescreve o preço do produto pra esse checkout.
thank_you_urlstring (url)Pra onde redirecionar após pagar.
back_redirect_urlstring (url)Back-redirect quando user sai sem pagar.
video_urlstring (url)VSL no topo do checkout.
facebook_pixel_idstringOverride do pixel global.
tiktok_pixel_idstringOverride 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.createdTx criada (PIX gerado ou cartão iniciado)
transaction.paidPagamento confirmado
transaction.refundedReembolsada
transaction.chargebackedChargeback (cartão)
transaction.expiredPIX expirou ou cartão falhou
withdrawal.completedSaque processado

Payload (todos os eventos)

json
{
  "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)

javascript
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)
  );
}
Responda 200 OKrápido (<5s) pra não causar retry. Processe em fila se a lógica for pesada. Eventos são re-tentados com backoff exponencial em caso de falha (até 24h).

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 PIXR$ 9,90 (fixo)
Mínimo saqueR$ 10,00

Quickstart (Node.js)

javascript
// 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