API · v1 · Estável

Documentação
da API

Integre pagamentos PIX, boleto e cartão em minutos.
REST + JSON. Autenticação via Bearer Token.

PIX Cartão Boleto 60 req/min Valores em centavos

Base URL https://api.chasepay.com.br

Começando

Introdução

API REST com respostas em JSON. Todos os valores monetários são em centavos inteiros (ex: 4890 = R$ 48,90).

Versão: v1
Formato: JSON — Content-Type: application/json
Erros: sempre em {"error": {"message": "..."}}
Limites: mín. R$ 1,00 (PIX mín. R$ 10,00) · máx. R$ 100.000,00 · PIX máx. R$ 2.000,00 por transação
Rate limit: 60 requisições/minuto por token — header X-RateLimit-Limit: 60
Datas: horário de Brasília (UTC-3), formato YYYY-MM-DD HH:MM:SS (exceto boleto_due: apenas YYYY-MM-DD)

Começando

Autenticação

Envie o header Authorization: Bearer {sua_api_key} em todas as chamadas. Gere sua chave em Dashboard → Configurações → API. A chave secreta é exibida uma única vez — guarde-a com segurança.

🔑

Bearer Token — não Basic Auth
A API ChasePay usa Bearer Token. Inclua Authorization: Bearer SEU_TOKEN em cada requisição. Não use HTTP Basic Auth.

cURL — Autenticação

curl https://api.chasepay.com.br/v1/balance \
  -H "Authorization: Bearer SEU_TOKEN"

🚫

Proteja seu token com máxima prioridade
O token dá acesso completo à sua conta: criar cobranças, emitir saques e processar reembolsos. Armazene exclusivamente em variáveis de ambiente do servidor. Nunca exponha no frontend, código-fonte ou repositórios.

Começando

Primeiros passos

Teste sua integração em minutos. Não há sandbox separado — use valores mínimos para testar.

Crie sua conta e obtenha o token

Acesse Dashboard → Configurações → API e copie seu token. Exibido uma única vez — salve em lugar seguro.

Crie sua primeira cobrança PIX

Mínimo R$ 10,00 (1.000 centavos). Use external_id para identificar o pedido e garantir idempotência.

Renderize o QR Code

O campo pix_qr_code contém o código EMV — renderize no seu frontend com qualquer biblioteca QR. O status muda para paid em segundos após pagamento.

Configure webhooks para notificações

Registre seu endpoint via POST /v1/user/webhooks e teste com POST /v1/user/webhooks/:id/test. Valide sempre a assinatura HMAC antes de processar.

Limites: PIX mín R$ 10 / máx R$ 2.000. Outros métodos: mín R$ 1 (linha digit: ~R$ 4) / máx R$ 100.000. Rate limit: 60 req/min por token (header X-RateLimit-Limit: 60).

Exemplo — Primeira cobrança PIX

curl -X POST https://api.chasepay.com.br/v1/charges \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pix",
    "amount_cents": 1000,
    "payer_name": "Teste",
    "payer_document": "00000000000"
  }'

Cobranças

Criar cobrança

POST /v1/charges

Cria uma cobrança PIX, cartão ou boleto. Retorna 201 com os dados da transação incluindo o QR Code (PIX) ou linha digitável (boleto).

⚠️

Sem sandbox separado — todas as cobranças são reais. Use valor mínimo (R$ 10,00 PIX) e external_id para identificar testes. Se boleto estiver indisponível, retorna HTTP 503.

Parâmetros da requisição

Campo	Tipo	Descrição
amount_centsobrig	integer	Valor em centavos. PIX: mín 1.000 (R$ 10), máx 200.000 (R$ 2.000). Outros: mín 100 (R$ 1), máx 10.000.000 (R$ 100.000).
methodobrig	string	`pix` \| `card` \| `boleto`
external_idrecom	string	Seu ID de pedido para idempotência. Máx 64 chars. Reenviar o mesmo `external_id` retorna `409` — recupere a transação original com `GET /v1/transactions/{external_id}`. É seguro para retry.
description	string	Descrição exibida ao pagador. Máx 255 chars.
customer.name	string	Nome completo do pagador.
customer.document	string	CPF (11 dígitos) ou CNPJ (14 dígitos). Apenas números, sem pontuação. Inválidos retornam `422`.
customer.email	string	Email do pagador.
customer.phone	string	Telefone do pagador.
payer_name	string	Atalho: nome do pagador sem objeto `customer`.
payer_document	string	Atalho: CPF/CNPJ sem objeto `customer`. Apenas dígitos, sem pontuação.
card	object	Somente `method=card`: `number`, `holder`, `expiry` (MM/AA), `cvv`, `installments`.
metadata	object	Chaves/valores customizados (máx 10). Devolvidos em webhooks.

