Comece aqui

Introdução

Documentação da API KUBOFY — Pix, boleto e cartão numa API única, mais consulta de saldo, taxas, disputas, transações e webhooks assinados. Sem precisar conhecer o adquirente por trás.

Base URL

https://www.kubofy.com.br/api/v1

Autenticação

Bearer + Secret Header

Limite

120 req/min

Autenticação

Toda chamada exige duas credenciais, geradas de uma vez no painel (Configurações → Chaves de API): a chave (Bearer token) e o segredo, enviado em header separado. O segredo só é exibido no momento da criação — se perder, revogue e gere outra.

Headers obrigatórios

Authorization: Bearer {SUA_API_KEY}
X-Kubofy-Secret: {SEU_API_SECRET}
Accept: application/json

Chave e segredo são isolados por conta — sua integração só enxerga e manipula os próprios dados, nunca os de outro lojista.

Formato de respostas

Respostas são JSON plano — sem envelope {"data": ...} nos recursos únicos, os campos vêm direto na raiz do objeto. Listas paginadas (transações, disputas) usam {"data": [...], "meta": {...}}. Erros seguem {"message": "..."} com o status HTTP correspondente.

Cobranças Pix

Três operações cobrem todo o ciclo de uma cobrança: criar, consultar e estornar.

POST /pix/charges

Cria uma cobrança Pix com QR code dinâmico e devolve o BR Code na hora.

Request

curl -X POST https://www.kubofy.com.br/api/v1/pix/charges \
  -H "Authorization: Bearer {API_KEY}" \
  -H "X-Kubofy-Secret: {API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 149.90,
    "description": "Assinatura Pro",
    "payer": {
      "name": "Maria Silva",
      "email": "maria@exemplo.com",
      "phone": "11999998888",
      "document": "12345678900"
    }
  }'

Response201 Created

{
  "id": 4821,
  "txid": "A1B2C3D4E5F6G7H8I9J0K1L2M3",
  "status": "created",
  "amount": 149.90,
  "currency": "BRL",
  "expires_at": "2026-07-08T02:00:00Z",
  "brcode": "00020126580014br.gov.bcb.pix..."
}

Campos payer.name, payer.email, payer.phone e payer.document são obrigatórios — exigência do Pix, não burocracia nossa.

GET /pix/charges/{txid}

Consulta o status atual de uma cobrança pelo identificador (txid).

Response

{
  "id": 4821,
  "txid": "A1B2C3D4E5F6G7H8I9J0K1L2M3",
  "status": "paid",
  "amount": 149.90,
  "currency": "BRL",
  "description": "Assinatura Pro",
  "expires_at": "2026-07-08T02:00:00Z",
  "payer": { "name": "Maria Silva", "document": "12345678900" }
}

status muda entre created → paid / expired / cancelled / refunded.

POST /pix/charges/{txid}/refunds

Estorna uma cobrança já paga.

Response200 OK

{
  "txid": "A1B2C3D4E5F6G7H8I9J0K1L2M3",
  "status": "refunded"
}

Boleto

Mesmo padrão do Pix — o boleto é gerado direto no adquirente configurado.

POST /boleto/charges

Cria uma cobrança de boleto e devolve código de barras e linha digitável.

Request

curl -X POST https://www.kubofy.com.br/api/v1/boleto/charges \
  -H "Authorization: Bearer {API_KEY}" \
  -H "X-Kubofy-Secret: {API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 149.90,
    "description": "Pedido 123",
    "payer": {
      "name": "Maria Silva",
      "email": "maria@exemplo.com",
      "phone": "11999998888",
      "document": "12345678900"
    }
  }'

Response201 Created

{
  "id": 91,
  "txid": "B7K2M9...",
  "status": "created",
  "amount": 149.90,
  "currency": "BRL",
  "due_date": "2026-07-10T00:00:00Z",
  "barcode": "00190000090123456789012345678901234567890123",
  "digitable_line": "00190.00009 01234.567890 12345.678901 2 34567890123456"
}

GET /boleto/charges/{txid}

Consulta status, código de barras e vencimento de um boleto.

Cartão

Cartão é síncrono — a resposta já vem com o resultado da cobrança, sem precisar de webhook na maioria dos casos.

POST /card/charges

Cria uma cobrança de cartão de crédito. Valor mínimo: R$5,00.

Request

curl -X POST https://www.kubofy.com.br/api/v1/card/charges \
  -H "Authorization: Bearer {API_KEY}" \
  -H "X-Kubofy-Secret: {API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 149.90,
    "installments": 1,
    "description": "Pedido 456",
    "payer": {
      "name": "Maria Silva",
      "email": "maria@exemplo.com",
      "phone": "11999998888",
      "document": "12345678900"
    },
    "card": {
      "number": "4111111111111111",
      "holder_name": "MARIA SILVA",
      "holder_document": "12345678900",
      "expiration_month": "08",
      "expiration_year": "2029",
      "cvv": "123"
    }
  }'

Response201 Created

{
  "txid": "C9F3A1...",
  "status": "approved",
  "amount": 149.90,
  "currency": "BRL",
  "brand": "VISA"
}

status: approved (201), pending (202 — raro, aguarda confirmação assíncrona) ou failed (402 — recusado).
card.holder_document é opcional — se não informado, usa o documento do pagador.

GET /card/charges/{txid}

Consulta o status de uma cobrança de cartão.

Conta

Dados da sua conta, saldo disponível e taxas configuradas — sempre em tempo real.

GET /me

Dados do lojista autenticado e status de configuração do gateway.

