API REST · v1

Integrar PIX na sua aplicação

A API Capri cobre cobrança PIX, consulta de saldo e saque PIX. Valores monetários são sempre inteiros em centavos. Respostas JSON usam ok: true em caso de sucesso.

Base URL: https://api-production-27d99.up.railway.app
Formato: application/json
Chaves: Crie em Painel → API (prefixo cpr_). O segredo completo aparece uma única vez.

Autenticação

Envie a chave de API no header de cada requisição autenticada.

Authorization: Bearer cpr_sua_chave
Content-Type: application/json

Requisições sem chave válida ou com chave revogada retornam 401.

Cobranças

Criar cobrança

POST /v1/charges — gera o PIX copia e cola (pixCopy) e status inicial pending. Valor mínimo: R$ 1,00 (100 centavos).

{
  "amount": 84700,
  "description": "Pedido #1847",
  "expiresIn": "30m",
  "externalId": "ped-1847",
  "customer": {
    "name": "Cliente",
    "email": "cliente@empresa.com",
    "phone": "(11) 91234-5678",
    "document": { "type": "CPF", "value": "12345678909" }
  }
}

externalId é idempotente por conta. expiresIn aceita sufixos como m e h. O bloco customer pode ser necessário quando a chave PIX da conta não for CPF/CNPJ — use documento válido do pagador.

201 Created

{
  "ok": true,
  "charge": {
    "id": "chg_…",
    "amount": 84700,
    "description": "Pedido #1847",
    "status": "pending",
    "pixCopy": "00020126…",
    "expiresAt": "2026-03-21T12:00:00.000Z",
    "paidAt": null,
    "createdAt": "2026-03-21T11:30:00.000Z"
  }
}

Consultar e listar

GET /v1/charges/:id — detalhe de uma cobrança
GET /v1/charges — lista da conta
POST /v1/charges/:id/cancel — cancela cobrança pending (não credita saldo)

Status possíveis: pending, paid, expired, cancelled. Quando o pagamento confirma, o saldo disponível é creditado e o evento charge.paid é disparado (webhook).

Saques

POST /v1/withdrawals — solicita transferência PIX. Valor mínimo: R$ 10,00 (1000 centavos). Informe pixKey no corpo; se omitir, usa a chave padrão da conta.

{
  "amount": 20000,
  "pixKey": "operador@empresa.com",
  "externalId": "saque-20260321"
}

201 Created

{
  "ok": true,
  "withdrawal": {
    "id": "wd_…",
    "amount": 20000,
    "pixKey": "••••@email.com",
    "status": "processing",
    "source": "api",
    "failureReason": null,
    "completedAt": null,
    "createdAt": "…"
  }
}

GET /v1/withdrawals/:id
GET /v1/withdrawals

Status: pending, processing, completed, failed, cancelled. Conclusão dispara withdrawal.completed; falha dispara withdrawal.failed.

Saldo

GET /v1/balance

{
  "ok": true,
  "balance": {
    "available": 84700,
    "reserved": 0,
    "ledger": 84700
  }
}

available é o que pode ser sacado. reserved inclui saques em processamento.

Webhooks

Cadastre URLs em Painel → Webhooks. Cada endpoint escolhe quais eventos recebe. Responda com 200 ou 201 para confirmar entrega.

Eventos disponíveis:

charge.created, charge.paid, charge.expired, charge.cancelled
withdrawal.completed, withdrawal.failed

Corpo enviado ao seu servidor:

{
  "id": "evt_…",
  "type": "charge.paid",
  "created_at": "2026-03-21T14:32:08.000Z",
  "data": {
    "charge": { … }
  }
}

Headers de assinatura (quando o endpoint tem secret):

X-Capri-Timestamp — unix em segundos
X-Capri-Signature — HMAC-SHA256 hex de {timestamp}.{rawBody}
X-Capri-Event-Id, X-Capri-Endpoint-Id

Use o secret exibido ao criar o endpoint. Compare a assinatura antes de confiar no payload. Entregas ficam no histórico do painel.

Fluxo recomendado

Crie a cobrança e mostre pixCopy (ou QR) ao pagador.
Receba charge.paid no webhook e libere seu produto ou pedido.
Opcional: consulte GET /v1/charges/:id se precisar reconciliar.
Saque via API ou painel quando quiser transferir o saldo.

Dúvidas operacionais: ola@capripayments.com