Requisição completa

{
  "amount_cents": 4890,
  "method": "pix",
  "description": "Pedido #123",
  "external_id": "meu-pedido-001",

  "customer": {
    "name": "Amanda Carvalho",
    "email": "amanda@email.com",
    "document": "12345678900",
    "phone": "11999999999"
  },

  // ou atalho sem objeto customer:
  "payer_name": "Amanda Carvalho",
  "payer_document": "12345678900"
}

Resposta PIX (201)

{
  "data": {
    "id": 42,
    "external_id": "meu-pedido-001",
    "status": "pending",
    "method": "pix",
    "amount_cents": 4890,
    "fee_cents": 220,
    "net_cents": 4670,
    "pix_qr_code": "00020126...bcb.pix",
    "discount_cents": 0,
    "description": "Pedido #123",
    "payer_name": "Amanda Carvalho",
    "payer_document": "12345678900",
    "paid_at": null,
    "created_at": "2026-06-20 19:25:06",
    "updated_at": "2026-06-20 19:25:06"
  }
}
// boleto_line/boleto_url/boleto_due: não retornados no create; use GET /v1/transactions/:id

Resposta Boleto (201)

{
  "data": {
    "id": 43,
    "external_id": "tx_abc123",
    "status": "pending",
    "method": "boleto",
    "amount_cents": 4890,
    "fee_cents": 608,
    "net_cents": 4282,
    "pix_qr_code": null,
    "boleto_line": "19790000058044...",  // linha digitável
    "boleto_url":  "https://...",        // link para o PDF
    "boleto_due":  "2026-06-30",        // vencimento (YYYY-MM-DD)
    "discount_cents": 0,
    "description": "Pedido #456",
    "payer_name": "João Silva",
    "payer_document": "12345678900",
    "paid_at": null,
    "created_at": "2026-06-20 19:25:06",
    "updated_at": "2026-06-20 19:25:06"
  }
}
// ⚠ Se 201 sem boleto_line/url/due: provedor falhou, verifique antes de usar
// ⚠ Boleto indisponível no momento → HTTP 503

Resposta Cartão (201)

{
  "data": {
    "id": 44,
    "external_id": "pedido-card-001",
    "status": "paid",         // paid (aprovado) | failed (recusado por saldo/limite)
                           // 422 se número de cartão inválido ou recusado pelo adquirente
    "method": "card",
    "amount_cents": 4890,
    "fee_cents": 342,
    "net_cents": 4548,
    "pix_qr_code": null,
    "boleto_line": null,
    "boleto_url": null,
    "boleto_due": null,
    "discount_cents": 0,
    "description": "Pedido #789",
    "payer_name": "Amanda Carvalho",
    "payer_document": "12345678900",
    "paid_at": "2026-06-20 19:25:07",
    "created_at": "2026-06-20 19:25:06",
    "updated_at": "2026-06-20 19:25:07"
  }
}

Cobranças

Listar cobranças

GET /v1/transactions

Lista transações da mais recente à mais antiga com suporte a filtros e paginação.

Parâmetros de query

status  paid | pending | failed | disputed
method  pix | card | boleto
period  hoje | 7 | 30 | 90
from    2026-01-01  (YYYY-MM-DD)
to      2026-06-30  (YYYY-MM-DD)
page    1           (padrão)
limit   20          (padrão, máx 100)

Resposta 200

{
  "data": [
    {
      "id": 42,
      "external_id": "tx_64100c30d74fe430",
      "status": "paid",
      "method": "pix",
      "amount_cents": 4890,
      "fee_cents": 220,
      "net_cents": 4670,
      "discount_cents": 0,
      "description": null,
      "payer_name": "Amanda Carvalho",
      "payer_document": "12345678900",
      "customer_name": "Amanda Carvalho",
      "customer_email": null,
      "customer_document": null,
      "customer_phone": null,
      "checkout_name": null,
      "product_name": null,
      "receiver_name": "SUA EMPRESA",
      "pix_qr_code": "00020126...",
      "boleto_line": null,
      "boleto_url": null,
      "boleto_due": null,
      "paid_at": "2026-06-20 10:05:12",
      "created_at": "2026-06-20 10:00:00",
      "updated_at": "2026-06-20 10:05:12"
    }
  ],
  "total": 160,
  "page": 1,
  "limit": 20
}