{
  "id": 12,
  "name": "Loja Exemplo LTDA",
  "email": "contato@loja.com",
  "user_type": "merchant",
  "created_at": "2026-01-15T10:00:00Z",
  "profile": {
    "legal_name": "Loja Exemplo LTDA",
    "trading_name": "Loja Exemplo",
    "document": "12345678000199"
  },
  "gateway": { "configured": true }
}

GET /balance

Saldo real por método, já descontando reservas de saque em andamento.

{
  "pix": 4230.50,
  "card": 1899.00,
  "boleto": 640.00,
  "refunded": 89.90,
  "pending": 320.00,
  "affiliate_earnings": 150.00,
  "total": 6829.60,
  "currency": "BRL"
}

GET /fees

Taxas configuradas para sua conta (percentual e/ou fixo por método).

{
  "pix_rate": 0.99,
  "pix_rate_fixed": 0.40,
  "card_rate": 3.99,
  "card_rate_fixed": 0,
  "boleto_rate": 2.5,
  "boleto_rate_fixed": 1.90,
  "crypto_rate": null,
  "fee_type_in": "percentage",
  "reserve_rate": 0,
  "withdrawal_rate": 1.5,
  "withdrawal_rate_fixed": 0,
  "fee_type_out": "percentage"
}

Retorna 404 se sua conta ainda não tiver taxa configurada pelo suporte KUBOFY.

Transações & disputas

Consulta genérica cobrindo Pix, cartão e boleto juntos — e o status das suas disputas.

GET /transactions

Lista paginada de todas as suas transações. Filtros opcionais: status (pending/approved/failed/refunded), method (pix/card/boleto) e per_page (máx. 100).

GET /transactions?status=approved&method=pix

{
  "data": [
    {
      "id": 4821,
      "reference": "A1B2C3D4...",
      "amount": 149.90,
      "fee_amount": 4.94,
      "net_amount": 144.96,
      "currency": "BRL",
      "method": "pix",
      "status": "approved",
      "description": "Assinatura Pro",
      "customer_name": "Maria Silva",
      "customer_email": "maria@exemplo.com",
      "created_at": "2026-07-07T14:20:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 3, "per_page": 15, "total": 42 }
}

GET /transactions/{id}

Consulta uma transação específica pelo ID interno.

GET /disputes

Lista suas disputas/chargebacks — só leitura. Abertura e defesa de disputa são feitas pela equipe KUBOFY.

{
  "data": [
    {
      "id": 7,
      "type": "chargeback",
      "status": "under_review",
      "status_label": "Em análise",
      "reason": "Produto não recebido",
      "amount": 149.90,
      "transaction_reference": "A1B2C3D4...",
      "opened_at": "2026-07-01T09:00:00Z",
      "resolved_at": null
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 15, "total": 1 }
}

Também disponível: GET /disputes/{id} pra consultar uma disputa específica.

Webhooks

Criar, listar e remover

Gerencie seus endpoints de webhook direto pela API (mesma coisa que a tela de Webhooks no painel). O segredo só aparece na resposta da criação — guarde nesse momento.

POST /webhooks

curl -X POST https://www.kubofy.com.br/api/v1/webhooks \
  -H "Authorization: Bearer {API_KEY}" \
  -H "X-Kubofy-Secret: {API_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://minhaloja.com/webhooks/kubofy",
    "events": ["pix.charge.paid", "card.charge.paid"]
  }'

{
  "id": 3,
  "url": "https://minhaloja.com/webhooks/kubofy",
  "events": ["pix.charge.paid", "card.charge.paid"],
  "status": "active",
  "secret": "8f14e45fceea167a5a36...",
  "created_at": "2026-07-07T15:00:00Z"
}

GET /webhooks lista os seus (sem o segredo). DELETE /webhooks/{id} remove. URLs internas/privadas são rejeitadas (422) — só HTTPS público.

Eventos disponíveis

pix.charge.created
pix.charge.paid
pix.charge.refunded
boleto.charge.created
boleto.charge.paid
card.charge.paid

Entregas com falha são reenviadas automaticamente; o histórico completo (status, resposta, tentativas) fica visível no painel.

Verificando a assinatura (HMAC SHA-256)

POST {sua_url}
X-Kubofy-Event: pix.charge.paid
X-Kubofy-Delivery: 8f14e45f-...
X-Kubofy-Signature: sha256=7d793037...

$expected = hash_hmac('sha256', $rawRequestBody, $seuWebhookSecret);
$recebida = str_replace('sha256=', '', $_SERVER['HTTP_X_KUBOFY_SIGNATURE']);

if (!hash_equals($expected, $recebida)) {
    http_response_code(401);
    exit;
}

O segredo do webhook é gerado junto com o endpoint e mostrado uma única vez — trate como senha.

Referência

Ainda não disponível

Duas operações que existem no roadmap mas ainda não estão na API pública, por decisão deliberada — preferimos não lançar algo sem confiança total no formato antes de confirmar contra o ambiente real:

— POST /withdrawals (saque via API) — hoje o saque é feito pelo painel.
— Criptomoeda como forma de recebimento.

Tratamento de erros

200 / 201Sucesso / recurso criado

202Cartão pendente — aguardando confirmação

204Removido com sucesso (sem corpo)

401Credenciais ausentes ou inválidas

402Cartão recusado

404Recurso não encontrado ou não pertence a você

422Dados inválidos ou adquirente não configurado

429Limite de requisições excedido

502Falha temporária no adquirente — tente novamente

Limites de uso

120/min

por chave de API, em todos os endpoints. Ao exceder, a resposta traz 429 — implemente backoff exponencial nas tentativas.

Gerar minha chave de API