chasepay API v1
Minhas chaves

Guia de integração

Introdução

A API da Chase Pay é feita para integração servidor a servidor: você cria cobranças Pix, boleto e cartão, gera checkouts, consulta saldo, faz saques, acompanha contestações (MED) e recebe cada mudança por webhook assinado.

Visão geral

  • REST + JSON. Envie Content-Type: application/json. Respostas de sucesso vêm em {"data": …}.
  • Valores em centavos inteiros. 4890 = R$ 48,90. Nunca envie decimais.
  • Datas no horário de Brasília (UTC−3), no formato YYYY-MM-DD HH:MM:SS. O vencimento de boleto (boleto_due) vem só como YYYY-MM-DD.
  • Sem ambiente de teste separado. Toda chamada é real. Para testar, use o valor mínimo e um external_id que identifique o teste.

Base URL

https://api.chasepay.com.br

Todas as rotas desta documentação começam com /v1. Chame a API somente do seu servidor: a chave dá acesso total à conta.

Formato das respostas

{
  "data": { "id": 42, "status": "pending", "amount_cents": 4890 }
}
{
  "error": { "message": "Campo obrigatório: amount_cents" }
}

Listas trazem os itens em data; as paginadas (cobranças, saques, clientes) trazem também total, page e limit. Veja Códigos de erro para cada status HTTP.

Ordem recomendada de leitura

  1. AutenticaçãoCrie a chave no painel e guarde no servidor.
  2. Depósitos ou Checkout nativoEscolha entre cobrar pela API ou mandar o comprador para a página pronta da Chase.
  3. Webhooks e assinaturaReceba a confirmação no seu servidor e valide a assinatura antes de liberar o pedido.
  4. Saques e MEDMovimente o saldo e acompanhe contestações.

Integrar com IA

No canto direito: Abrir no ChatGPT e Abrir no Claude abrem a conversa já apontando para esta documentação; Usar no Cursor copia tudo para você colar no chat do editor. Os três também copiam a documentação inteira, caso a IA não consiga abrir o link. Revise o código gerado antes de usar em produção.

Integre meu backend com a API da Chase Pay usando a documentação colada.
- Chave em variável de ambiente CHASE_API_KEY, nunca no navegador.
- Valores sempre em centavos; external_id único por pedido.
- Confirme pagamento só por webhook com assinatura X-Chase-Signature válida
  ou consultando GET /v1/transactions/by-external/{external_id}.
- Em timeout, consulte antes de tentar de novo.

Suporte

Dúvidas de integração: suporte@chasepay.com.br ou WhatsApp (35) 92002-5347. Informe o external_id e o horário da chamada — nunca envie a chave de API.

Guia de integração

Autenticação

Toda chamada leva o header Authorization: Bearer {sua_chave}. Não existe OAuth nem token temporário: a chave vale até ser revogada.

Criar a chave

  1. Abra o painelEm Integrações → API, toque em Nova credencial e dê um nome (ex.: “Loja produção”).
  2. Copie o segredo na horaO segredo aparece uma única vez. Depois, o painel mostra só o nome, o identificador público (ck_live_…) e o último uso.
  3. Guarde no servidorUse variável de ambiente ou cofre de segredos. Nunca coloque no front-end, no app, em repositório ou em log.

Várias chaves

  • Cada conta pode ter até 10 chaves ativas. Use uma por sistema (loja, ERP, automação) para revogar só a que precisar.
  • Criar uma chave nova não cancela as antigas.
  • Toda chave tem o mesmo acesso: cobranças, saques, webhooks e MED da conta.
  • Cada chave vale 365 dias a partir da criação. Anote a data e troque antes de vencer: crie a nova, atualize seus sistemas e só então apague a antiga.

Trocar a senha revoga todas as chaves

Ao alterar ou redefinir a senha da conta, todas as chaves de API são revogadas por segurança. Crie novas chaves e atualize seus sistemas logo em seguida.

Erros de autenticação

HTTPMensagemO que fazer
401Não autenticado.Header ausente, chave que não existe ou chave vencida (365 dias). Confira se enviou o segredo completo, sem espaços, depois de Bearer .
401API key invalida.A chave foi apagada ou o segredo não confere (ex.: segredo antigo depois de um reset).
401API key revogada.A chave foi revogada pela troca de senha da conta. Crie outra.
403Conta pendente de aprovação. Aguarde a análise do seu cadastro.A conta ainda está em análise. Aguarde a aprovação.
403Conta bloqueada / Conta suspensa.Fale com o suporte.

Conferir de quem é a chave

Use para confirmar que a chave configurada no seu sistema é a da conta certa. A resposta mostra o nome da conta e o CPF ou CNPJ do lojista — nunca um número interno.

{
  "data": {
    "account": {
      "name": "Loja Exemplo Ltda",
      "trading_name": "Loja Exemplo",
      "document": "12.345.678/0001-90",
      "document_type": "CNPJ",
      "email": "financeiro@lojaexemplo.com.br",
      "status": "active",
      "kyc_status": "approved"
    },
    "key": { "name": "Loja produção", "client_id": "ck_live_9f2c4e1a7b3d5f6e8a0b1c2d" }
  }
}
  • key vem quando a chamada é feita com chave de API: é o nome que você deu à chave e o identificador público dela (o segredo nunca volta).
  • status: active, pending, suspended ou blocked. kyc_status: approved, pending ou rejected.
  • Se o nome ou o documento não forem os esperados, a chave é de outra conta: troque no seu sistema.

Trocar a chave sem parar a operação

  1. Crie a nova chaveNo painel ou por POST /v1/user/api-keys. A antiga continua funcionando.
  2. Atualize seus sistemasTroque a variável CHASE_API_KEY e reinicie os serviços.
  3. Confira o usoEm GET /v1/user/api-keys, o last_used_at da nova deve mudar e o da antiga parar.
  4. Apague a antigaDELETE /v1/user/api-keys/{id}.

Gerenciar chaves pela API

GET/v1/user/api-keys
{
  "data": [
    { "id": 31, "name": "Loja produção", "client_id": "ck_live_9f2c4e1a7b3d5f6e8a0b1c2d", "last_used_at": "2026-11-16 10:05:12", "created_at": "2026-01-20 14:00:00" }
  ]
}

O segredo nunca aparece na lista, só o nome, o identificador público e o último uso.

POST/v1/user/api-keys
{
  "data": { "id": 32, "name": "ERP", "client_id": "ck_live_1a2b3c4d5e6f7a8b9c0d1e2f", "secret": "…", "created_at": "2026-11-16T10:30:00-03:00" }
}

secret aparece só aqui. Até 10 chaves ativas por conta (422 “Limite de 10 chaves de API por conta.”).

DELETE/v1/user/api-keys/{id}

Apaga a chave na hora. Resposta: {"data": {"deleted": true}}. Cuidado para não apagar a chave que está fazendo a chamada.

POST/v1/user/api-keys/{id}/reset

Gera um segredo novo para a mesma chave e devolve {"id", "secret"}. O segredo antigo para de funcionar na hora — use só em caso de vazamento. Para troca planejada, prefira os passos acima.

Por que não é OAuth?

A integração é entre o seu servidor e a Chase, sem um usuário clicando em “autorizar”. Uma chave por sistema, guardada no servidor e enviada por HTTPS, é mais simples e tem a mesma segurança na prática: não há token para renovar a cada hora nem fluxo de redirecionamento. A proteção vem de três regras: a chave nunca sai do servidor, cada sistema tem a sua, e você apaga na hora a que vazar.

A chave movimenta dinheiro

Com ela é possível criar cobranças, pedir saques e reembolsos. Se suspeitar de vazamento, apague a chave no painel imediatamente e crie outra.

Guia de integração

Primeiros passos

Em quatro chamadas você cria uma cobrança Pix, mostra o QR Code e recebe a confirmação no seu servidor.

  1. Crie a chave de APINo painel, em Integrações → API. Guarde o segredo em CHASE_API_KEY no servidor. Veja Autenticação.
  2. Cadastre o webhookUma vez só, com a URL HTTPS do seu servidor. Guarde o secret que volta na resposta.
  3. Crie a cobrançaCom o valor em centavos e o external_id do seu pedido.
  4. Mostre o Pix e espere o webhookExiba pix_qr_code (copia e cola) e o QR Code. Libere o pedido quando chegar charge.paid com assinatura válida.

1. Cadastrar o webhook

A resposta traz secret (whsec_…) uma única vez. É com ele que você valida a assinatura.

2. Criar a cobrança Pix

{
  "data": {
    "id": 90412,
    "external_id": "pedido-1001",
    "status": "pending",
    "method": "pix",
    "amount_cents": 4890,
    "fee_cents": 342,
    "net_cents": 4548,
    "pix_qr_code": "00020101021226…6304A1B2",
    "pix_qr_url": "https://api.chasepay.com.br/v1/qr/3f9c…",
    "description": "Pedido 1001",
    "payer_name": "Amanda Carvalho",
    "paid_at": null,
    "created_at": "2026-11-16 10:00:00"
  }
}

3. Mostrar ao comprador

  • pix_qr_code é o copia e cola. Mostre com um botão “Copiar”.
  • pix_qr_url é a imagem PNG do QR Code. Use direto num <img> na tela do comprador — não baixe pelo seu servidor, porque o primeiro acesso à imagem é registrado como o do comprador.

4. Confirmar o pagamento

Quando o comprador paga, a Chase envia charge.paid para o seu webhook. Valide a assinatura, confira o external_id e o amount_cents no seu banco e só então libere o pedido. Se o webhook não chegar, consulte:

Testando em produção

Não há ambiente de teste. Use R$ 10,00 (o mínimo do Pix) e um external_id como teste-001. Pague com o seu próprio banco e acompanhe o webhook chegar.

Guia de integração

Limites, taxas e idempotência

Como evitar cobrança ou saque em dobro quando a rede falha, quantas chamadas a API aceita e como consultar as taxas e limites da sua conta.