Cobranças

Consultar cobrança

GET /v1/transactions/:id

Consulta pelo external_id ou pelo ID numérico retornado na criação.

// Por external_id:
GET /v1/transactions/meu-pedido-001
Authorization: Bearer SEU_TOKEN

// Por ID numérico:
GET /v1/transactions/42
Authorization: Bearer SEU_TOKEN

// Resposta 200
{
  "data": {
    "id": 42,
    "external_id": "meu-pedido-001",
    "status": "paid",
    "method": "pix",
    "amount_cents": 4890,
    "fee_cents": 220,
    "net_cents": 4670,
    "pix_qr_code": "00020126...",
    "boleto_line": null,
    "boleto_url": null,
    "boleto_due": null,          // YYYY-MM-DD para boleto
    "discount_cents": 0,
    "description": "Pedido #123",
    "payer_name": "Amanda Carvalho",
    "payer_document": "12345678900",
    "paid_at": "2026-06-20 10:05:12",
    "created_at": "2026-06-20 10:00:00",
    "updated_at": "2026-06-20 10:05:12"
  }
}
// Datas: horário de Brasília (UTC-3)

Cobranças

Reembolsar

POST /v1/charges/:id/refund

Solicita estorno de uma transação paga. A transação vai para status disputed e o evento charge.chargeback é disparado. O processamento é manual.

// Sem corpo na requisição
POST /v1/charges/42/refund
Authorization: Bearer SEU_TOKEN

// Resposta 200
{
  "data": {
    "id": 42,
    "external_id": "meu-pedido-001",
    "status": "disputed",
    "amount_cents": 4890,
    "method": "pix"
  }
}
// Erros: 422 se status != paid (pending, failed, disputed) • 409 se paga com disputa anterior ainda registrada

Saques

Solicitar saque

POST /v1/payouts

Solicita saque PIX para sua chave cadastrada. Mínimo R$ 10,00. Taxa conforme seu plano.

Requisição

{
  "amount_cents": 50000,
  "pix_key": "financeiro@empresa.com.br"
}

Resposta 201

{
  "data": {
    "id": 7,
    "type": "cashout",
    "status": "processing",
    "amount_cents": 50000,
    "fee_cents": 150,
    "pix_key": "financeiro@empresa.com.br",
    "end_to_end_id": "E0...",
    "error_reason": null,
    "requested_at": "2026-06-20 19:00:00",
    "paid_at": null,
    "created_at": "2026-06-20 19:00:00",
    "updated_at": "2026-06-20 19:00:00"
  }
}
// status: processing | paid | failed
// end_to_end_id: ID E2E Bacen (null enquanto processing)
// paid_at: preenchido quando status=paid

Saques

Listar saques

GET /v1/payouts

Lista saques do mais recente ao mais antigo. Suporta paginação: page e limit (padrão 20, máx 100).

