API REST · v1
Integrar PIX
Cobrança PIX, consulta, saldo e saque. Valores em centavos, inteiros. Sucesso vem com ok: true.
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/jsonSem 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. Use30m,1h,90sou 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
phoneedocument(typeCPF ou CNPJ,value).nameeemailsã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 dechargeem 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.externalIdcontinua sendo a chave de idempotência e também volta emcharge.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
400INVALID_AMOUNT,AMOUNT_TOO_LOW,INVALID_EXPIRES,INVALID_CUSTOMER_IP,CUSTOMER_PHONE_REQUIRED,CUSTOMER_DOCUMENT_REQUIRED,INVALID_CHECKOUT_URL,INVALID_CALLBACK_URL,INVALID_METADATA401API_KEY_INVALID403TENANT_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
404NOT_FOUND401API_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
400INVALID_PIX,INVALID_AMOUNT,AMOUNT_TOO_LOW,INVALID_CUSTOMER_IP401API_KEY_INVALID403TENANT_INACTIVE409INSUFFICIENT_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
404NOT_FOUND401API_KEY_INVALID
Testar
Webhooks
Cadastre URLs em Painel → Webhooks e escolha os eventos. Responda 200 ou 201.
charge.created,charge.paid,charge.expired,charge.cancelledwithdrawal.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 segundosX-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
- Crie a cobrança e mostre
pixCopya quem vai pagar. - Receba
charge.paide libere o pedido. - Se precisar reconciliar, chame
GET /v1/charges/:id. - Saque com
POST /v1/withdrawals, informando a chave de destino.