external_id: um por pedido

  • Envie o ID do seu pedido em external_id (até 64 caracteres, sem espaço, # ou /). Sem ele, a Chase gera um tx_….
  • Repetir um external_id já usado devolve 409 — não devolve a cobrança original. Busque-a com GET /v1/transactions/by-external/{external_id}.
  • O external_id fica reservado mesmo se a cobrança falhar. Para uma nova tentativa do mesmo pedido, use um sufixo (pedido-1001-2).
  • Não existe header Idempotency-Key na Chase.
// 1. Não repita o POST na hora: a cobrança pode ter sido criada.
// 2. Consulte pelo external_id original:
const res = await fetch(`https://api.chasepay.com.br/v1/transactions/by-external/${externalId}`, {
  headers: { Authorization: `Bearer ${process.env.CHASE_API_KEY}` }
});
if (res.status === 404) {
  // não foi criada: pode tentar de novo com o mesmo external_id
} else {
  const { data } = await res.json(); // já existe: use esta cobrança
}

Saques não têm external_id

Se um POST /v1/payouts der timeout, consulte GET /v1/payouts antes de pedir de novo. Repetir às cegas pode gerar dois saques.

Limites de chamadas

LimiteValorResposta
Requisições por IP30 por segundo (picos de até 60)429 em HTML, não JSON
Cobranças por conta20 por minuto e 1.500 por hora429
Cobranças por documento do comprador30 por hora429
Mesma cobrança repetidaMesmo comprador, valor e método em 30 segundos, depois de uma cobrança criada. Só não contam erros barrados antes de criar a cobrança (campo obrigatório faltando, invalid_device_data). Cartão recusado ou invalid_payment_data já criam a cobrança (como failed): espere 30 s ou mude valor/comprador. A trava usa customer.document.429 “Cobrança duplicada detectada”
Teste de webhook5 por minuto429

Ao receber 429, espere alguns segundos e tente de novo com pausa crescente (1 s, 2 s, 4 s…). O header X-RateLimit-Limit que aparece nas respostas é fixo e não indica quanto falta.

Limites de valor

MétodoMínimoMáximo por cobrança
PixR$ 10,00 (1000)R$ 2.000,00 (200000)
BoletoR$ 1,00 (100)R$ 100.000,00 (10000000)
CartãoR$ 1,00 (100)R$ 100.000,00 (10000000)

Algumas contas têm teto menor por venda no Pix ou mínimo maior no boleto. Nesses casos a API responde 422 com o valor exato na mensagem.

Taxas da sua conta

GET/v1/fees

As taxas que valem para a sua conta agora, já com qualquer condição especial negociada. Use para mostrar o valor líquido no seu sistema em vez de fixar porcentagens no código.

{
  "data": {
    "pix":    { "pct": 6.99, "fixed_cents": 0, "custom": true },
    "boleto": { "pct": 2.5,  "fixed_cents": 300, "custom": false },
    "card": {
      "pct": 6.3, "fixed_cents": 270, "custom": false,
      "installment_rates": { "1": 6.3, "2": 9.1, "3": 10.2, "12": 18.0 }
    },
    "withdrawal": { "pct": 0, "fixed_cents": 370 },
    "card_link_normal": { "pct": 5.99, "fixed_cents": 380, "settlement_days": 7, "installments": 1 },
    "card_link_nitro":  { "pct": 7.99, "fixed_cents": 440, "settlement_days": 2, "installments": 1 },
    "min_charge_cents": 1000,
    "card_enabled": true,
    "boleto_enabled": true
  }
}
CampoDescrição
pix / boleto / cardpct (porcentagem) + fixed_cents (fixo em centavos) por venda paga. custom: true = condição própria da sua conta.
card.installment_ratesTaxa total por número de parcelas ("1" a "12"), em %.
withdrawalTaxa de cada saque.
card_link_normal / card_link_nitroCartão pago na página segura (link de cartão, cartão do checkout e cartão pela API): taxa, prazo em dias úteis e máximo de parcelas.
card_enabled / boleto_enabledSe a conta pode receber cartão e boleto.

Taxa da venda = round(amount_cents × pct / 100) + fixed_cents. O valor exato de cada venda sempre vem em fee_cents e net_cents.

Limites da sua conta

GET/v1/user/limits

Mínimo, máximo e limite diário de saque, quanto já foi usado hoje e se o PIN está ativo. Consulte antes de pedir um saque para evitar recusa.

{
  "data": {
    "cashout_enabled": true,
    "pin_active": true,
    "min_withdrawal_cents": 10000,
    "max_withdrawal_cents": 1500000,
    "daily_limit_cents": 1500000,
    "daily_used_cents": 250000,
    "daily_withdrawal_count": 1,
    "withdrawal_pct": 0,
    "withdrawal_fix_cents": 370,
    "pix_settlement_days": 0,
    "card_settlement_days": 30,
    "card_settlement_business_days": true
  }
}
CampoDescrição
cashout_enabledSe a conta pode sacar agora.
pin_activeSe o saque exige o campo pin.
min_withdrawal_cents / max_withdrawal_centsMenor e maior saque permitido.
daily_limit_cents / daily_used_centsLimite do dia e quanto já foi usado (dia no horário de Brasília). Disponível hoje = limite − usado.
daily_withdrawal_countMáximo de saques por dia (0 = sem limite). Não é a contagem dos saques já feitos.
withdrawal_pct / withdrawal_fix_centsTaxa de saque.
pix_settlement_days / card_settlement_daysPrazo até a venda virar saldo disponível (cartão em dias úteis quando card_settlement_business_days é true).

Guia de integração

Segurança

O que a Chase garante do lado dela e o que você precisa fazer do seu lado para a integração não virar porta de entrada para fraude.

O que a API nunca permite

TentativaO que acontece
Mudar o próprio saldo, taxa, limite, status da conta, KYC ou cargo enviando esses camposOs campos são ignorados. Saldo, taxas, limites e travas só mudam pela equipe da Chase.
Forjar ou editar o token para “subir de cargo”Todo token é assinado pelo servidor; qualquer alteração invalida a assinatura (401). O cargo vem sempre do cadastro, nunca do token.
Usar uma chave de API em rotas administrativas403 “Chaves de API não acessam rotas administrativas.” Mesmo a chave de um administrador só acessa as rotas de seller.
Mandar pedidos para a área administrativa a partir desta documentação, de outro site ou de um iframe403. A área administrativa só aceita o painel com login; a documentação nem consegue chamar a API pelo navegador.
Ler ou alterar cobrança, saque, produto, checkout, cupom, webhook ou contestação de outra contaTudo é filtrado pela conta da chave: o recurso de outra conta responde 404.
Reabrir uma contestação (MED) já encerrada409 “Contestação já concluída.”
Cobrar com recebimento desativado ou sacar com saque desativado / KYC pendente403. Vale para cobrança, saque, comissão de indicação e pagamentos.
Sacar mais do que o disponível ou repetir saque ao mesmo tempo422 saldo insuficiente / 409 outra operação em andamento. Com PIN na conta, o saque exige o pin; PIN errado repetido bloqueia novas tentativas (429).
Cobrar duas vezes o mesmo pedidoexternal_id repetido → 409; mesma cobrança (comprador + valor + método) em 30 s → 429.

Sua chave de API

  • Só no servidor. Nunca em app, site, front-end, repositório, log ou ferramenta de análise. Quem tem a chave cria cobranças e pede saques na sua conta.
  • Uma chave por sistema (loja, ERP, automação): se uma vazar, você apaga só ela.
  • Vazou? Apague no painel ou por DELETE /v1/user/api-keys/{id} na hora. Trocar a senha da conta revoga todas as chaves.
  • Validade de 365 dias. Troque antes de vencer (veja troca de chave).
  • Ative o PIN de saque no painel: com ele, uma chave vazada não basta para sacar nem pagar Pix/boleto. Depois de 5 PINs errados em 15 minutos (ou 10 no dia), novas tentativas recebem 429 até a janela passar. O saque de comissão de indicação ainda não pede PIN.

Webhooks

Do lado da Chase:

  • Envio só para HTTPS com certificado válido; endereços internos/privados são recusados no cadastro, na alteração e no envio; redirecionamentos não são seguidos.
  • Cada endpoint tem um segredo próprio (whsec_…) e cada envio é assinado com HMAC-SHA256.
  • Cada envio leva X-Chase-Timestamp e X-Chase-Signature-V2, que amarram a assinatura ao horário do envio.

Do seu lado:

  1. Valide a assinaturaCom o corpo bruto e comparação em tempo constante. Veja Verificando a assinatura.
  2. Recuse avisos antigosCom X-Chase-Signature-V2, rejeite quando o horário estiver a mais de 5 minutos do seu relógio — um aviso capturado não pode ser reenviado depois.
  3. DedupliqueGuarde o id (evt_…) de cada aviso processado e ignore repetidos.
  4. Confirme na API antes de liberarPara pedidos de valor alto, consulte GET /v1/transactions/by-external/{external_id}: o status e o valor vêm direto da Chase.
  5. Segredo vazou?Gere outro com POST /v1/user/webhooks/{id}/rotate-secret e atualize o seu servidor; o antigo deixa de valer na hora.

Cartão

  • Se você usa cartão no seu site, seu servidor recebe o número do cartão: não grave número, CVV ou validade e avalie o PCI DSS. Sem essa estrutura, use o Checkout nativo, onde o cartão nunca passa por você.
  • O valor da cobrança sai sempre do seu servidor, nunca do navegador.
  • Nunca libere um pedido pela mensagem da tela do banco nem pelo retorno do navegador: só por webhook validado ou consulta à API.

Dados do comprador

Os avisos e consultas trazem dados pessoais do comprador (nome, documento, e-mail). Guarde só o necessário, proteja o acesso e siga a LGPD. Campos que não estão nesta documentação podem aparecer nas respostas por compatibilidade: não dependa deles.

Encontrou uma falha?

Mande os detalhes para suporte@chasepay.com.br com o assunto “Segurança”. Não teste em contas de outras pessoas e não divulgue antes da correção.

Receber

Depósitos: Pix e boleto

Uma chamada cria a cobrança e devolve o copia e cola e o QR Code do Pix, ou a linha digitável e o PDF do boleto. A confirmação chega por webhook.

Criar cobrança

POST/v1/charges

Responde 201 com a cobrança em pending. 201 não é pagamento aprovado: espere o webhook ou consulte o status.

Parâmetros

CampoDescrição
methodobrigatóriostringpix, boleto ou card (minúsculo). Cartão: veja Cartão no seu site.
amount_centsobrigatóriointegerValor em centavos. Pix: 1.000 a 200.000. Boleto e cartão: 100 a 10.000.000.
external_idrecomendadostringID do seu pedido, até 64 caracteres, único por conta. Veja Idempotência.
descriptionopcionalstring3 a 255 caracteres, aparece para o comprador. No Pix, o padrão é “Cobrança Pix”. No boleto, use algo específico (“Pedido 1001”) — textos genéricos como “pagamento” são recusados.
customer.namerecomendadostringNome completo do comprador.
customer.documentrecomendadostringCPF (11 dígitos) ou CNPJ (14), só números.
customer.emailopcionalstringE-mail válido do comprador.
customer.phoneopcionalstringTelefone com DDD.
payer_name, payer_document, payer_phoneopcionalstringAtalhos para os mesmos dados, sem o objeto customer. Telefone com 10 ou 11 dígitos.

Envie sempre os dados do comprador

Sem nome e documento do comprador, a cobrança sai com os dados da sua própria conta. Isso atrapalha a conciliação e a defesa em caso de MED.

Bloqueio da contaResposta
Recebimento desativado pela Chase403 “Recebimentos desativados para esta conta. Fale com o suporte.”
Cartão ou boleto não liberados403 “Pagamento com cartão não está disponível.” / “Pagamento via boleto não está disponível.” Para emitir boleto (normal ou proposta), o boleto precisa estar ativo na sua conta.
Conta não ativa ou cadastro (KYC) não aprovado403 “Checkout temporariamente indisponível.” (vale também para a API)
Pagamentos pausados pela plataforma503 “Plataforma temporariamente indisponível para novos pagamentos.”
Método pausado pela plataforma503 “Este método de pagamento está temporariamente indisponível.”
Conta pendente, bloqueada ou suspensa403 (veja Autenticação)

Boleto

Campos da resposta

CampoDescrição
idintegerID interno da cobrança.
external_idstringO seu ID (ou o tx_… gerado).
statusstringVeja Status das cobranças.
amount_cents / fee_cents / net_centsintegerValor cobrado, taxa da Chase e quanto entra no seu saldo.
pix_qr_codestring | nullPix copia e cola.
pix_qr_urlstring | nullImagem PNG do QR Code. Mostre direto ao comprador.
boleto_line / boleto_url / boleto_duestring | nullLinha digitável, PDF e vencimento (YYYY-MM-DD). Só nas cobranças de boleto.
payer_name / payer_documentstring | nullQuem pagou (no Pix, preenchido pelo banco depois do pagamento).
paid_at / created_at / updated_atstringHorário de Brasília.
{
  "data": {
    "id": 90413,
    "external_id": "pedido-1002",
    "status": "pending",
    "method": "boleto",
    "amount_cents": 19990,
    "fee_cents": 400,
    "net_cents": 19590,
    "pix_qr_code": null,
    "boleto_line": "23793.38128 60000.000003 00000.000400 1 99990000019990",
    "boleto_url": "https://…/boleto.pdf",
    "boleto_due": "2026-11-19",
    "created_at": "2026-11-16 10:00:00"
  }
}

Se boleto_line ou boleto_url vierem null, não mostre o boleto: consulte a cobrança de novo em alguns segundos.

Validade do Pix

O QR Code vale por um tempo limitado, que depende da conta (de alguns minutos a 1 dia). Quando expira sem pagamento, conforme a conta a cobrança vira failed (com charge.failed) ou continua pending — não espere o status mudar. Trate como expirada depois do prazo do seu checkout e, se o comprador voltar, gere uma nova. Para cobrar de novo, crie outra cobrança com novo external_id. Boleto vencido sem pagamento não gera evento: trate pelo vencimento.

Listar cobranças

GET/v1/transactions
QueryDescrição
statusFiltra por status (ex.: paid, pending, failed).
methodpix, boleto ou card.
qBusca no external_id, nome do pagador ou descrição.
from / toPeríodo pela data de criação, YYYY-MM-DD.
movement_from / movement_toPeríodo pela data do pagamento (ou criação, se não pago).
periodAtalho: hoje, 7, 30 ou 90 dias.
page / limitPaginação. Padrão 20, máximo 500 por página.

Resposta: {"data": [...], "total", "page", "limit"}, do pagamento mais recente para o mais antigo. A lista também mostra lançamentos de estorno e ajuste da conta (method refund, chargeback, adjustment).

Consultar cobrança

GET/v1/transactions/by-external/{external_id}

Use sempre o external_id original — funciona até quando ele só tem números. A rota antiga GET /v1/transactions/{id} continua existindo: com número, busca pelo ID interno; com texto, pelo external_id. Consultar também atualiza o status junto ao banco, então é seguro usar para conciliar.

Detalhes da transação

GET/v1/transactions/{id}/details

Informações extras de uma venda: cartão, prazo de liberação e origem. {id} é o ID interno (número).

CampoDescrição
card_brand / card_last4 / installmentsBandeira, final do cartão e parcelas (só cartão).
authorization_codeCódigo de autorização do cartão, quando houver.
end_to_end_id / payer_bankIdentificador do Pix e banco de quem pagou, quando disponíveis.
release_atQuando o valor vira saldo disponível.
settlement_statescheduled (agendado), released (liberado), early (antecipado), not_paid ou unknown.
settlement_days / settlement_business_daysPrazo de liberação e se é em dias úteis.
source_type / source_name / source_domainOrigem da venda (ex.: checkout) e o site, quando informado em source_site. Em cobrança pela API sem source_site, vem null.
checkout_nameNome do checkout, se a venda veio de um.
dispute_*Em lançamentos de contestação: motivo, status, valor bloqueado e comprador.

A rota traz só os campos acima e alguns de identificação (documento do pagador mascarado). Ignore campos que não estão nesta lista.

Campos extras da cobrança

CampoDescrição
source_siteopcionalstringDomínio do seu site onde a venda aconteceu (ex.: sualoja.com.br). Aparece na origem da venda. Precisa ser um domínio público válido, senão 422.
product_idopcionalintegerSe description vier vazia, usa o nome deste produto seu.
boleto_dueopcionalstringVencimento do boleto, YYYY-MM-DD. Nem toda conta aceita vencimento personalizado: confira boleto_due na resposta.
checkout_slugopcionalstringCobra pelo preço de um checkout seu. Veja abaixo.

Cobrar pelo preço de um checkout

Com checkout_slug, a Chase recalcula valor e descrição a partir do produto do checkout, somando o order bump ("bump": true) e aplicando o cupom (coupon_code). Útil para usar o seu próprio formulário com os preços e cupons do painel.

  • amount_cents continua obrigatório no corpo, mas o valor final é o calculado pelo checkout. Confira amount_cents na resposta.
  • O checkout precisa ser da sua conta. Checkouts em moeda estrangeira ou de link de cartão não aceitam esta forma (409).
  • O cupom vale sobre o total com o order bump. Exemplo testado: produto R$ 25,00 + bump R$ 3,90 − cupom 10% = 2601. O desconto fica registrado em discount_cents e conta um uso do cupom (respeita max_uses), igual à venda feita na página do checkout.
  • A descrição vira o nome do produto do checkout.
  • Cupom inválido, vencido ou esgotado: 422 “Cupom inválido ou expirado.” / “Cupom esgotado.”.

Pedir reembolso

POST/v1/charges/{id}/refund

Sem corpo. {id} aceita o ID interno ou o external_id. Só funciona em cobrança paid.

O reembolso é analisado pela Chase

O pedido abre uma contestação, a cobrança passa para disputed, o valor líquido fica bloqueado e o evento charge.disputed é enviado. Quando a devolução é concluída, a cobrança vira refunded e chega charge.refunded. Não há reembolso parcial. Se a cobrança já teve contestação ou estorno (mesmo encerrado), a resposta é 409 “Ja existe um estorno/disputa em andamento para esta transacao.”; se a cobrança não estiver paga, 422 “Apenas transações pagas podem ser estornadas.”.

Clientes

GET/v1/user/customer-list

Todos os compradores da conta, com resumo de compras.

{
  "data": [
    {
      "id": 5512,
      "name": "Amanda Carvalho",
      "email": "amanda@example.com",
      "document": "52998224725",
      "phone": "11999999999",
      "city": "São Paulo",
      "state": "SP",
      "tx_count": 3,
      "paid_tx_count": 2,
      "spent_cents": 39400,
      "pending_cents": 4890,
      "last_purchase": "2026-11-15 10:05:12",
      "last_method": "pix",
      "last_status": "paid",
      "created_at": "2026-10-02 09:12:44"
    }
  ]
}

Vem a base inteira, sem paginação

Inclui também quem pagou Pix sem cadastro (IDs a partir de 900000). Em contas grandes a resposta é pesada (testado: 66 mil linhas em ~4 s). Para telas e buscas, use a rota paginada abaixo.

Clientes paginados

GET/v1/user/customers-summary
QueryDescrição
page / limitPaginação. limit de 10 a 100 (padrão 50).
qBusca por nome, e-mail ou documento.
periodtoday, yesterday, 30 (padrão), 90 ou 365 (ano atual, desde 1º de janeiro). Filtra pela data de cadastro do cliente: sem ele vêm só os últimos 30 dias.
statusativo, pendente ou inativo.
customer_idDetalhe de um cliente, com as últimas compras. Nesse caso a resposta vem como {"data": {"customers": [...], "total": 1, "summary": ...}}.

Resposta: {"data": [...], "total", "page", "limit", "summary"}. Cada cliente traz tx_count, paid_count, pending_count, refund_count, failed_count, total_paid_cents, total_charged_cents e last_paid. summary resume a conta (clientes e pedidos pagos, total recebido). Lista só clientes com cadastro (respondeu em menos de 1 s no teste).

Receber

Checkout nativo

A página de pagamento pronta da Chase. Você cria pela API (ou pelo painel), manda o comprador para o link e recebe a confirmação por webhook. Cartão, Pix, parcelas e segurança ficam por conta da Chase.

Recomendado: crie pelo builder do painel

Em Links de checkout, o builder cria o checkout em três modelos — Brasil (Pix e/ou cartão, em reais), Pix recorrente (assinatura) e Internacional (outra moeda) — com a identidade visual da sua marca e prévia ao vivo. Esta página mostra a criação pela API; veja também Checkout Brasil pela API.

POST /v1/user/products→POST /v1/user/checkouts→checkout.chasepay.com.br/pay/{slug}→webhook charge.paid

1. Criar o produto

POST/v1/user/products
CampoDescrição
nameobrigatóriostringNome que o comprador vê, até 255 caracteres.
price_centsobrigatóriointegerPreço em centavos, de 100 (R$ 1,00) a 99.999.900.
activeopcionalbooleanProduto disponível para venda.
description, image_url, skuopcionalstringDescrição, imagem (HTTPS) e código interno (letras, números, ., -, _; único na conta).

Guarde o data.id da resposta.

2. Criar o checkout

POST/v1/user/checkouts
CampoDescrição
nameobrigatóriostringNome interno do checkout.
product_idsobrigatórioarrayIDs dos seus produtos (criados no passo 1).
settings.pixopcionalbooleanAceitar Pix.
settings.cardopcionalbooleanAceitar cartão de crédito (a conta precisa ter cartão liberado).
settings.ui.installments / parcelasMaxopcionalintegerAceito e guardado. No cartão à vista do checkout, o comprador escolhe as parcelas na página segura de cartão (veja Cartão no checkout).
settings.ui.customerPaysInterestopcionalbooleanAceito e guardado. Os juros do parcelamento são pagos pelo comprador na página segura de cartão.
settings.ui.redirecionar + urlRedirectopcionalLeva o comprador para a sua página (HTTPS) depois do pagamento.
slugopcionalstringFinal do link. Se não enviar, a Chase gera a partir do nome.

Ative pelo menos um meio (pix ou card); sem nenhum, a API responde 422 “Ative pelo menos um meio de pagamento disponível para este checkout.”

Use settings.card e settings.pix

Exemplos antigos usavam settings.advanced.payCard/payPix. Esses campos são guardados, mas não ligam o meio de pagamento.

3. Mandar o comprador para o link

<a href="https://checkout.chasepay.com.br/pay/curso-completo-a1b2c" rel="noopener">Pagar com segurança</a>
  • Use o data.slug da resposta do passo 2.
  • Abra em navegação normal (link ou redirecionamento). Não coloque o checkout dentro de iframe e nunca ponha a chave de API no link.
  • O mesmo link serve para vários compradores. Para um pedido específico, crie um checkout por pedido.

4. Confirmar a venda

Cada venda gera uma cobrança com external_id criado pela Chase (tx_…) e os dados que o comprador preencheu. Você recebe charge.pending quando ele começa a pagar e charge.paid quando o pagamento é aprovado. Ligue a venda ao seu pedido pelo e-mail/documento do comprador ou usando um checkout por pedido.

Assinatura mensal no cartão

{
  "card": true,
  "pix": false,
  "ui": {
    "recurringCardEnabled": true,
    "recurringBillingDay": 10,
    "recurringCycles": 12
  }
}

Dia de cobrança de 1 a 28 e duração de 2 a 24 meses. Na assinatura, o cartão é sempre à vista (1x) e o comprador aceita a recorrência no checkout. Assinatura não é parcelamento.

Listar e cancelar assinaturas

GET/v1/user/subscriptions

Lista as assinaturas da conta (cartão e Pix), com id, payment_method, amount_cents, status, next_scheduled_at e o external_id da primeira cobrança. Com ?refresh=1, atualiza os status antes de responder (mais lento).

POST/v1/user/subscriptions/{id}/cancel

Mande o payment_method que veio na lista (pix ou card). Resposta: {"data": {"cancelled": true}}. Assinatura já encerrada também responde cancelled: true. Se vier 502 “Cancelamento solicitado; aguardando confirmação…”, consulte a lista de novo em instantes antes de repetir.

Cupons de desconto

Cupons valem para todos os checkouts da conta. Crie o cupom e ligue o campo de cupom no checkout.

POST/v1/user/coupons
CampoDescrição
codeobrigatórioO código que o comprador digita. Maiúsculas e minúsculas são iguais.
typeobrigatóriopercent (porcentagem) ou fixed (valor fixo).
valueobrigatóriopercent: de 1 a 100. fixed: desconto em centavos (1000 = R$ 10,00).
max_usesopcionalQuantas vezes pode ser usado no total. Sem ele, ilimitado.
expires_atopcionalValidade, YYYY-MM-DD HH:MM:SS (Brasília).
activeopcionalPausar sem apagar: false.

No checkout, mostre o campo com "ui": {"couponEnabled": true}. Também: GET /v1/user/coupons, PATCH e DELETE /v1/user/coupons/{id}. O desconto nunca deixa a venda abaixo de R$ 0,01.

Códigos são únicos na conta

Código repetido (maiúsculas e minúsculas contam como iguais) responde 409 “Já existe um cupom com este código.”, inclusive ao renomear.

Order bump

Uma oferta extra marcável na própria página de pagamento (“Adicione também…”). Use outro produto seu:

{
  "ui": {
    "bumpAtivo": true,
    "bumpProdutoId": 124,
    "bumpPrecoPromo": 19.90
  }
}
  • bumpProdutoId: ID do produto do bump (diferente do produto principal). A Chase inclui ele em product_ids automaticamente.
  • bumpPrecoPromo (opcional): preço especial do bump em reais (ex.: 19.90). Sem ele, vale o preço do produto.
  • Cores e posição (antes ou depois do pagamento) ficam no construtor do checkout no painel.

Upsell (oferta depois da compra)

Depois do pagamento aprovado, o comprador vê uma oferta de outro produto:

{
  "ui": {
    "upsellAtivo": true,
    "upsellProdutoId": 125,
    "upsellTitulo": "Leve a mentoria com 50% de desconto",
    "upsellDescricao": "Oferta válida só nesta página."
  }
}

Sem título e descrição, a Chase mostra um texto padrão com o nome do produto.

Mensagem de obrigado e retorno

{
  "ui": {
    "thankYouMessage": "Pronto! O acesso chega no seu e-mail em até 5 minutos.",
    "redirecionar": true,
    "urlRedirect": "https://sualoja.com.br/obrigado"
  }
}

thankYouMessage aparece na tela de confirmação. Com redirecionar, o comprador vai para a sua página (HTTPS) depois do pagamento. Não confirme a venda por esse retorno: use o webhook.

Cartão no checkout

Quando o comprador escolhe cartão, o checkout abre a página segura de cartão numa nova aba, com o valor final (produto + order bump − cupom). Ele digita o cartão e escolhe as parcelas lá, com juros pagos por ele; a aba do checkout acompanha e mostra a confirmação. Não é preciso mudar nada na sua integração: a venda continua com external_id tx_… e os webhooks charge.pending e charge.paid.

  • Taxa e prazo: os do link de cartão — card_link_normal ou card_link_nitro em GET /v1/fees, conforme a opção Nitro do painel.
  • Assinatura no cartão e cartão internacional continuam com o campo de cartão na própria página.

Checkout Brasil pela API (modelo do builder)

O mesmo checkout que o builder cria na opção Brasil: preço fixo em reais, Pix pago na própria página (QR Code e copia e cola) e/ou cartão na página segura, com a identidade visual que você escolher.

CampoDescrição
settings.ui.webMarketBuilder + webBrlInfinityobrigatóriobooleantrue nos dois: checkout Brasil do builder.
settings.ui.webPriceCentsobrigatóriointegerPreço deste link em centavos, de 100 a 100.000.000. Não muda o preço do produto no catálogo.
settings.pix / settings.cardopcionalbooleanFormas de pagamento (pelo menos uma). Pix usa a taxa de Pix da sua conta; cartão, a do link de cartão (normal ou Nitro). O preço precisa cobrir a taxa de cada forma ligada.
settings.ui.title, description, logoTextopcionalstringTítulo no checkout, descrição (até 2.000 caracteres) e nome da marca no topo.
settings.ui.studioBackground / studioButtonopcionalstringCores do fundo do resumo e do botão (#RRGGBB).
settings.ui.studioFont / studioBorderopcionalstringFonte (global, system, roboto, open_sans) e bordas (global, rounded, pill, rectangular). Sem eles, vale o visual padrão.

Nesse modelo não há boleto, parcelamento próprio, cupom, order bump, upsell nem assinatura (para assinatura por Pix, use o Pix recorrente do builder). A venda gera os mesmos webhooks do checkout.

Criado pelo painel ou pelo app vira checkout Brasil

Checkouts simples (Pix e/ou cartão, sem assinatura, boleto, order bump ou upsell) criados pelo painel ou pelo app são salvos neste modelo. Pela chave de API, o formato que você enviar é mantido; checkouts que já existem não mudam.

Idioma do comprador (automático)

O checkout aparece no idioma do comprador: português, inglês ou espanhol. Não há nada para configurar nem na API nem no painel: vale para todos os checkouts, inclusive os que já existem.

  • Como o idioma é escolhido: pelo país de onde o comprador acessa. Brasil e países de língua portuguesa veem em português; Espanha e América hispânica, em espanhol; Estados Unidos, Reino Unido, Canadá, Austrália e outros de língua inglesa, em inglês. De outros países, vale o idioma do navegador (ou inglês). Quem usa o navegador em português sempre vê em português.
  • O comprador pode trocar: há um seletor PT · EN · ES no canto inferior direito. A escolha fica guardada naquele aparelho.
  • O que é traduzido: textos do checkout da Chase, botões, avisos e mensagens de erro, os campos do cartão internacional e as frases da assinatura. Em inglês, valores e datas seguem o formato de lá ($120.00, Nov 16, 2026). Quando o pagamento continua numa página segura de parceiro (cartão em reais), essa página segue o idioma dela.
  • O que não é traduzido: o que você escreveu — nome e descrição do produto, mensagem de obrigado, textos de upsell e bump. Para vender fora do Brasil, escreva esses textos no idioma do seu público.

Para abrir o checkout num idioma fixo (por exemplo, numa campanha para outro país), acrescente lang ao link: pt, en ou es. Funciona junto com UTMs.

https://checkout.chasepay.com.br/pay/curso-completo-a1b2c?lang=en&utm_source=instagram

Vale também no domínio próprio

Os links em checkout.chasepay.com.br e no seu domínio próprio se traduzem do mesmo jeito (ex.: https://pagar.sualoja.com.br/curso-completo-a1b2c?lang=en). A cobrança, os webhooks e os dados enviados à API são os mesmos em qualquer idioma.

Domínio próprio

Mostre o checkout no seu domínio (ex.: pagar.sualoja.com.br).

  1. Cadastre o domínioPOST /v1/user/domains com {"domain": "pagar.sualoja.com.br"}. A resposta traz id, verification_token e cname_target.
  2. Configure o DNSCrie um registro TXT em _chase.pagar.sualoja.com.br com o valor chase-verify={verification_token} e um CNAME de pagar.sualoja.com.br para o cname_target.
  3. VerifiquePOST /v1/user/domains/{id}/verify depois que o DNS propagar (pode levar algumas horas).
  4. Use no checkoutEnvie "domain": "pagar.sualoja.com.br" ao criar ou alterar o checkout.

Editar e apagar produto

PATCH/v1/user/products/{id}

Envie só o que mudar. Campos aceitos: name, price_cents, description, image_url, active, sku, type e a entrega por e-mail (deliverable_type, deliverable_url, deliverable_text, deliverable_files, deliverable_active). Outros campos são ignorados sem erro; página de obrigado, suporte e garantia ficam no checkout e no painel.

DELETE/v1/user/products/{id}

Apaga o produto.

Apagar o produto apaga os checkouts dele

Os checkouts em que ele é o produto principal são apagados (o link para de funcionar) e o bump/upsell que o usa é desligado. Desativar com {"active": false} mantém o histórico, mas o checkout desse produto também deixa de vender.

Link de cartão com liberação rápida

Além do checkout acima, o painel cria um link de cartão com prazo de recebimento menor. É só cartão de crédito, em até 12x com juros pagos pelo comprador.

  1. No painel, crie o link de cartãoInforme o valor (R$ 1,00 a R$ 1.000.000,00) e uma descrição de 3 a 160 caracteres.
  2. Escolha o recebimentoHoje: Padrão, liberado em D+7 dias úteis (5,99% + R$ 3,80), ou Nitro, em D+2 dias úteis (7,99% + R$ 4,40). Confira as taxas atuais no painel.
  3. Envie o link ao compradorCada link vale para um pagamento e expira em 24 horas. O pagamento acontece numa página segura de parceiro da Chase; no fim, o comprador vê a confirmação.
AcompanhamentoComo
Venda criadaA cobrança aparece como pending, com external_id começando por ip_. Não há charge.pending.
Pagamento aprovadoStatus paid e evento charge.paid (sem charge.received).
ConsultaGET /v1/transactions/by-external/ip_…. A URL pública /pub/card-payments/…/status não vale para este link.
Cancelamento ou estornoNão gera webhook: a venda volta para análise. Acompanhe pelo painel.

Alterar ou desativar

PATCH/v1/user/checkouts/{id}

Também aceita PUT. Mande só o que muda. Exemplos: {"active": false} para desativar, {"name": "…"} para renomear.

Ao mudar settings, mande ele completo e com product_ids

settings substitui as configurações anteriores (inclusive pix/card), e precisa vir junto de product_ids; sem produto, a resposta é 422 “Selecione um produto para este checkout.”. O mais seguro: GET /v1/user/checkouts, altere o item e mande de volta.

Para listar: GET /v1/user/checkouts e GET /v1/user/products (paginados: page e limit, padrão 50, máximo 200 — com mais itens, percorra as páginas). Para apagar: DELETE /v1/user/checkouts/{id}.

Receber

Cartão internacional

Venda para compradores de fora do Brasil, cobrando na moeda deles. O comprador paga no checkout da Chase e você recebe em reais, já convertido, no seu saldo.

Como criar

  1. No painel, crie um link de pagamentoInforme o nome e escolha pagamento único.
  2. Escolha a moeda e o preçoSelecione a moeda do comprador (ex.: USD) e o valor nessa moeda, de 1 a 1.000.000.
  3. Copie o linkO link fica em https://checkout.chasepay.com.br/pay/{slug}. Divulgue ou use como botão no seu site.

Moedas aceitas

Dólar americano (USD), euro (EUR), libra (GBP), dólar canadense (CAD), dólar australiano (AUD), peso colombiano (COP), ringgit (MYR), peso filipino (PHP), dólar de Singapura (SGD), peso chileno (CLP, só valores inteiros), coroa dinamarquesa (DKK), peso argentino (ARS), naira (NGN), dólar de Hong Kong (HKD), yuan (CNY), sol peruano (PEN), peso mexicano (MXN) e rúpia indiana (INR).

O que o comprador vê

  • O preço na moeda escolhida e o formulário de cartão. Ele informa o país de cobrança do cartão.
  • A página no idioma dele (português, inglês ou espanhol), escolhido pelo país de acesso, com seletor para trocar. Para fixar o idioma, use ?lang=en no link. Veja Idioma do comprador.
  • Cartão à vista (1x). Apple Pay e Google Pay aparecem quando o aparelho permite. Em algumas moedas dá para oferecer meios locais.
  • Autenticação do banco emissor (3DS) quando o banco exigir.
  • Depois do pagamento, volta para a página de confirmação ou para a sua URL de retorno, se configurada.

Regras

PagamentoSó cartão, à vista. Sem Pix, boleto, parcelamento ou assinatura em moeda estrangeira.
ExtrasCupom, order bump e upsell ficam desligados.
TaxaHoje, 15% + R$ 4,80 sobre o valor convertido em reais. Confira a taxa atual da sua conta no painel.
LimiteO valor convertido não pode passar do teto de venda no cartão da sua conta.
ContaPrecisa estar aprovada, com recebimento e cartão liberados.

Status e webhooks

processing→paidoufailed
  1. Pagamento aprovadoA venda aparece como processing, com “saldo em conversão” na descrição. Ainda não é dinheiro disponível.
  2. Conversão concluídaA Chase converte para reais, atualiza amount_cents, fee_cents e net_cents em reais e muda para paid. Nesse momento chegam charge.paid e charge.received.
  3. RecusaSe o cartão for recusado, chega charge.failed.

Não há charge.pending nesta venda

Libere o pedido só no charge.paid. Os valores em reais só ficam definitivos depois da conversão; antes disso são estimativa.

Para consultar uma venda, use GET /v1/transactions/by-external/{external_id} com o ID que aparece no painel ou no webhook.

Receber

Cartão de crédito no seu site

O seu servidor cria a cobrança pela API e o comprador paga na página de pagamento segura da Chase, aberta numa nova aba. Você não lida com número de cartão. Este guia mostra cada etapa, com um exemplo completo cuja chamada foi testada na API real, e o que fazer em cada resposta.

Qual caminho escolher?

Checkout nativo (recomendado)Cartão pela API
Onde o comprador digita o cartãoNa página da ChaseNa página de pagamento segura da Chase (nova aba)
Você lida com número do cartãoNãoNão
Quem cria a vendaO link do checkoutO seu servidor, com o seu pedido (external_id)
Pix e boleto na mesma telaSimNão (crie a cobrança Pix ou boleto à parte)
EsforçoCriar o link e ouvir o webhookUma chamada na API + webhook ou consulta

Se você só quer receber no cartão, use o Checkout nativo. Siga este guia se a venda nasce no seu site ou sistema.

Como funciona

1. seu servidor chama /v1/charges→2. abre a página de pagamento→3. comprador paga→4. webhook / consulta→5. libera o pedido
  1. Seu servidor cria a cobrançaPega o preço do seu banco de dados (nunca do navegador) e chama POST /v1/charges com method: "card". Não precisa de dados do cartão.
  2. A API devolve a página de pagamentoResposta 202 com status: "requires_action" e o endereço em payment_url (o mesmo valor vem em redirect_url).
  3. O comprador paga numa nova abaEle digita o cartão e escolhe as parcelas na página segura. A sua página continua aberta, esperando.
  4. Você confirma no servidorPelo webhook charge.paid ou consultando a cobrança. Só então libera o pedido, uma vez só.

Antes de começar

  • Conta aprovada, com cartão de crédito liberado. Confira card_enabled em GET /v1/fees.
  • Um servidor próprio (Node, PHP, Python…) com a chave de API (Autenticação). A chave nunca vai para o navegador.
  • Um webhook com charge.paid e charge.failed (recomendado), ou consulta da cobrança.

Taxas, prazo e parcelas

  • A taxa e o prazo são os da venda por link da sua conta: card_link_normal (recebe em 7 dias úteis) ou card_link_nitro (recebe em 2 dias úteis, se o Nitro estiver ligado no painel). Veja os valores em GET /v1/fees. A resposta da cobrança traz fee_cents, net_cents, receiving e release_days.
  • Parcelas: o comprador escolhe na página de pagamento. O campo installments é ignorado.
  • amount_cents é o total que o comprador paga. Mínimo R$ 1,00 e máximo R$ 1.000.000,00, respeitando o teto de cartão da sua conta.
  • Só crédito. method: "card_debit" responde 422.

Passo 1 — Seu servidor cria a cobrança

POST/v1/charges
CampoDe onde vemRegras
methodobrigatórioFixocard (ou card_credit).
amount_centsobrigatórioSeu banco de dadosTotal final. Nunca aceite valor vindo do navegador.
external_idSeu pedidoÚnico. Volta no webhook e na consulta. Use um novo para cada nova tentativa.
descriptionobrigatórioSeu produtoNome do produto ou serviço: é o que o comprador vê na página de pagamento. 3 a 160 caracteres. Textos genéricos (“Pagamento”, “Pagamento cartão”) são recusados com 422.
receivingVocê"normal" (recebe em 7 dias úteis) ou "nitro" (2 dias úteis, taxa maior). Sem o campo, vale a opção Nitro do painel. Outro valor responde 422.
customer.name, customer.emailCompradorOpcionais. Ajudam a identificar a venda no painel.

Já integrou enviando o cartão?

Integrações antigas que ainda mandam card, device e browser continuam aceitas: esses dados são ignorados (não são guardados nem usados) e a resposta traz card_data_ignored: true. O comprador paga na página de pagamento. Pare de coletar o cartão no seu site quando puder.

Passo 2 — Tratar a resposta

RespostaSignificaO que fazer
202 + requires_actionPágina de pagamento pronta.Abra o payment_url numa nova aba (Passo 3).
403Cartão não está liberado nesta conta (ou a conta não pode receber agora).Fale com o seu gerente. Ofereça Pix.
422Valor fora do limite de cartão, ou que não cobre a tarifa.Mostre a mensagem. Para tentar de novo, use outro external_id.
409external_id já usado.Consulte a cobrança existente. Não crie outra.
429Muitas tentativas, ou a mesma cobrança (comprador + valor) já foi criada há menos de 30 s.Consulte a cobrança existente antes de tentar de novo.
timeout, 502, 503Resultado desconhecido.Não repita o POST. Consulte GET /v1/transactions/by-external/{external_id}.
{
  "data": {
    "id": 163412,
    "external_id": "pedido-2001",
    "method": "card",
    "status": "requires_action",
    "amount_cents": 19700,
    "fee_cents": 1560,
    "net_cents": 18140,
    "payment_url": "https://…  (página de pagamento segura)",
    "redirect_url": "https://…  (o mesmo endereço)",
    "redirect_mode": "new_tab",
    "status_url": "https://api.chasepay.com.br/pub/card-payments/ip_5a3c…/status",
    "receiving": "plan",
    "release_days": 7,
    "expires_at": "2026-11-17T13:52:00-03:00"
  }
}

Passo 3 — Abrir a página de pagamento

O que o comprador vê

Na páginaVem de
Nome do produtodescription (até 160 caracteres)
Valor e totalamount_cents. O comprador paga exatamente esse valor; a taxa da Chase sai do seu líquido (net_cents).
Nome da lojaO da plataforma de pagamento da Chase, não o da sua empresa. Avise o comprador no seu site para ele reconhecer a cobrança.
Contato e cartãoO comprador preenche telefone, e-mail, nome e cartão na própria página (os dados de customer não são repassados).
Recebimento normal ou NitroNão aparece para o comprador. Vale o receiving que você enviou; sem ele, a opção Nitro do painel. A resposta confirma em receiving (plan = normal, 7 dias úteis; nitro = 2 dias úteis).
  1. Abra o payment_url exatamente como veio, numa nova abaA página de pagamento não abre dentro de <iframe> (redirect_mode: "new_tab"). Abra a aba no próprio clique do comprador (navegadores bloqueiam abas abertas depois de uma espera) e mostre um botão “abrir de novo” para o caso de bloqueio. Não altere a URL.
  2. O link vale 24 horasAté expires_at. Depois disso, crie uma nova cobrança com outro external_id.
  3. Consulte enquanto o comprador pagaA cada 3 s, uma consulta por vez, e de novo quando ele voltar para a sua aba. No exemplo, a página consulta o seu servidor, que consulta a Chase.
  4. Fechar a aba não cancelaA cobrança continua aberta até expirar. Consulte antes de oferecer nova tentativa.

O status_url é público e usa outro código

Ele termina em ip_…, diferente do seu external_id. Não precisa de chave e responde {"data": {"id": "", "status": "processing" | "paid" | "rejected", "message": ""}}. Serve para a sua página mostrar o andamento; para liberar o pedido, confirme sempre no servidor (Passo 4).

Passo 4 — Confirmar e liberar

  • Webhook: charge.paid com a assinatura válida. Ao criar a cobrança, chega charge.pending.
  • Consulta: GET /v1/transactions/by-external/{external_id} com status: "paid". Antes do pagamento, a cobrança aparece como pending.
  • Confira amount_cents e o pedido no seu banco. Libere uma vez só, mesmo se o webhook chegar repetido.

Exemplo completo

Servidor Node 18+ sem dependências e página de venda. A chamada que ele faz foi testada na API real em 16/11/2026: a cobrança volta com a página de pagamento, o status_url responde e a consulta por external_id mostra o andamento. Rode com CHASE_API_KEY=… CHASE_WEBHOOK_SECRET=… node server.mjs e abra http://localhost:3000.

// Exemplo completo: venda com cartão no seu site pela API da Chase Pay.
// O comprador paga na página de pagamento segura da Chase; o seu servidor cria a cobrança e confirma.
// Node 18+ sem dependências.  Rodar:  CHASE_API_KEY=... CHASE_WEBHOOK_SECRET=... node server.mjs
// Abra http://localhost:3000 — o navegador só fala com ESTE servidor; a chave nunca vai para o navegador.
import { createServer } from 'node:http';
import { readFile } from 'node:fs/promises';
import { createHmac, timingSafeEqual, randomUUID } from 'node:crypto';

const API = 'https://api.chasepay.com.br';
const KEY = process.env.CHASE_API_KEY;
const WEBHOOK_SECRET = process.env.CHASE_WEBHOOK_SECRET || '';
const PORT = Number(process.env.PORT || 3000);
if (!KEY) { console.error('Defina CHASE_API_KEY'); process.exit(1); }

// "Banco de dados" do exemplo. Em produção use o seu banco: o pedido, o preço e o status ficam no SERVIDOR.
const products = { curso: { name: 'Curso completo', price_cents: 19700 } };
const orders = new Map();      // id -> { id, product, amount_cents, status, payment_url, fulfilled }
const seenEvents = new Set();  // ids de evento de webhook já processados (deduplicação)

const json = (res, status, body) => { res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' }); res.end(JSON.stringify(body)); };
const readBody = req => new Promise((ok, ko) => { const parts = []; let size = 0; req.on('data', c => { size += c.length; if (size > 1e6) { ko(new Error('corpo grande demais')); req.destroy(); } else parts.push(c); }); req.on('end', () => ok(Buffer.concat(parts))); req.on('error', ko); });

async function chase(path, { method = 'GET', body } = {}) {
  const res = await fetch(API + path, {
    method, redirect: 'error', signal: AbortSignal.timeout(method === 'POST' ? 60000 : 30000),
    headers: { Authorization: `Bearer ${KEY}`, Accept: 'application/json', ...(body ? { 'Content-Type': 'application/json' } : {}) },
    body: body ? JSON.stringify(body) : undefined,
  });
  let data; try { data = await res.json(); } catch { data = null; }
  return { status: res.status, data };
}

// Atualiza o pedido a partir da Chase (fonte da verdade). Usado pelo navegador (consulta) e pelo webhook.
async function syncOrder(order) {
  const { status, data } = await chase('/v1/transactions/by-external/' + encodeURIComponent(order.id));
  if (status === 404) return order;                       // ainda não criada
  if (status !== 200 || !data?.data) return order;        // falha temporária: mantém o que sabia
  const tx = data.data;
  if (tx.amount_cents !== order.amount_cents) { order.status = 'review'; return order; } // valor diferente: não libera
  if (tx.status === 'paid' && order.status !== 'paid') { order.status = 'paid'; fulfill(order); }
  else if (['failed', 'refunded', 'chargeback'].includes(tx.status)) order.status = 'failed';
  else if (order.status !== 'paid') order.status = 'waiting';
  return order;
}
function fulfill(order) {
  if (order.fulfilled) return;            // libera uma vez só, mesmo com webhook repetido
  order.fulfilled = true;
  console.log('Pedido pago e liberado:', order.id);
}

createServer(async (req, res) => {
  try {
    const url = new URL(req.url, 'http://localhost');

    // 1) Cria o pedido e a cobrança. Preço vem do SEU catálogo, nunca do navegador.
    if (req.method === 'POST' && url.pathname === '/api/pedidos') {
      const input = JSON.parse((await readBody(req)).toString() || '{}');
      const product = products[input.product];
      if (!product) return json(res, 422, { error: 'Produto inválido' });
      const order = { id: 'pedido-' + randomUUID().slice(0, 13), product: input.product, amount_cents: product.price_cents, status: 'creating' };
      orders.set(order.id, order);
      const payload = {
        method: 'card',
        amount_cents: order.amount_cents,          // total, do servidor
        external_id: order.id,                     // seu pedido: volta no webhook e na consulta
        description: product.name,
        customer: { name: String(input.name || '').slice(0, 120), email: String(input.email || '').slice(0, 160) },
      };
      let r;
      try { r = await chase('/v1/charges', { method: 'POST', body: payload }); }
      catch { order.status = 'waiting'; return json(res, 202, { id: order.id, status: 'waiting', message: 'Sem resposta da Chase. Consultando o pedido…' }); } // timeout: NÃO repita
      if (r.status === 202 && r.data?.data?.payment_url) {
        order.status = 'waiting'; order.payment_url = r.data.data.payment_url;
        return json(res, 201, { id: order.id, status: 'waiting', payment_url: order.payment_url });
      }
      if (r.status === 409) { await syncOrder(order); return json(res, 200, { id: order.id, status: order.status, payment_url: order.payment_url }); }
      if (r.status >= 500) { order.status = 'waiting'; return json(res, 202, { id: order.id, status: 'waiting', message: 'Instabilidade. Consultando o pedido…' }); }
      order.status = 'failed';                     // 4xx: conta sem cartão, valor fora do limite… mostre a mensagem
      return json(res, r.status, { id: order.id, status: 'failed', message: r.data?.error?.message || 'Não foi possível iniciar o pagamento' });
    }

    // 2) Status para o navegador (sempre confirmado na Chase pelo servidor).
    const st = url.pathname.match(/^\/api\/pedidos\/([\w-]+)$/);
    if (req.method === 'GET' && st) {
      const order = orders.get(st[1]);
      if (!order) return json(res, 404, { error: 'Pedido não encontrado' });
      if (order.status !== 'paid') await syncOrder(order);
      return json(res, 200, { status: order.status, payment_url: order.payment_url });
    }

    // 3) Webhook da Chase: valida assinatura no corpo BRUTO, deduplica e confirma na API.
    if (req.method === 'POST' && url.pathname === '/webhooks/chase') {
      const raw = await readBody(req);
      // X-Chase-Signature-V2: t=<unix>,v1=HMAC(secret, "<t>." + corpo). Recusa avisos com mais de 5 minutos.
      const parts = Object.fromEntries(String(req.headers['x-chase-signature-v2'] || '').split(',').map(p => p.split('=')));
      const t = Number(parts.t);
      const expected = Buffer.from(createHmac('sha256', WEBHOOK_SECRET).update(`${t}.`).update(raw).digest('hex'));
      const received = Buffer.from(String(parts.v1 || ''));
      if (!WEBHOOK_SECRET || !t || Math.abs(Date.now() / 1000 - t) > 300 || received.length !== expected.length || !timingSafeEqual(received, expected))
        return json(res, 401, { error: 'assinatura inválida' });
      const event = JSON.parse(raw.toString());
      json(res, 200, { ok: true });                 // responde rápido; processa depois
      if (seenEvents.has(event.id)) return;
      seenEvents.add(event.id);
      const order = orders.get(event.data?.external_id);
      if (order && event.type.startsWith('charge.')) await syncOrder(order);
      return;
    }

    // Arquivos da página
    const file = url.pathname === '/' ? 'index.html' : url.pathname.slice(1);
    if (['index.html', 'checkout.js'].includes(file)) {
      const type = file.endsWith('.html') ? 'text/html; charset=utf-8' : 'text/javascript; charset=utf-8';
      res.writeHead(200, { 'Content-Type': type, 'Cache-Control': 'no-store' });
      return res.end(await readFile(new URL('./public/' + file, import.meta.url)));
    }
    json(res, 404, { error: 'não encontrado' });
  } catch (e) {
    json(res, 500, { error: 'erro interno' });
  }
}).listen(PORT, () => console.log(`Exemplo rodando em http://localhost:${PORT}`));
// Navegador: fala só com o SEU servidor. O cartão é digitado na página de pagamento segura da Chase.
const $ = s => document.querySelector(s);
const show = (text, kind = '') => { const el = $('#status'); el.textContent = text; el.dataset.kind = kind; };
const field = name => $(`[name="${name}"]`).value.trim();

$('#form').addEventListener('submit', async e => {
  e.preventDefault();
  $('#pay').disabled = true;
  // Abra a aba já no clique (navegadores bloqueiam abas abertas depois de uma espera).
  const tab = window.open('', '_blank');
  show('Preparando o pagamento…');
  try {
    // 1) Seu servidor cria o pedido e a cobrança (o preço é do servidor).
    const res = await fetch('/api/pedidos', { method: 'POST', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ product: 'curso', name: field('name'), email: field('email') }) });
    const order = await res.json();
    if (order.status === 'failed') { tab?.close(); $('#pay').disabled = false; return show(order.message || 'Não foi possível iniciar o pagamento.', 'error'); }
    if (order.payment_url) openPayment(tab, order.payment_url);
    else tab?.close();
    waitFor(order.id);
  } catch {
    tab?.close();
    show('Falha de conexão. Não pague de novo: confira o status do pedido.', 'error');
  }
});

// 2) Página de pagamento: use a URL exatamente como veio. Se a aba foi bloqueada, mostre um botão.
function openPayment(tab, paymentUrl) {
  const url = new URL(paymentUrl);
  if (url.protocol !== 'https:') { tab?.close(); return show('Resposta inesperada. Não pague de novo.', 'error'); }
  if (tab && !tab.closed) tab.location.href = url.href;
  $('#open-payment').hidden = false;
  $('#open-payment').onclick = () => window.open(url.href, '_blank');
  show('Conclua o pagamento na aba que abriu. Esta página atualiza sozinha.');
}

// 3) Consulta o SEU servidor a cada 3 s (ele confirma na Chase). Uma consulta por vez, até 30 min.
function waitFor(orderId) {
  const started = Date.now(); let timer, busy = false, stopped = false;
  const stop = () => { stopped = true; clearTimeout(timer); $('#open-payment').hidden = true; };
  async function tick() {
    if (stopped || busy) return; busy = true; clearTimeout(timer);
    try {
      const { status } = await (await fetch(`/api/pedidos/${orderId}`)).json();
      if (status === 'paid') { stop(); return show('Pagamento aprovado!', 'ok'); }
      if (status === 'failed') { stop(); $('#pay').disabled = false; return show('Pagamento não aprovado. Tente de novo.', 'error'); }
      if (status === 'review') { stop(); return show('Pagamento em análise. Você receberá a confirmação por e-mail.'); }
    } catch {} finally { busy = false; }
    if (Date.now() - started > 30 * 60 * 1000) { stop(); return show('Ainda sem confirmação. Não pague de novo: aguarde o e-mail ou consulte o pedido.'); }
    timer = setTimeout(tick, 3000);
  }
  // Ao voltar para esta aba, consulta na hora.
  document.addEventListener('visibilitychange', () => { if (!document.hidden) tick(); });
  tick();
}
<!doctype html>
<html lang="pt-BR">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Exemplo de venda com cartão — Chase Pay</title>
<style>
 body{font:15px/1.5 system-ui,sans-serif;background:#f6f5f0;color:#1b2a31;margin:0;padding:24px 16px}
 main{max-width:480px;margin:0 auto;background:#fff;border:1px solid #e3e3da;border-radius:16px;padding:24px}
 h1{font-size:22px;margin:0 0 4px}.price{color:#66747a;margin:0 0 18px}
 form{display:grid;gap:10px}
 label{display:grid;gap:4px;font-size:13px;color:#66747a}
 input{font:inherit;padding:10px 12px;border:1px solid #d7d8cf;border-radius:10px;color:#1b2a31}
 button{font:inherit;font-weight:700;width:100%;padding:13px;border:0;border-radius:12px;background:#265c73;color:#fff;cursor:pointer}
 button:disabled{opacity:.5;cursor:wait}
 .hint{font-size:13px;color:#66747a;margin:10px 0 0;text-align:center}
 #status{margin-top:14px;font-weight:600}#status[data-kind=ok]{color:#2f8f74}#status[data-kind=error]{color:#b54d4d}
 .link{background:none;color:#265c73;text-decoration:underline;padding:6px;font-weight:500}
</style>
</head>
<body>
<main>
 <h1>Curso completo</h1>
 <p class="price">R$ 197,00 · cartão de crédito</p>
 <form id="form" autocomplete="on">
  <label>Nome completo<input name="name" required autocomplete="name"></label>
  <label>E-mail<input name="email" type="email" required autocomplete="email"></label>
  <button id="pay">Pagar com cartão</button>
  <p class="hint">Você vai digitar o cartão na página de pagamento segura da Chase, numa nova aba.</p>
 </form>
 <p id="status" role="status" aria-live="polite"></p>
 <button id="open-payment" class="link" type="button" hidden>A página de pagamento não abriu? Abrir agora</button>
</main>
<script type="module" src="/checkout.js"></script>
</body>
</html>

Em PHP ou Python, a lógica é a mesma: crie o pedido no servidor, chame POST /v1/charges com a tabela do Passo 1, devolva o payment_url para a página abrir e consulte by-external para confirmar.

Testar antes de publicar

  1. Criar sem pagarCrie uma cobrança de R$ 1,00 a R$ 5,00. A resposta deve ser 202 com payment_url. Abra a página e não pague: a cobrança fica pending e o link vence em 24 horas. Nada é cobrado.
  2. Venda real pequenaNão existe ambiente de teste. Pague uma cobrança pequena com o seu cartão para ver a aprovação e o webhook de verdade.
  3. Casos difíceisFeche a aba de pagamento no meio, recarregue a sua página, bloqueie pop-ups e confirme que nada é cobrado duas vezes.

Perguntas frequentes

Posso salvar o cartão para cobrar depois?

Não nesta rota. Para cobrança mensal, use a assinatura do Checkout nativo.

O comprador fechou a aba de pagamento. Cobro de novo?

Não de imediato. Consulte a cobrança: ela pode ser paga até o link expirar. Só ofereça nova tentativa (com novo external_id) depois que ela vencer ou aparecer failed.

Posso ter o campo de cartão dentro da minha própria página?

Não pela API. O campo seguro de cartão só funciona nas páginas da Chase. Para uma página com a sua cara, crie o checkout pelo builder do painel (veja Checkout Brasil), com cores, textos e a sua marca. Pela API, o cartão é sempre pago na página de pagamento.

Dá para escolher Nitro em uma cobrança só?

Sim. Envie "receiving": "nitro" (ou "normal") em POST /v1/charges. Sem o campo, vale a opção Nitro do painel. Confira receiving, release_days e fee_cents na resposta.

Ainda preciso do módulo de segurança e do IP do comprador?

Não. A página de pagamento cuida da segurança e da confirmação do banco. Se você ainda envia device e browser, eles são ignorados.

Apple Pay e Google Pay?

Não são aceitos em POST /v1/charges. Eles aparecem automaticamente no Checkout nativo quando o aparelho e a conta permitem.

Receber

Boleto proposta

Boleto registrado no banco emissor para uma proposta comercial que o cliente pediu. O pagamento é facultativo e a emissão não credita o seu saldo na Chase: o que vale é o pagamento conciliado.

Quem pode usar

A conta precisa estar com boleto ativo e habilitada para boleto proposta, com KYC aprovado. Sem isso, as rotas respondem 403 “Boleto proposta indisponivel para esta conta.”. Use a chave de API só no servidor; os dados do beneficiário e do convênio ficam na Chase e não vêm do navegador.

Regras da emissão

  • Vencimento: 3 dias corridos a partir da emissão efetiva, no horário de Brasília. A data não começa a contar no envio do arquivo nem no agendamento.
  • Baixa: pedida para 90 dias após o vencimento, sem juros, multa nem protesto. Pagar depois do vencimento depende de o boleto continuar ativo e do aceite do banco.
  • Valor: o banco aceita pagamento de valor diferente do nominal. Valor diferente ou parcial não conta como pagamento integral (veja a conciliação).

Emitir

POST/v1/boleto-proposals
{
  "idempotency_key": "proposta-cliente-0001-a1b2c3",
  "amount_cents": 19990,
  "payer_requested_proposal": true,
  "payer_request_reference": "REGISTRO_REAL_DA_SOLICITACAO",
  "payer": {
    "name": "NOME REAL DO CLIENTE",
    "document": "CPF_OU_CNPJ_REAL",
    "address": "Rua e número",
    "neighborhood": "Bairro",
    "city": "Cidade",
    "state": "SP",
    "zip_code": "00000000"
  }
}
CampoRegra
idempotency_keyobrigatóriostring16 a 64 caracteres (letras, números, - e _), única por proposta. Repetir a mesma chave com os mesmos dados devolve o registro original, sem nova emissão; com dados diferentes, 409. A chave é isolada por conta.
amount_centsobrigatóriointegerValor nominal em centavos (R$ 199,90 = 19990). Defina uma vez e mantenha em novas tentativas.
payer_requested_proposalobrigatóriobooleantrue: confirma que o cliente pediu a proposta. Fica na Chase; não vai para o banco.
payer_request_referenceobrigatóriostringReferência do registro real do pedido do cliente. Fica na Chase. Use uma referência comum só se o registro cobrir os pedidos de todos aqueles clientes.
payerobrigatórioobjectNome (até 40), CPF/CNPJ válido, endereço com número (até 40), bairro (até 30), cidade (até 20), UF e CEP (8 dígitos). CNPJ: razão social.
offer_descriptionopcionalstring3 a 255 caracteres. Vazio usa a descrição padrão de /defaults. Vai no recibo do boleto e volta na resposta.
offer_termsopcionalstringCondições acrescidas ao padrão. Texto final de 20 a 20.000 caracteres e, com descrição e contato, até 45 mensagens de 100 caracteres no recibo. Passou do limite: 422 antes do registro, sem corte.
due_dateignoradoLegado. O vencimento é sempre emissão + 3 dias corridos.

HTTP 201 não basta

Só libere o boleto e o e-mail ao cliente quando a resposta tiver registration_verified: true e o estado estiver registrado e aberto. Em creating ou uncertain, consulte o registro original; não gere outra chave.

Rotas

RotaO que faz
GET /v1/boleto-proposals/defaultsDescrição e termos padrão. Não emite nada.
POST /v1/boleto-proposalsEmissão real (produção).
GET /v1/boleto-proposalsÚltimas 100 propostas da conta, como estão na Chase (sem consultar o banco item a item).
GET /v1/boleto-proposals?ids=123,124Até 100 IDs da conta. IDs de outra conta ou inexistentes não aparecem.
GET /v1/boleto-proposals?idempotency_key=…Busca a proposta pela sua chave.
GET /v1/boleto-proposals/{id}Consulta o banco na hora e atualiza o registro na Chase.
GET /v1/boleto-proposals/{id}/pdfPDF do boleto (arquivo, sem JSON) para proposta registrada e aberta. Indisponível: 409.
POST /v1/boleto-proposals/validateEnvia o cadastro ao ambiente de teste do banco e responde payable: false. Não testa a emissão de produção.

Fluxo: arquivo, Chase e banco

  1. ArquivoCSV UTF-8 com cabeçalho nome;cpf;email;endereco. Em endereco, use Rua e número | Bairro | Cidade | UF | CEP. Planilhas antigas com endereço, bairro, cidade, UF e CEP em colunas separadas continuam aceitas.
  2. ChaseConfere autorização, termos, idempotência e vencimento; tira duplicados do arquivo e já emitidos; separa o endereço nos campos do banco (com os limites de tamanho) e fixa o valor escolhido, sem sortear de novo.
  3. BancoRegistra pagador e valor e devolve linha digitável, código de barras e PDF. O e-mail ao cliente só é enviado depois da emissão conferida.

No painel, o preço é fixo ou uma faixa (mínimo e máximo, com valores diferentes no lote). Nome, horário e duração do lote ficam no site; o ritmo de emissão respeita no mínimo 3 segundos entre boletos e pode estender o término se o banco estiver lento.

Conferência e conciliação

Registro confirmado, envio de e-mail e pagamento são etapas diferentes. HTTP de sucesso e linha digitável não provam pagamento.

{
  "data": {
    "id": 123,
    "status": "uncertain",
    "document_kind": "BOLETO_PROPOSTA",
    "registration_verified": false,
    "digitable_line": null
  }
}
EstadoO que fazer
creating / uncertainNão envie o boleto nem crie outra chave. Consulte e confira o original.
pendingRegistro aberto. Libere só depois de conferir. Ainda não é pagamento.
payment_processing / paid_processingEm compensação. Não presuma pagamento integral.
paid_amount_pendingPagamento indicado, valor ainda não confirmado. Não use o nominal no lugar.
paidConfira paid_cents == amount_cents antes de liberar o que foi vendido.
paid_partial / paid_divergentPago a menos ou valor diferente do nominal. Confira à parte; não conta como integral.
rejected / canceled / reversedRecusado, cancelado ou estornado. Não é recebimento.
  • Atualização: o retorno do banco e o conciliador da Chase atualizam os estados em segundo plano. A lista mostra o último ciclo; a consulta por ID vai ao banco na hora.
  • Sem webhook de saída para estas rotas: consulte a lista ou o ID. A emissão não credita saldo.
  • Erros: 401 autenticação; 403 conta sem boleto ativo ou sem habilitação; 404 proposta não encontrada na conta; 409 chave em conflito, em processamento ou PDF indisponível; 422 dados inválidos; 502 banco indisponível ou retorno incompatível. Leia sempre data.status.

Receber

Rastreamento (UTM) e integrações

Saiba de qual anúncio veio cada venda. O checkout da Chase guarda as UTMs do link e envia a venda para as suas ferramentas de rastreamento e para a API de Conversões do Facebook.

UTMs no link do checkout

Coloque os parâmetros no link que vai no anúncio. A página de pagamento lê e grava junto com a venda:

https://checkout.chasepay.com.br/pay/curso-completo-a1b2c?utm_source=facebook&utm_medium=cpc&utm_campaign=black-friday&utm_content=video-01&utm_term=publico-frio
ParâmetroUso comum
utm_sourceOrigem: facebook, google, tiktok, instagram.
utm_mediumTipo de tráfego: cpc, organico, email.
utm_campaignCampanha.
utm_contentCriativo ou anúncio.
utm_termPúblico ou palavra-chave.

Se o link chegar sem UTM, o checkout usa os valores padrão que você definir nele (opcional):

{
  "ui": {
    "trackingPlatform": "facebook",
    "utmSource": "facebook",
    "utmMedium": "cpc",
    "utmCampaign": "perpetuo"
  }
}

Cobrança direta pela API não leva UTM

POST /v1/charges não aceita campos de UTM. Se você cobra pela API no seu próprio site, guarde as UTMs no seu sistema junto do external_id. As UTMs automáticas valem para vendas feitas no Checkout nativo.

Pixel do Meta, Google Tag Manager e GA4

O checkout carrega os seus pixels na página de pagamento quando trackingAtivo está ligado:

CampoDescrição
ui.trackingAtivoobrigatóriotrue para carregar os pixels abaixo.
ui.fbPixelID do Pixel do Meta (só números).
ui.gtmID do Google Tag Manager (GTM-…).
ui.ga4ID do Google Analytics 4 (G-…).

Ao mandar settings, mande ele completo (com pix/card) e junto de product_ids: ele substitui as configurações anteriores. Veja Checkout nativo.

Integrações de rastreamento

Com a integração ligada, a Chase envia cada venda (com as UTMs do checkout) para a ferramenta. Configure no painel, em Integrações, ou pela API:

POST/v1/user/integrations
providerconfigOnde pegar
utmifytokenCredencial (token) de API criada no painel da Utmify.
xtrackywebhookUrl, tokenURL de webhook e token do painel da xTracky.
adoptifywebhookUrl, tokenURL de webhook e token da Adoptify.
otimizeiwebhookUrl, tokenURL de webhook e token da Otimizei.
facebookpixelId, token, testEventCode (opcional)API de Conversões: ID do Pixel e token de acesso do Gerenciador de Eventos. O código de teste mostra os eventos na aba “Testar eventos”.
  • Mantenha uma integração por ferramenta (duplicadas recebem a mesma venda duas vezes). Para trocar o token, use PUT /v1/user/integrations/{id} com {"config": {...}}.
  • Pausar: PUT com {"active": false}. Remover: DELETE /v1/user/integrations/{id}.
  • Listar: GET /v1/user/integrations.
  • POST /v1/user/integrations/{id}/test só confere se o token tem 8+ caracteres e responde {"data": {"success": true, "message": "Token valido. Integracao pronta para receber eventos.", "integration": {...}}} — não envia nada para a ferramenta. Para testar de verdade, faça uma venda de valor baixo e veja se ela aparece lá.

Quando a venda é enviada

Na criação da cobrança (aguardando pagamento), na aprovação e em estorno/MED. Vendas do link de cartão com liberação rápida não são enviadas às integrações.

Notificação no celular (Pushcut)

Para receber push a cada venda, use um webhook apontando para a URL de notificação do Pushcut, com os eventos charge.paid e payout.paid.

Saldo e saques

Saques Pix

Transfira o saldo disponível por Pix. A taxa sai do valor pedido, e cada conta tem mínimo, limite diário e, às vezes, aprovação manual.

Solicitar saque

POST/v1/payouts
CampoDescrição
amount_centsobrigatóriointegerValor pedido, em centavos. A taxa de saque é descontada dele.
pix_keyobrigatóriostringChave Pix de destino.
key_typerecomendadostringcpf, cnpj, email, phone ou evp (aleatória). Com cpf, a chave precisa ser o CPF do titular da conta.
pinse a conta tiver PINstringPIN de saque de 4 dígitos, o mesmo do painel. Obrigatório quando a conta tem PIN.

Sempre envie key_type

Sem ele, uma chave de 11 dígitos que não seja o CPF do titular é tratada como telefone. Telefone pode ir com ou sem +55.

{
  "data": {
    "id": 7781,
    "status": "processing",
    "amount_cents": 50000,
    "fee_cents": 370,
    "pix_key": "financeiro@sualoja.com.br",
    "end_to_end_id": null,
    "error_reason": null,
    "paid_at": null,
    "created_at": "2026-11-16 15:20:00"
  }
}

Use os campos acima. A resposta pode trazer campos internos extras; ignore-os.

Status do saque

StatusSignificado
pendingAguardando aprovação manual da Chase (algumas contas).
processing / awaiting_adminEm envio ou em conferência. Não peça de novo.
paidPago. end_to_end_id traz o identificador do Pix.
failed / cancelled / refundedNão concluído. Veja o motivo em error_reason e confira o saldo antes de pedir outro.

Eventos: payout.created, payout.paid e payout.failed.

Regras e limites

  • Mínimo, taxa e limite diário são os da sua conta: consulte em GET /v1/user/limits antes de pedir. O dia conta no horário de Brasília.
  • O saque usa só o saldo disponível. Valores em liquidação ou bloqueados por MED não entram.
  • Um saque por vez: pedidos simultâneos da mesma conta recebem 409.
  • As travas da conta valem para todo tipo de saída de dinheiro (saque, comissão de indicação e pagamentos): saque desativado, cadastro não aprovado, pausa geral e manutenção bloqueiam o pedido.
  • Não existe external_id em saque. Em timeout, consulte a lista antes de pedir de novo.

Erros comuns

HTTPMensagem
403PIN de saque obrigatorio / PIN de saque incorreto.
403Saques temporariamente desabilitados para esta conta.
403Saques liberados somente apos aprovacao do KYC.
409Outra solicitação de saque está em processamento. Tente novamente. (Pedidos simultâneos esperam até 10 s antes desse erro.)
429Muitas tentativas de PIN incorretas. Tente novamente mais tarde. (5 erros em 15 min ou 10 no dia.)
422Abaixo do mínimo (“Valor mínimo para saque: R$ 100,00”), acima do limite diário, saldo insuficiente (“Saldo disponível insuficiente.”), taxa maior que o valor ou chave inválida. “Falha ao processar o saque.” quando o envio falha na hora: o saque fica failed na lista, o saldo não é debitado e não sai payout.failed.
503Saques pausados pela plataforma ou manutenção. Tente mais tarde.

Listar e consultar saques

GET/v1/payouts

Do mais recente ao mais antigo, limit até 100. Resposta: {"data": [...], "total", "page", "limit"}.

GET/v1/payouts/{id}

Em pagamentos de Pix copia e cola/QR Code, traz também beneficiary_name e beneficiary_document (mascarado) para você conferir o destino. Em saque por chave Pix esses campos vêm null.

Saldo e saques

Saldo

Quanto você pode sacar agora, quanto ainda vai liberar e quanto está bloqueado.

Consultar saldo

GET/v1/balance
{
  "data": {
    "available_cents": 46808,
    "pending_cents": 12000,
    "settling_cents": 19700,
    "settling_boleto_cents": 0,
    "settling_card_cents": 19700,
    "blocked_cents": 651,
    "debt_cents": 0,
    "received_cents": 1048659,
    "withdrawn_cents": 980000,
    "boleto_settlement_days": 1,
    "card_settlement_days": 30,
    "settling_transactions": [
      { "id": 90420, "external_id": "pedido-2001", "method": "card", "amount_cents": 19700, "net_cents": 18300, "paid_at": "2026-11-10 12:00:00", "release_at": "2026-12-22" }
    ],
    "currency": "BRL"
  }
}
CampoDescrição
available_centsDisponível para saque agora.
settling_centsVendas pagas aguardando liberação (boleto e cartão), com o detalhe em settling_transactions e a data em release_at.
blocked_centsBloqueado por MED, reembolso pedido ou análise.
debt_centsDébito da conta com a Chase (ex.: estorno maior que o saldo disponível).
boleto_settlement_days / card_settlement_daysPrazo de liberação em dias úteis.
received_cents / withdrawn_centsTotais históricos recebidos e sacados.

Saldo por método

GET/v1/balance/breakdown
{
  "data": {
    "pix":    { "available_cents": 30000, "today_cents": 4890, "week7_cents": 61200 },
    "boleto": { "available_cents": 0,     "today_cents": 0,    "week7_cents": 19990 },
    "card":   { "available_cents": 16808, "today_cents": 0,    "week7_cents": 19700 }
  }
}

Use para relatórios de vendas por método (hoje e últimos 7 dias). Para saber quanto dá para sacar, use sempre available_cents de /v1/balance.

Webhooks

Webhooks

A Chase avisa o seu servidor a cada mudança de cobrança e saque, com um POST JSON assinado, em poucos segundos. Responda 2xx rápido e processe depois.

Eventos

EventoQuando
charge.pendingCobrança criada e aguardando pagamento: Pix/boleto gerado, cartão aguardando o comprador pagar na página de pagamento. Não libere o pedido.
charge.paidPagamento aprovado. É o evento para liberar o pedido.
charge.receivedEnviado depois da maioria dos charge.paid, com os mesmos dados (não vem em renovação de assinatura, link de cartão nem liberação de retenção). Para liberar pedido, use charge.paid.
charge.failedPagamento recusado ou cancelado.
charge.disputedVocê pediu reembolso; valor bloqueado em análise.
charge.refundedValor devolvido ao comprador.
charge.chargebackContestação do banco ou MED aberta. Veja MED.
payout.created / payout.paid / payout.failedSaque criado, pago ou com falha.
webhook.testDisparo manual pelo teste.
*Todos os eventos, inclusive os que vierem a existir.

charge.created, charge.expired e balance.updated são aceitos no cadastro, mas hoje não são enviados.

Formato do envio

POST /webhooks/chase HTTP/1.1
Content-Type: application/json
X-Chase-Event: charge.paid
X-Chase-Timestamp: 1763298312
X-Chase-Signature-V2: t=1763298312,v1=9a41c0…
X-Chase-Signature: sha256=5f0c1e…

{
  "id": "evt_8f2b4c1d9e0a7b6c5d4e",
  "type": "charge.paid",
  "created_at": "2026-11-16T13:05:12+00:00",
  "data": {
    "id": 90412,
    "external_id": "pedido-1001",
    "status": "paid",
    "method": "pix",
    "amount_cents": 4890,
    "fee_cents": 342,
    "net_cents": 4548,
    "description": "Pedido 1001",
    "payer_name": "Amanda Carvalho",
    "payer_document": "52998224725",
    "paid_at": "2026-11-16 10:05:12",
    "created_at": "2026-11-16 10:00:00",
    "updated_at": "2026-11-16 10:05:12"
  }
}
  • created_at do evento vem em UTC (ISO 8601). As datas dentro de data vêm no horário de Brasília.
  • Em eventos charge.*, data é a cobrança. Em payout.*, é o saque.
  • data pode trazer campos internos além dos documentados. Use só os documentados; não dependa dos outros.

Entrega e novas tentativas

RegraValor
Primeiro envioEm até ~15 segundos depois do evento (os avisos saem por uma fila; um endpoint lento nunca atrasa o pagamento).
SucessoResposta 2xx. Redirecionamentos não são seguidos.
Tempo limite8 segundos (3 s para conectar).
Novas tentativasAté 5 envios no total: depois de 1, 5, 15 e 60 minutos.
Mesmo eventoCada nova tentativa manda o mesmo corpo, com o mesmo id evt_….
Evento desatualizadoSe a cobrança já mudou de status, a tentativa pendente é descartada.

Receptor confiável

1) Valide a assinatura. 2) Grave o id do evento e ignore repetidos. 3) Responda 200. 4) Processe em segundo plano, conferindo external_id e amount_cents no seu banco e liberando o pedido uma vez só.

Criar webhook

  1. Tenha uma chave de API ativaSem nenhuma chave, o cadastro é recusado. Veja Autenticação.
  2. Publique a URL que vai receberHTTPS, pública e já respondendo. O domínio precisa existir no DNS no momento do cadastro.
  3. CadastrePelo painel, na área de Webhooks, ou pela API, abaixo.
  4. Guarde o secretEle volta uma única vez e é usado para validar a assinatura.
  5. TesteUse Testar endpoint e confira que o seu servidor respondeu 200.
POST/v1/user/webhooks
CampoDescrição
urlobrigatóriostringEndereço HTTPS do seu servidor. Não aceita IP privado, localhost ou rede interna.
eventsrecomendadoarrayEventos da tabela de eventos, ou ["*"] para todos.
nameopcionalstringNome para você reconhecer o endpoint (ex.: “Loja produção”).
{
  "data": {
    "id": 12,
    "url": "https://sualoja.com.br/webhooks/chase",
    "name": "Loja produção",
    "events": ["charge.paid", "charge.failed", "charge.refunded", "charge.chargeback", "payout.paid", "payout.failed"],
    "active": true,
    "secret": "whsec_…"
  }
}
  • A URL precisa ser HTTPS e pública (sem localhost ou rede interna).
  • A conta precisa ter ao menos uma chave de API ativa.
  • Endpoint fora do ar continua recebendo tentativas. Se desativar o sistema, pause o webhook ({"active": false}) ou remova-o, e acompanhe as falhas em success_count/fail_count.
  • O secret aparece só nesta resposta. Se perder ou vazar, gere outro em Trocar o segredo.
  • Pode ter vários endpoints (ex.: loja e ERP); cada um recebe os eventos que assinou e tem seu próprio secret.

Erros do cadastro

HTTPMensagem
422Para criar webhooks voce precisa ter ao menos uma Chave de API ativa…
422URL do webhook deve usar HTTPS.
422URL do webhook invalida. (domínio não resolve no DNS)
422URL do webhook nao pode apontar para enderecos privados.
422Não inclua usuário ou senha na URL do webhook.
422Evento invalido: … Valores permitidos: … / events deve ser um array.

Evento de saque

Nos eventos payout.created, payout.paid e payout.failed, data é o saque:

{
  "id": "evt_1c9d2e3f4a5b6c7d8e9f",
  "type": "payout.paid",
  "created_at": "2026-11-16T18:21:40+00:00",
  "data": {
    "id": 7781,
    "type": "cashout",
    "status": "paid",
    "amount_cents": 50000,
    "fee_cents": 370,
    "pix_key": "financeiro@sualoja.com.br",
    "end_to_end_id": "E1234567820261116182140abc123",
    "error_reason": null,
    "requested_at": "2026-11-16 15:20:00",
    "paid_at": "2026-11-16 15:21:40",
    "created_at": "2026-11-16 15:20:00",
    "updated_at": "2026-11-16 15:21:40"
  }
}

Em payout.failed, status vem failed e o motivo em error_reason. Ligue o evento ao saque pelo data.id que voltou no POST /v1/payouts.

Listar endpoints

GET/v1/user/webhooks

Cada item traz success_count e fail_count das últimas 24 h, last_triggered, last_status_code e last_success.

Atualizar endpoint

PUT/v1/user/webhooks/{id}

Envie só o que mudar: url, name, events ou active. Use os nomes de evento da tabela acima: na alteração o nome não é conferido, e um nome errado faz o endpoint parar de receber aquele evento sem aviso.

Remover endpoint

DELETE/v1/user/webhooks/{id}

Resposta: {"data": {"deleted": true}}.

Testar endpoint

POST/v1/user/webhooks/{id}/test

Envia um webhook.test na hora, uma vez, sem novas tentativas (até 5 testes por minuto). A resposta diz se o seu servidor aceitou: {"data": {"ok": true, "status_code": 200}}. Se a sua URL redirecionar (301/302/307), vem ok: false com esse código: cadastre a URL final, sem redirecionamento. O corpo do teste é diferente de uma cobrança:

{ "id": "ch_test_1a2b3c4d5e6f", "amount": 1990, "currency": "BRL", "status": "paid", "test": true }

Trocar o segredo

POST/v1/user/webhooks/{id}/rotate-secret

Resposta: {"data": {"id": 12, "secret": "whsec_…"}}. O novo segredo aparece só aqui e o antigo deixa de valer na hora — inclusive para as novas tentativas de avisos que ainda estão na fila. Atualize o seu servidor logo em seguida.

Histórico de entregas

GET/v1/user/webhooks/{id}/deliveries

Últimas entregas com event, status_code, success, attempts e created_at (até 200).

Webhooks

Verificando a assinatura

Todo webhook vem assinado com o secret do endpoint. Valide antes de qualquer outra coisa — e recuse avisos antigos para que ninguém reenvie um aviso capturado.

Cabeçalhos

HeaderConteúdo
X-Chase-Signature-V2t=<unix>,v1=<hex> — HMAC-SHA256 de "<t>." + corpo_bruto. Recomendado.
X-Chase-TimestampHorário do envio (segundos Unix), o mesmo t da V2.
X-Chase-Signaturesha256=<hex> — HMAC-SHA256 só do corpo bruto. Continua sendo enviado para quem já valida assim.
X-Chase-EventO tipo do evento (ex.: charge.paid).

Como validar (V2)

  1. Leia o corpo brutoOs bytes exatos que chegaram, antes de converter para JSON.
  2. Separe t e v1De X-Chase-Signature-V2.
  3. Confira o horárioRecuse se t estiver a mais de 300 segundos do seu relógio (ajuste o relógio do servidor com NTP).
  4. Calcule e comparehex(HMAC_SHA256(secret, t + "." + corpo_bruto)) igual a v1, comparando em tempo constante. Diferente? Responda 401.
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const app = express();
const SECRET = process.env.CHASE_WEBHOOK_SECRET; // whsec_…
const TOLERANCE = 300; // segundos

function validChase(raw, header) {
  const parts = Object.fromEntries(String(header || '').split(',').map(p => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > TOLERANCE) return false; // aviso antigo ou sem horário
  const expected = Buffer.from(createHmac('sha256', SECRET).update(`${t}.`).update(raw).digest('hex'));
  const received = Buffer.from(String(parts.v1 || ''));
  return received.length === expected.length && timingSafeEqual(received, expected);
}

// express.raw ANTES de qualquer express.json nesta rota
app.post('/webhooks/chase', express.raw({ type: 'application/json' }), (req, res) => {
  if (!validChase(req.body, req.get('X-Chase-Signature-V2'))) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  res.sendStatus(200);   // responda rápido
  queue.add(event);      // processe em segundo plano (deduplique por event.id)
});
<?php
$raw = file_get_contents('php://input');
$secret = getenv('CHASE_WEBHOOK_SECRET');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_CHASE_SIGNATURE_V2'] ?? ''), $parts);
$t = (int)($parts['t'] ?? 0);

if (!$t || abs(time() - $t) > 300) { http_response_code(401); exit; }   // aviso antigo
$expected = hash_hmac('sha256', $t . '.' . $raw, $secret);
if (!hash_equals($expected, (string)($parts['v1'] ?? ''))) { http_response_code(401); exit; }

$event = json_decode($raw, true);
http_response_code(200);
// grave $event['id'] e processe depois
import hmac, hashlib, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["CHASE_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/chase")
def chase_webhook():
    raw = request.get_data()  # corpo bruto
    parts = dict(p.split("=", 1) for p in request.headers.get("X-Chase-Signature-V2", "").split(",") if "=" in p)
    t = int(parts.get("t", "0") or 0)
    if not t or abs(time.time() - t) > 300:
        abort(401)  # aviso antigo
    expected = hmac.new(SECRET, f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        abort(401)
    event = request.get_json()
    # grave event["id"] e processe em segundo plano
    return "", 200

Validação simples (V1)

Integrações antigas validam só o corpo: "sha256=" + hex(HMAC_SHA256(secret, corpo_bruto)) igual a X-Chase-Signature. Continua funcionando, mas não protege contra reenvio de um aviso capturado — prefira a V2.

const expected = Buffer.from('sha256=' + createHmac('sha256', SECRET).update(raw).digest('hex'));
const received = Buffer.from(String(req.get('X-Chase-Signature') || ''));
const ok = received.length === expected.length && timingSafeEqual(received, expected);

Checklist de segurança

  • Corpo bruto. Re-serializar o JSON muda os bytes e a assinatura não bate.
  • Recuse avisos com mais de 5 minutos (V2) e deduplique pelo id do evento: novas tentativas repetem o mesmo evt_… com horário novo.
  • Confira no seu banco. O pedido do external_id existe, ainda não foi liberado e o amount_cents é o esperado.
  • Segredo vazou? POST /v1/user/webhooks/{id}/rotate-secret gera outro (veja Webhooks).
  • Na dúvida, consulte. GET /v1/transactions/by-external/{external_id} confirma o status direto na Chase.

Guia

MED e contestações

Quando um comprador contesta um pagamento (no Pix, pelo Mecanismo Especial de Devolução — MED), a Chase abre uma contestação na sua conta, bloqueia o valor envolvido e você tem a chance de se defender com texto e anexos.

Como funciona

open→under_review→acceptedourejected
StatusSignificadoValor
openContestação aberta, aguardando sua defesa.Bloqueado no saldo.
under_reviewDefesa enviada (ou contestação reconhecida) e em análise pela instituição.Continua bloqueado.
acceptedContestação procedente: o valor é devolvido ao comprador.Sai do saldo; a cobrança vira refunded.
rejectedContestação improcedente: a venda é mantida.Liberado de volta ao seu saldo.

O campo frozen_cents mostra quanto está bloqueado por aquela contestação agora. Enquanto houver contestação aberta, esse valor não pode ser sacado.

Prazo

O prazo de resposta é definido pelo Banco Central para cada MED. Envie a defesa assim que a contestação aparecer — a defesa é enviada uma única vez.

Listar contestações

GET/v1/user/disputes

Retorna todas as contestações da conta, da mais recente para a mais antiga.

{
  "data": [
    {
      "id": 318,
      "transaction_id": 90412,
      "status": "open",
      "reason": "produto_nao_recebido",
      "reason_label": "Produto não recebido",
      "amount_cents": 15900,
      "frozen_cents": 15900,
      "tx_external_id": "pedido-2026-0042",
      "tx_amount_cents": 15900,
      "tx_paid_at": "2026-11-02 14:31:08",
      "product_name": "Curso completo",
      "buyer_name": "Amanda Carvalho",
      "buyer_document": "52998224725",
      "buyer_email": "amanda@example.com",
      "evidence": [],
      "created_at": "2026-11-10 09:12:44",
      "updated_at": "2026-11-10 09:12:44"
    }
  ]
}
CampoDescrição
idintegerID da contestação. Use nas rotas abaixo.
statusstringopen, under_review, accepted ou rejected.
reason / reason_labelstringMotivo: nao_autorizado, produto_nao_recebido, produto_defeituoso, fraude, valor_divergente, duplicidade. Outros motivos aparecem como “Transação contestada”.
amount_centsintegerValor contestado.
frozen_centsintegerValor bloqueado agora por esta contestação.
tx_external_idstringO external_id da cobrança original — ligue ao seu pedido por ele.
buyer_*string | nullDados do comprador: nome, documento, e-mail, telefone, cidade e UF, quando existirem.
evidencearrayDefesas já enviadas: description, attachments e submitted_at.

A resposta pode trazer outros campos internos; use apenas os documentados acima.

Consultar uma contestação

GET/v1/user/disputes/{id}

Mesmo formato de um item da lista. Retorna 404 se a contestação não for da sua conta.

Enviar anexo

POST/v1/user/disputes/{id}/upload

Envie um arquivo por chamada, em multipart/form-data, no campo file. A resposta traz a url que você usa na defesa.

curl -X POST "https://api.chasepay.com.br/v1/user/disputes/318/upload" \
  -H "Authorization: Bearer $CHASE_API_KEY" \
  -F "file=@comprovante-entrega.pdf"
import { readFile } from 'node:fs/promises';

const form = new FormData();
form.append('file', new Blob([await readFile('comprovante-entrega.pdf')], { type: 'application/pdf' }), 'comprovante-entrega.pdf');
const res = await fetch('https://api.chasepay.com.br/v1/user/disputes/318/upload', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CHASE_API_KEY}` },
  body: form
});
const { data } = await res.json();
console.log(data.url);
<?php
$ch = curl_init('https://api.chasepay.com.br/v1/user/disputes/318/upload');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CHASE_API_KEY')],
  CURLOPT_POSTFIELDS => ['file' => new CURLFile('comprovante-entrega.pdf', 'application/pdf')],
]);
$data = json_decode(curl_exec($ch), true)['data'];
echo $data['url'];
import os, requests

with open("comprovante-entrega.pdf", "rb") as f:
    res = requests.post(
        "https://api.chasepay.com.br/v1/user/disputes/318/upload",
        headers={"Authorization": f"Bearer {os.environ['CHASE_API_KEY']}"},
        files={"file": ("comprovante-entrega.pdf", f, "application/pdf")},
        timeout=60,
    )
res.raise_for_status()
print(res.json()["data"]["url"])
{
  "data": {
    "url": "https://api.chasepay.com.br/uploads/disputes/318/ev_6551f2c1a8b3e4.12345678_comprovante-entrega.pdf",
    "name": "comprovante-entrega.pdf"
  }
}

Use PDF, JPG ou PNG de até 8 MB

Acima de 8 MB o envio é recusado com 413 (resposta em HTML, não JSON). Algumas contestações aceitam também GIF e WEBP, mas PDF, JPG e PNG são aceitos em todas. Mande no máximo 5 anexos por defesa.

Enviar a defesa

POST/v1/user/disputes/{id}/evidence
CampoDescrição
descriptionobrigatóriostringSua defesa, de 1 a 5.000 caracteres. Explique a entrega, o contato com o comprador e o que comprova a venda.
attachmentsopcionalarray de stringAs url devolvidas pelo upload desta mesma contestação (até 5).

A resposta traz a contestação atualizada, com status: "under_review" e a defesa em evidence.

Envie a defesa uma vez só

Revise o texto e os anexos antes de enviar. Só contestações open ou under_review aceitam defesa; encerradas devolvem 409, e em várias delas uma segunda resposta também dá 409. Se receber 503 (“não confirmou o envio”), não reenvie: fale com o suporte para conferir.

Reconhecer a contestação

POST/v1/user/disputes/{id}/accept

Use quando você concorda com o comprador e não vai se defender. A contestação passa para under_review e a instituição conclui a devolução. Reconhecer não move dinheiro na hora. Sem corpo na requisição.

Erros comuns

HTTPQuando
404Contestação não encontrada nesta conta (“Disputa não encontrada” na consulta; “Registro não encontrado.” nas ações).
400Upload sem arquivo, com erro de envio ou tipo não permitido. Esses erros vêm como {"data": {"error": "no file" | "upload error" | "tipo de arquivo nao permitido"}}.
413Arquivo acima de 8 MB (resposta em HTML).
409Contestação já concluída, defesa já enviada ou em processamento.
422Defesa vazia ou acima de 5.000 caracteres, anexo inválido, ou mais de 5 anexos.
503A instituição não confirmou o envio. Não reenvie; fale com o suporte.

No webhook

MomentoCobrançaEvento
Chega uma MED ou contestação do bancochargebackcharge.chargeback
Você pede reembolso pela APIdisputedcharge.disputed
Encerrada com devolução ao compradorrefundedcharge.refunded
Encerrada com a venda mantidapaidsem evento — consulte a contestação ou a cobrança

Para acompanhar o fim de uma contestação sem evento, consulte GET /v1/user/disputes/{id} ou GET /v1/transactions/by-external/{external_id} uma vez por dia. Veja Webhooks.

Referência da API

Todos os endpoints

Base https://api.chasepay.com.br, header Authorization: Bearer {chave}. Clique para ver detalhes e exemplos.

Cobranças

POST/v1/chargesCriar cobrança Pix, boleto ou cartão
GET/v1/transactionsListar cobranças com filtros
GET/v1/transactions/by-external/{external_id}Consultar pelo seu ID
GET/v1/transactions/{id}Consultar pelo ID interno
POST/v1/charges/{id}/refundPedir reembolso
GET/pub/card-payments/{id}/statusStatus público do pagamento com cartão (sem chave)

Checkout

POST/v1/user/productsCriar produto
GET/v1/user/productsListar produtos
POST/v1/user/checkoutsCriar checkout
GET/v1/user/checkoutsListar checkouts
PUT/v1/user/checkouts/{id}Alterar ou desativar checkout

Saldo e saques

GET/v1/balanceSaldo disponível, em liberação e bloqueado
GET/v1/balance/breakdownSaldo por método
POST/v1/payoutsSolicitar saque Pix
GET/v1/payoutsListar saques
GET/v1/payouts/{id}Consultar saque

Webhooks

POST/v1/user/webhooksCadastrar endpoint
GET/v1/user/webhooksListar endpoints
PUT/v1/user/webhooks/{id}Atualizar endpoint
DELETE/v1/user/webhooks/{id}Remover endpoint
POST/v1/user/webhooks/{id}/testEnviar teste
POST/v1/user/webhooks/{id}/rotate-secretTrocar o segredo
GET/v1/user/webhooks/{id}/deliveriesHistórico de entregas

MED e contestações

GET/v1/user/disputesListar contestações
GET/v1/user/disputes/{id}Consultar contestação
POST/v1/user/disputes/{id}/uploadEnviar anexo
POST/v1/user/disputes/{id}/evidenceEnviar defesa
POST/v1/user/disputes/{id}/acceptReconhecer contestação

Conta, cupons, domínio e rastreamento

GET/v1/feesTaxas da conta
GET/v1/user/limitsLimites de saque e uso do dia
PATCH/v1/user/products/{id}Alterar produto
DELETE/v1/user/products/{id}Apagar produto
POST/v1/user/couponsCriar cupom (também GET, PATCH e DELETE)
POST/v1/user/domainsCadastrar domínio próprio
POST/v1/user/domains/{id}/verifyVerificar DNS
POST/v1/user/integrationsLigar integração de rastreamento (também GET, PUT e DELETE)

Contrato completo em JSON (OpenAPI 3.1): botão OpenAPI (JSON) no canto da página. Importe no Postman, Insomnia ou gerador de SDK.

Referência da API

Status das cobranças

Só paid confirma pagamento. Todo o resto é espera, recusa ou devolução.

StatusSignificadoEvento
pendingPix ou boleto aguardando pagamento. Pix expirado pode continuar pending (depende da conta). Em contas com retenção, uma venda paga pode ficar pending até a liberação pela Chase; o charge.paid chega na liberação.charge.pending (na criação)
pending_paymentCartão em análise ou aguardando autenticação.charge.pending
processingResposta do banco incerta. Consulte de novo; não crie outra.—
paidPago. Libere o pedido.charge.paid (e, na maioria, charge.received)
failedRecusado, cancelado ou expirado.charge.failed (quando houver recusa)
disputedReembolso pedido por você, valor bloqueado.charge.disputed
chargebackContestação do banco ou MED.charge.chargeback
refundedValor devolvido ao comprador.charge.refunded
pending          → paid | failed            (Pix e boleto)
pending_payment  → paid | failed            (cartão)
paid             → disputed → refunded | paid   (reembolso pedido)
paid             → chargeback → refunded | paid (MED / contestação)
paid             → refunded                  (devolução direta)

Ao voltar de disputed ou chargeback para paid, nenhum evento é enviado — consulte a cobrança ou a contestação.

Referência da API

Códigos de erro

Erros vêm como {"error": {"message": "…"}}, às vezes com code (ex.: invalid_payment_data) ou transaction_id. Mostre a mensagem ao seu time, não ao comprador.

HTTPSignificadoO que fazer
400Requisição malformada (JSON inválido, upload sem arquivo).Corrija o corpo.
401Chave ausente, inválida, revogada ou vencida.Veja Autenticação.
403Conta pendente, bloqueada ou suspensa; chave de API em rota administrativa; recebimento ou saque desativado; cadastro (KYC) não aprovado; método não liberado; PIN de saque.Leia a mensagem; fale com o suporte se for da conta.
404Recurso não existe nesta conta.Confira o ID.
409external_id já usado; operação em andamento; contestação já respondida.Consulte o recurso existente. Não repita.
422Validação: campo faltando, valor fora do limite, documento inválido, cartão recusado.Corrija os dados conforme a mensagem.
429Muitas requisições ou cobrança duplicada. Pode vir em HTML.Espere e tente com pausa crescente.
500Erro interno.Consulte pelo external_id antes de repetir.
502 / 503Instabilidade no processamento ou serviço pausado. Com transaction_id, a cobrança ficou em processing.Consulte antes de repetir.

Exemplos de 422

{"error":{"message":"Campo obrigatório: amount_cents"}}
{"error":{"message":"external_id já utilizado. Consulte em GET /v1/transactions/by-external/pedido-1001"}}
{"error":{"message":"Ative pelo menos um meio de pagamento disponível para este checkout."}}
{"error":{"message":"Valor acima do limite de cartão."}}

Referência da API

Novidades

O que mudou na documentação e na API. Nenhuma mudança quebra integrações existentes.

16/11/2026 — Integrar com IA

  • Novo botão Integrar com IA no topo da documentação: copia as regras de integração e a documentação inteira para colar no Claude Code, Codex, Cursor ou ChatGPT.

16/11/2026 — Conferir de quem é a chave

  • Nova rota GET /v1/account: devolve o nome da conta e o CPF ou CNPJ do lojista (e o nome da chave usada), sem número interno. Veja Conferir de quem é a chave.
  • Nenhuma rota existente mudou.

16/11/2026 — OpenAPI completo

  • O openapi.json passa a trazer todas as rotas desta documentação e continua com tudo o que já tinha: boleto proposta, status do cartão (/pub/card-payments/{external}/status), consulta por external_id e source no saque.
  • Mudou só um nome: a operação de teste do boleto proposta agora se chama validateBoletoProposal, e o esquema de referência do registro no banco, ProposalBankRegistration. Rota, corpo e resposta são os mesmos.

16/11/2026 — Boleto proposta na documentação nova

  • A página Boleto proposta voltou à documentação, com as mesmas âncoras de antes (emissão, rotas, fluxo e conciliação). Nenhuma rota mudou.
  • Para emitir boleto — normal ou proposta — o boleto precisa estar ativo na conta.

16/11/2026 — Checkout no modelo do builder

  • Novo Checkout Brasil do builder: Pix na própria página (QR Code e copia e cola) e/ou cartão na página segura, com a identidade visual da sua marca. Também pela API.
  • Cartão no checkout: o comprador paga na página segura de cartão e escolhe as parcelas lá; taxa e prazo do link de cartão (normal ou Nitro). Assinatura no cartão e cartão internacional não mudam.
  • Checkouts simples criados pelo painel ou pelo app passam a ser salvos no modelo do builder. Pela chave de API, o formato enviado é mantido; checkouts existentes não mudam.
  • Nenhuma rota, campo ou webhook foi removido.

16/11/2026 — Checkout no idioma do comprador

  • O checkout aparece em português, inglês ou espanhol, conforme o país de acesso do comprador, com seletor PT · EN · ES na página. Vale para todos os checkouts, em checkout.chasepay.com.br e no domínio próprio, sem configurar nada.
  • Para fixar o idioma, acrescente ?lang=pt, en ou es ao link. Textos que você escreveu (produto, descrição, mensagens) não são traduzidos. Veja Idioma do comprador.
  • Nenhuma rota, campo ou webhook mudou.

16/11/2026 — Cartão pela API: página de pagamento

  • POST /v1/charges com method: "card" agora responde 202 com status: "requires_action" e payment_url: o comprador paga na página de pagamento segura da Chase, numa nova aba. Não é mais preciso enviar cartão, módulo de segurança nem IP do comprador. Veja Cartão no seu site.
  • Quem ainda envia card, device e browser continua sendo aceito: os dados são ignorados (card_data_ignored: true) e a resposta traz a página de pagamento. O status_url continua público e o webhook charge.paid sai com o seu external_id.
  • Taxa e prazo do cartão pela API são os da venda por link (card_link_normal ou card_link_nitro em GET /v1/fees). Escolha por cobrança com "receiving": "normal" ou "nitro"; sem o campo, vale a opção do painel.

16/11/2026 — Correções na API

  • Alterar checkout aceita só o que muda (ex.: {"active": false}); antes respondia 422.
  • Cupom com código repetido responde 409 “Já existe um cupom com este código.”; antes, 500.
  • Cobrança pela API com checkout_slug e cupom registra discount_cents e conta o uso do cupom (max_uses).
  • Mensagens de erro e campos das respostas não citam mais o nome de operadoras de pagamento (boleto_issuer e boleto_nominal vêm vazios; details_source vem provider, stored ou demo).
  • Segurança: chave de API não acessa rotas administrativas; webhooks com X-Chase-Timestamp e X-Chase-Signature-V2 contra reenvio; nova rota para trocar o segredo do webhook. Nova página Segurança.
  • A trava de “Cobrança duplicada” só conta cobranças criadas: erro barrado antes de criar a cobrança (campo faltando) não conta mais.
  • A API respeita as travas da conta em todas as rotas de dinheiro: cobrança com recebimento desativado responde 403; saque de comissão segue as mesmas travas do saque comum.
  • PIN de saque com limite de tentativas: 5 erros em 15 minutos (ou 10 no dia) bloqueiam novas tentativas com 429. PIN certo continua funcionando como antes.
  • Defesa de MED: contestação encerrada não pode ser reaberta (409); texto de 1 a 5.000 caracteres e até 5 anexos em todas as contestações.

Nada que já existia mudou de formato: só foram acrescentados rota, cabeçalhos e travas. Integrações existentes continuam funcionando.

16/11/2026 — Documentação nova

  • Nova organização em guias, com exemplos em cURL, Node.js, PHP e Python e botões para usar com IA.
  • Novas páginas: MED e contestações, Cartão internacional, Rastreamento (UTM) e integrações, Limites e taxas da conta.
  • Checkout completo: cupons, order bump, upsell, mensagem de obrigado, domínio próprio e edição de produto.
  • Webhooks: passo a passo de criação, erros do cadastro, novas tentativas e exemplo do evento de saque.
  • Novas rotas documentadas: /v1/fees, /v1/user/limits, /v1/transactions/{id}/details, /v1/user/customer-list, /v1/user/api-keys.
  • OpenAPI 3.1 novo e coleção para Postman/Insomnia.

Correções em relação à documentação anterior

AntesComo funciona de verdade
Checkout com settings.advanced.payCardUse settings.card e settings.pix. O campo antigo não liga o meio de pagamento.
Saque com totp_codeSaque usa pin (quando a conta tem PIN) e aceita key_type.
Webhook sem novas tentativasAté 5 envios: depois de 1, 5, 15 e 60 minutos, com o mesmo evt_….
charge.created, charge.expired, balance.updatedAceitos no cadastro, mas hoje não são enviados.
MED gera charge.disputedMED do banco gera charge.chargeback; charge.disputed é quando você pede reembolso.
Chave sem validadeA chave vale 365 dias, e trocar a senha revoga todas.