{
  "data": [
    {
      "id": 7,
      "type": "cashout",
      "status": "paid",
      "amount_cents": 50000,
      "fee_cents": 150,
      "pix_key": "financeiro@empresa.com.br",
      "end_to_end_id": "E02026...",
      "error_reason": null,
      "requested_at": "2026-06-20 18:00:00",
      "paid_at": "2026-06-20 19:05:00",
      "created_at": "2026-06-20 18:00:00",
      "updated_at": "2026-06-20 19:05:00"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Saldo

Consultar saldo

GET /v1/balance

Retorna o saldo da conta em centavos, com detalhes de liquidação e histórico acumulado.

// Resposta 200
{
  "data": {
  "available_cents": 46808,       // disponível para saque agora
  "pending_cents": 131030181,     // vendas aguardando liquidação
  "settling_cents": 0,            // em liquidação (boleto+cartão)
  "settling_boleto_cents": 0,     // em liquidação — boleto
  "settling_card_cents": 0,       // em liquidação — cartão
  "withdrawn_cents": 1200,        // total sacado historicamente
  "received_cents": 48659,        // total recebido historicamente
  "blocked_cents": 651,           // bloqueado (disputas/compliance)
  "debt_cents": 0,                // débito com a plataforma
  "boleto_settlement_days": 2,    // prazo liquidação boleto (D+N)
  "card_settlement_days": 30,     // prazo liquidação cartão (D+N)
  "debt_cents": 0,
  "settling_boleto_cents": 0,
  "settling_card_cents": 0,
  "received_cents": 0,
  "withdrawn_cents": 0,
  "blocked_cents": 0,
  "settling_transactions": [
    {
      "id": 62,
      "method": "boleto",
      "external_id": "tx_abc123",
      "amount_cents": 1000,
      "net_cents": 651,
      "payer_name": "João Silva",
      "description": null,
      "paid_at": "2026-06-20 10:05:00"
    }
  ],
  "currency": "BRL"
  }
}

Webhooks

Criar webhook

POST /v1/user/webhooks

Cadastra um endpoint para receber eventos em tempo real. A URL deve ser HTTPS. O campo secret é retornado apenas na criação — salve imediatamente.

Eventos disponíveis

charge.paidCobrança paga

charge.failedPagamento recusado

charge.refundedReembolso

charge.chargebackChargeback

charge.expiredExpirada

charge.pendingPendente

charge.createdCobrança criada

payout.paidSaque concluído

payout.failedSaque falhou

balance.updatedSaldo atualizado

payout.createdSaque criado

webhook.testTeste

💡

Use "events": ["*"] para receber todos os eventos automaticamente, incluindo futuros.

Requisição

{
  "url": "https://seusite.com/webhooks/chase",
  "name": "Producao",
  "events": ["charge.paid", "charge.failed"]
  // ou: "events": ["*"]
}

Resposta 201

{
  "data": {
    "id": 1,
    "url": "https://seusite.com/webhooks/chase",
    "events": ["charge.paid", "charge.failed"],
    "name": "Produção",
    "active": true,
    "secret": "whsec_abc123..."
    // secret exibido APENAS aqui — salve!
  }
}

Webhooks

Listar webhooks

GET /v1/user/webhooks

Lista todos os webhooks cadastrados. Retorna total, page, limit.

// Resposta 200
{
  "data": [
    {
      "id": 1,
      "url": "https://seusite.com/webhooks/chase",
      "name": "Producao",
      "events": ["charge.paid", "charge.failed"],
      "active": true,
      "success_count": 42,
      "fail_count": 1,
      "last_triggered": "2026-06-20 10:05:00",
      "created_at": "2026-06-01 09:00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Webhooks

Atualizar webhook

PUT /v1/user/webhooks/:id

Atualiza url, nome, eventos ou status ativo/inativo. Envie apenas os campos que deseja alterar.

// Exemplo: desativar webhook
PUT /v1/user/webhooks/1
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{ "active": false }

// Exemplo: atualizar eventos
{ "events": ["charge.paid", "payout.paid"] }

// Resposta 200
{
  "data": {
    "id": 1,
    "url": "https://seusite.com/webhooks/chase",
    "events": ["charge.paid", "payout.paid"],
    "active": false
  }
}

Webhooks

Remover webhook

DELETE /v1/user/webhooks/:id

Remove o webhook permanentemente.

DELETE /v1/user/webhooks/1
Authorization: Bearer SEU_TOKEN

// Resposta 200
{ "data": { "deleted": true } }

Webhooks

Testar endpoint

POST /v1/user/webhooks/:id/test

Dispara um evento webhook.test para o endpoint cadastrado. Sem corpo na requisição. Retorna {"data":{"ok":true|false,"status_code":200}} com o resultado da entrega.

Exemplo

POST /v1/user/webhooks/1/test
Authorization: Bearer SEU_TOKEN

// Sem corpo

Resposta 200

{
  "data": {
    "ok": true,         // false se servidor retornou erro
    "status_code": 200  // HTTP status do seu endpoint
  }
}

⏱️

Timeout e retry
Timeout: 8 segundos. Sem retry automático. Use este endpoint para reenviar manualmente após falhas. O evento webhook.test é seguro e não tem efeitos colaterais.

Webhooks

Assinatura HMAC

Cada requisição ao seu endpoint inclui o header X-Chase-Signature. Valide com HMAC-SHA256 usando o corpo bruto (não parseado) e o secret do webhook.

🔒

Checklist de segurança — obrigatório

Valide o HMAC antes de tudo — nunca processe sem verificar X-Chase-Signature. Use corpo bruto (Buffer / php://input), não JSON re-serializado.
Use comparação segura — timingSafeEqual (Node) / hash_equals (PHP) para evitar timing attacks.
Confira amount_cents no seu banco — nunca libere um pedido só pelo evento. Valide que o valor pago bate com o valor do pedido. Um atacante pode criar uma cobrança de R$ 0,01 e tentar reusar o payload em outro contexto.
Verifique o external_id — confirme que o pedido existe e ainda não foi processado (evita replay attack com payload legítimo capturado).
Responda em menos de 8 s — retorne HTTP 200 imediatamente e processe em background. Timeout marca o evento como falha.

Node.js (Express)

// IMPORTANTE: use express.raw() ANTES do express.json()
// app.use('/webhooks', express.raw({ type: '*/*' }));

const sig = "sha256=" + crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(req.body)  // Buffer com express.raw()
  .digest("hex");

// Header: X-Chase-Signature: sha256=<hex>
if (!crypto.timingSafeEqual(
  Buffer.from(sig),
  Buffer.from(req.headers["x-chase-signature"] ?? "")
)) return res.status(401).end();

PHP

$sig = "sha256=" . hash_hmac(
  "sha256",
  file_get_contents("php://input"),
  $webhookSecret
);

// Header: X-Chase-Signature: sha256=<hex>
if (!hash_equals(
  $sig,
  $_SERVER["HTTP_X_CHASE_SIGNATURE"] ?? ""
)) {
  http_response_code(401);
  exit;
}

Payload recebido no seu servidor

POST https://seusite.com/webhooks/chase
Content-Type: application/json
X-Chase-Signature: sha256=a3f2c1d8...
X-Chase-Event: charge.paid

{
  "event": "charge.paid",
  "data": {
    "id": 42,
    "external_id": "meu-pedido-001",
    "method": "pix",
    "status": "paid",
    "amount_cents": 4890,
    "fee_cents": 190,
    "net_cents": 4700,
    "discount_cents": 0,
    "description": "Pedido #123",
    "payer_name": "João Silva",
    "payer_document": "12345678900",   // apenas dígitos
    "pix_qr_code": "00020126...",
    "boleto_line": null,
    "boleto_url": null,
    "boleto_due": null,
    "paid_at": "2026-06-20 10:05:12",
    "created_at": "2026-06-20 10:01:00",
    "updated_at": "2026-06-20 10:05:12"
  }
}

Datas no horário de Brasília (UTC-3), formato YYYY-MM-DD HH:MM:SS (exceto boleto_due: apenas YYYY-MM-DD). Timeout: 8 s. Sem retry automático.

Referência

Códigos de erro

Erros sempre retornam {"error": {"message": "descrição"}}. Limite de 60 requisições/minuto por token — header X-RateLimit-Limit: 60. Ao exceder retorna 429.

HTTP	Significado
200	OK
201	Recurso criado com sucesso
400	Requisição malformada — JSON inválido ou campo inesperado
401	Não autenticado — token ausente ou inválido
402	Pagamento recusado pela adquirente
403	Conta sem permissão para esta operação
404	Recurso não encontrado
409	Conflito — `external_id` já utilizado. Reenvie com o mesmo `external_id` — idempotência garantida.
422	Validação falhou — campo inválido, valor fora do limite ou formato incorreto
429	Muitas requisições — aguarde e tente novamente. Resposta pode ser HTML (nginx), não JSON.
500	Erro interno do servidor
502	Falha na adquirente — tente novamente
503	Serviço indisponível — ex: boleto temporariamente fora do ar

🔄

Idempotência via external_id
Ao receber timeout ou erro de rede ao criar cobrança, reenvie com o mesmo external_id. Se já foi criada, a API retorna 409 em vez de duplicata. É seguro para retry.

Referência

Status das cobranças

Ciclo de vida de uma cobrança desde a criação até a conclusão.

pending→paidPIX/boleto confirmado

pending→failedPIX expirado ou recusado

pending→expiredBoleto vencido sem pagamento

paid→refundedEstorno confirmado

paid→disputedChargeback / disputa aberta

paid→chargebackChargeback finalizado

Referência rápida

pending  -> paid        // PIX/boleto confirmado
pending  -> failed      // PIX expirado ou recusado
pending  -> expired     // boleto vencido sem pagamento
paid     -> refunded    // estorno confirmado
paid     -> disputed    // chargeback / disputa aberta
paid     -> chargeback  // chargeback finalizado

// PIX pendente expira em ~24h (definido pelo banco)
// Boleto: vencimento configurado na geração

Documentaçãoda API

Introdução

Autenticação

Primeiros passos

Crie sua conta e obtenha o token

Crie sua primeira cobrança PIX

Renderize o QR Code

Configure webhooks para notificações

Criar cobrança

Parâmetros da requisição

Listar cobranças

Consultar cobrança

Reembolsar

Solicitar saque

Listar saques

Consultar saldo

Criar webhook

Eventos disponíveis

Listar webhooks

Atualizar webhook

Remover webhook

Testar endpoint

Assinatura HMAC

Códigos de erro

Status das cobranças

Documentação
da API