API REST · v1

Integrar PIX

Cobrança PIX, consulta, saldo e saque. Valores em centavos, inteiros. Sucesso vem com ok: true.

Base URL
https://api.capripayments.com
Formato
application/json
Erros
{ "ok": false, "error": "…", "code": "…" }

Autenticação

Crie a chave em Painel → API. O segredo começa com cpr_ e aparece uma vez. Envie em cada chamada:

Authorization: Bearer cpr_sua_chave
Content-Type: application/json

Sem chave, ou com chave revogada, a resposta é 401 e API_KEY_INVALID.

Criar cobrança

POST/v1/charges

Gera o PIX copia e cola. Status inicial pending. Mínimo: 100 centavos.

Corpo

amount
Obrigatório. Inteiro em centavos, maior que zero.
description
Opcional. Até 180 caracteres.
expiresIn
Opcional. Também expires_in. Padrão 30 minutos. Use 30m, 1h, 90s ou segundos em número, entre 1 minuto e 24 horas.
externalId
Opcional. Também external_id. Idempotente por conta: repetir o mesmo id devolve a cobrança já criada.
customer
phone e document (type CPF ou CNPJ, value). name e email são opcionais. Nome, e-mail e telefone enviados aparecem no detalhe da transação no painel.
customerIp
Opcional. Também customer_ip. IP de quem paga, não o IP do servidor. IPv4 ou IPv6.
checkoutUrl
Opcional. Também checkout_url. URL http ou https do checkout que gerou o pedido. Volta na cobrança, no detalhe da transação e em todo webhook dessa cobrança.
callbackUrl
Opcional. Também callback_url. URL http ou https. Não substitui o endpoint do painel: ela volta dentro de charge em cada webhook, inclusive no reenvio.
metadata
Opcional. Até 8 pares de texto, chave com letras, números, _ ou - (até 40) e valor até 200. Use para um id do pedido. Volta igual na cobrança e no webhook. externalId continua sendo a chave de idempotência e também volta em charge.externalId.

Exemplo

POST /v1/charges

{
  "amount": 84700,
  "description": "Pedido 1847",
  "expiresIn": "30m",
  "externalId": "ped-1847",
  "customerIp": "187.32.10.20",
  "checkoutUrl": "https://loja.example/checkout/1847",
  "callbackUrl": "https://loja.example/pagamentos/callback",
  "metadata": { "orderId": "1847" },
  "customer": {
    "name": "Cliente",
    "email": "cliente@empresa.com",
    "phone": "11912345678",
    "document": { "type": "CPF", "value": "12345678909" }
  }
}

Resposta · 201

{
  "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",
    "externalId": "ped-1847",
    "checkoutUrl": "https://loja.example/checkout/1847",
    "callbackUrl": "https://loja.example/pagamentos/callback",
    "metadata": { "orderId": "1847" }
  }
}

Erros

  • 400 INVALID_AMOUNT, AMOUNT_TOO_LOW, INVALID_EXPIRES, INVALID_CUSTOMER_IP, CUSTOMER_PHONE_REQUIRED, CUSTOMER_DOCUMENT_REQUIRED, INVALID_CHECKOUT_URL, INVALID_CALLBACK_URL, INVALID_METADATA
  • 401 API_KEY_INVALID
  • 403 TENANT_INACTIVE
Testar

Consultar cobrança

GET/v1/charges/:id

A resposta tem o mesmo objeto charge da criação. Status: pending, paid, expired, cancelled, failed, rejected, infraction, med, returned.

GET /v1/charges lista a conta. POST /v1/charges/:id/cancel cancela só pending e não credita saldo (409 INVALID_STATE fora desse estado). Cobrança paga dispara charge.paid.

Erros

  • 404 NOT_FOUND
  • 401 API_KEY_INVALID
Testar

Saldo

GET/v1/balance

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

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

Testar

Criar saque

POST/v1/withdrawals

Solicita um PIX de saída. Mínimo: 1000 centavos. A chave de destino é obrigatória.

Corpo

amount
Obrigatório. Inteiro em centavos.
pixKey
Obrigatório. Também pix_key. Chave de quem vai receber: CPF, CNPJ, e-mail, telefone ou EVP.
externalId
Opcional. Também external_id. Idempotente por conta.
customerIp
Opcional. Também customer_ip. IP de quem recebe, não o IP do servidor. IPv4 ou IPv6.

Exemplo

POST /v1/withdrawals

{
  "amount": 20000,
  "pixKey": "destino@empresa.com",
  "externalId": "saque-20260321",
  "customerIp": "2804:14c:1:1::1"
}

Resposta · 201

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

Erros

  • 400 INVALID_PIX, INVALID_AMOUNT, AMOUNT_TOO_LOW, INVALID_CUSTOMER_IP
  • 401 API_KEY_INVALID
  • 403 TENANT_INACTIVE
  • 409 INSUFFICIENT_BALANCE
Testar

Consultar saque

GET/v1/withdrawals/:id

A resposta tem o mesmo objeto withdrawal. Status: pending, processing, completed, failed, cancelled. GET /v1/withdrawals lista a conta. Conclusão dispara withdrawal.completed; falha dispara withdrawal.failed.

Erros

  • 404 NOT_FOUND
  • 401 API_KEY_INVALID
Testar

Webhooks

Cadastre URLs em Painel → Webhooks e escolha os eventos. Responda 200 ou 201.

  • charge.created, charge.paid, charge.expired, charge.cancelled
  • withdrawal.completed, withdrawal.failed
{
  "id": "evt_…",
  "type": "charge.paid",
  "created_at": "2026-03-21T14:32:08.000Z",
  "data": {
    "charge": {
      "id": "chg_…",
      "externalId": "ped-1847",
      "status": "paid",
      "checkoutUrl": "https://loja.example/checkout/1847",
      "callbackUrl": "https://loja.example/pagamentos/callback",
      "metadata": { "orderId": "1847" }
    }
  }
}

Com secret no endpoint, os headers são:

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

Compare a assinatura com o secret do endpoint antes de confiar no corpo.

Fluxo

  1. Crie a cobrança e mostre pixCopy a quem vai pagar.
  2. Receba charge.paid e libere o pedido.
  3. Se precisar reconciliar, chame GET /v1/charges/:id.
  4. Saque com POST /v1/withdrawals, informando a chave de destino.

ola@capripayments.com

Documentação da API · Capri Payments