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ó comoYYYY-MM-DD. - Sem ambiente de teste separado. Toda chamada é real. Para testar, use o valor mínimo e um
external_idque 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
- AutenticaçãoCrie a chave no painel e guarde no servidor.
- Depósitos ou Checkout nativoEscolha entre cobrar pela API ou mandar o comprador para a página pronta da Chase.
- Webhooks e assinaturaReceba a confirmação no seu servidor e valide a assinatura antes de liberar o pedido.
- 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
- Abra o painelEm Integrações → API, toque em Nova credencial e dê um nome (ex.: “Loja produção”).
- 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. - 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
| HTTP | Mensagem | O que fazer |
|---|---|---|
401 | Nã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 . |
401 | API key invalida. | A chave foi apagada ou o segredo não confere (ex.: segredo antigo depois de um reset). |
401 | API key revogada. | A chave foi revogada pela troca de senha da conta. Crie outra. |
403 | Conta pendente de aprovação. Aguarde a análise do seu cadastro. | A conta ainda está em análise. Aguarde a aprovação. |
403 | Conta 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" }
}
}keyvem 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,suspendedoublocked.kyc_status:approved,pendingourejected.- 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
- Crie a nova chaveNo painel ou por
POST /v1/user/api-keys. A antiga continua funcionando. - Atualize seus sistemasTroque a variável
CHASE_API_KEYe reinicie os serviços. - Confira o usoEm
GET /v1/user/api-keys, olast_used_atda nova deve mudar e o da antiga parar. - Apague a antiga
DELETE /v1/user/api-keys/{id}.
Gerenciar chaves pela API
/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.
/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.”).
/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.
/v1/user/api-keys/{id}/resetGera 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.
- Crie a chave de APINo painel, em Integrações → API. Guarde o segredo em
CHASE_API_KEYno servidor. Veja Autenticação. - Cadastre o webhookUma vez só, com a URL HTTPS do seu servidor. Guarde o
secretque volta na resposta. - Crie a cobrançaCom o valor em centavos e o
external_iddo seu pedido. - Mostre o Pix e espere o webhookExiba
pix_qr_code(copia e cola) e o QR Code. Libere o pedido quando chegarcharge.paidcom 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 umtx_…. - Repetir um
external_idjá usado devolve409— não devolve a cobrança original. Busque-a comGET /v1/transactions/by-external/{external_id}. - O
external_idfica 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-Keyna 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
| Limite | Valor | Resposta |
|---|---|---|
| Requisições por IP | 30 por segundo (picos de até 60) | 429 em HTML, não JSON |
| Cobranças por conta | 20 por minuto e 1.500 por hora | 429 |
| Cobranças por documento do comprador | 30 por hora | 429 |
| Mesma cobrança repetida | Mesmo 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 webhook | 5 por minuto | 429 |
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étodo | Mínimo | Máximo por cobrança |
|---|---|---|
| Pix | R$ 10,00 (1000) | R$ 2.000,00 (200000) |
| Boleto | R$ 1,00 (100) | R$ 100.000,00 (10000000) |
| Cartão | R$ 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
/v1/feesAs 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
}
}| Campo | Descrição |
|---|---|
pix / boleto / card | pct (porcentagem) + fixed_cents (fixo em centavos) por venda paga. custom: true = condição própria da sua conta. |
card.installment_rates | Taxa total por número de parcelas ("1" a "12"), em %. |
withdrawal | Taxa de cada saque. |
card_link_normal / card_link_nitro | Cartã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_enabled | Se 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
/v1/user/limitsMí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
}
}| Campo | Descrição |
|---|---|
cashout_enabled | Se a conta pode sacar agora. |
pin_active | Se o saque exige o campo pin. |
min_withdrawal_cents / max_withdrawal_cents | Menor e maior saque permitido. |
daily_limit_cents / daily_used_cents | Limite do dia e quanto já foi usado (dia no horário de Brasília). Disponível hoje = limite − usado. |
daily_withdrawal_count | Máximo de saques por dia (0 = sem limite). Não é a contagem dos saques já feitos. |
withdrawal_pct / withdrawal_fix_cents | Taxa de saque. |
pix_settlement_days / card_settlement_days | Prazo 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
| Tentativa | O que acontece |
|---|---|
| Mudar o próprio saldo, taxa, limite, status da conta, KYC ou cargo enviando esses campos | Os 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 administrativas | 403 “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 iframe | 403. 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 conta | Tudo é filtrado pela conta da chave: o recurso de outra conta responde 404. |
| Reabrir uma contestação (MED) já encerrada | 409 “Contestação já concluída.” |
| Cobrar com recebimento desativado ou sacar com saque desativado / KYC pendente | 403. Vale para cobrança, saque, comissão de indicação e pagamentos. |
| Sacar mais do que o disponível ou repetir saque ao mesmo tempo | 422 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 pedido | external_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
429até 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-TimestampeX-Chase-Signature-V2, que amarram a assinatura ao horário do envio.
Do seu lado:
- Valide a assinaturaCom o corpo bruto e comparação em tempo constante. Veja Verificando a assinatura.
- 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. - DedupliqueGuarde o
id(evt_…) de cada aviso processado e ignore repetidos. - 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. - Segredo vazou?Gere outro com
POST /v1/user/webhooks/{id}/rotate-secrete 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
/v1/chargesResponde 201 com a cobrança em pending. 201 não é pagamento aprovado: espere o webhook ou consulte o status.
Parâmetros
| Campo | Descrição |
|---|---|
methodobrigatóriostring | pix, boleto ou card (minúsculo). Cartão: veja Cartão no seu site. |
amount_centsobrigatóriointeger | Valor em centavos. Pix: 1.000 a 200.000. Boleto e cartão: 100 a 10.000.000. |
external_idrecomendadostring | ID do seu pedido, até 64 caracteres, único por conta. Veja Idempotência. |
descriptionopcionalstring | 3 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.namerecomendadostring | Nome completo do comprador. |
customer.documentrecomendadostring | CPF (11 dígitos) ou CNPJ (14), só números. |
customer.emailopcionalstring | E-mail válido do comprador. |
customer.phoneopcionalstring | Telefone com DDD. |
payer_name, payer_document, payer_phoneopcionalstring | Atalhos 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 conta | Resposta |
|---|---|
| Recebimento desativado pela Chase | 403 “Recebimentos desativados para esta conta. Fale com o suporte.” |
| Cartão ou boleto não liberados | 403 “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 aprovado | 403 “Checkout temporariamente indisponível.” (vale também para a API) |
| Pagamentos pausados pela plataforma | 503 “Plataforma temporariamente indisponível para novos pagamentos.” |
| Método pausado pela plataforma | 503 “Este método de pagamento está temporariamente indisponível.” |
| Conta pendente, bloqueada ou suspensa | 403 (veja Autenticação) |
Boleto
Campos da resposta
| Campo | Descrição |
|---|---|
idinteger | ID interno da cobrança. |
external_idstring | O seu ID (ou o tx_… gerado). |
statusstring | Veja Status das cobranças. |
amount_cents / fee_cents / net_centsinteger | Valor cobrado, taxa da Chase e quanto entra no seu saldo. |
pix_qr_codestring | null | Pix copia e cola. |
pix_qr_urlstring | null | Imagem PNG do QR Code. Mostre direto ao comprador. |
boleto_line / boleto_url / boleto_duestring | null | Linha digitável, PDF e vencimento (YYYY-MM-DD). Só nas cobranças de boleto. |
payer_name / payer_documentstring | null | Quem pagou (no Pix, preenchido pelo banco depois do pagamento). |
paid_at / created_at / updated_atstring | Horá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
/v1/transactions| Query | Descrição |
|---|---|
status | Filtra por status (ex.: paid, pending, failed). |
method | pix, boleto ou card. |
q | Busca no external_id, nome do pagador ou descrição. |
from / to | Período pela data de criação, YYYY-MM-DD. |
movement_from / movement_to | Período pela data do pagamento (ou criação, se não pago). |
period | Atalho: hoje, 7, 30 ou 90 dias. |
page / limit | Paginaçã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
/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
/v1/transactions/{id}/detailsInformações extras de uma venda: cartão, prazo de liberação e origem. {id} é o ID interno (número).
| Campo | Descrição |
|---|---|
card_brand / card_last4 / installments | Bandeira, final do cartão e parcelas (só cartão). |
authorization_code | Código de autorização do cartão, quando houver. |
end_to_end_id / payer_bank | Identificador do Pix e banco de quem pagou, quando disponíveis. |
release_at | Quando o valor vira saldo disponível. |
settlement_state | scheduled (agendado), released (liberado), early (antecipado), not_paid ou unknown. |
settlement_days / settlement_business_days | Prazo de liberação e se é em dias úteis. |
source_type / source_name / source_domain | Origem da venda (ex.: checkout) e o site, quando informado em source_site. Em cobrança pela API sem source_site, vem null. |
checkout_name | Nome 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
| Campo | Descrição |
|---|---|
source_siteopcionalstring | Domí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_idopcionalinteger | Se description vier vazia, usa o nome deste produto seu. |
boleto_dueopcionalstring | Vencimento do boleto, YYYY-MM-DD. Nem toda conta aceita vencimento personalizado: confira boleto_due na resposta. |
checkout_slugopcionalstring | Cobra 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_centscontinua obrigatório no corpo, mas o valor final é o calculado pelo checkout. Confiraamount_centsna 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 emdiscount_centse conta um uso do cupom (respeitamax_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
/v1/charges/{id}/refundSem 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
/v1/user/customer-listTodos 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
/v1/user/customers-summary| Query | Descrição |
|---|---|
page / limit | Paginação. limit de 10 a 100 (padrão 50). |
q | Busca por nome, e-mail ou documento. |
period | today, 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. |
status | ativo, pendente ou inativo. |
customer_id | Detalhe 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.
1. Criar o produto
/v1/user/products| Campo | Descrição |
|---|---|
nameobrigatóriostring | Nome que o comprador vê, até 255 caracteres. |
price_centsobrigatóriointeger | Preço em centavos, de 100 (R$ 1,00) a 99.999.900. |
activeopcionalboolean | Produto disponível para venda. |
description, image_url, skuopcionalstring | Descrição, imagem (HTTPS) e código interno (letras, números, ., -, _; único na conta). |
Guarde o data.id da resposta.
2. Criar o checkout
/v1/user/checkouts| Campo | Descrição |
|---|---|
nameobrigatóriostring | Nome interno do checkout. |
product_idsobrigatórioarray | IDs dos seus produtos (criados no passo 1). |
settings.pixopcionalboolean | Aceitar Pix. |
settings.cardopcionalboolean | Aceitar cartão de crédito (a conta precisa ter cartão liberado). |
settings.ui.installments / parcelasMaxopcionalinteger | Aceito 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.customerPaysInterestopcionalboolean | Aceito e guardado. Os juros do parcelamento são pagos pelo comprador na página segura de cartão. |
settings.ui.redirecionar + urlRedirectopcional | Leva o comprador para a sua página (HTTPS) depois do pagamento. |
slugopcionalstring | Final 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.slugda 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
/v1/user/subscriptionsLista 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).
/v1/user/subscriptions/{id}/cancelMande 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.
/v1/user/coupons| Campo | Descrição |
|---|---|
codeobrigatório | O código que o comprador digita. Maiúsculas e minúsculas são iguais. |
typeobrigatório | percent (porcentagem) ou fixed (valor fixo). |
valueobrigatório | percent: de 1 a 100. fixed: desconto em centavos (1000 = R$ 10,00). |
max_usesopcional | Quantas vezes pode ser usado no total. Sem ele, ilimitado. |
expires_atopcional | Validade, YYYY-MM-DD HH:MM:SS (Brasília). |
activeopcional | Pausar 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 emproduct_idsautomaticamente.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_normaloucard_link_nitroemGET /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.
| Campo | Descrição |
|---|---|
settings.ui.webMarketBuilder + webBrlInfinityobrigatórioboolean | true nos dois: checkout Brasil do builder. |
settings.ui.webPriceCentsobrigatóriointeger | Preç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.cardopcionalboolean | Formas 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, logoTextopcionalstring | Título no checkout, descrição (até 2.000 caracteres) e nome da marca no topo. |
settings.ui.studioBackground / studioButtonopcionalstring | Cores do fundo do resumo e do botão (#RRGGBB). |
settings.ui.studioFont / studioBorderopcionalstring | Fonte (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).
- Cadastre o domínio
POST /v1/user/domainscom{"domain": "pagar.sualoja.com.br"}. A resposta trazid,verification_tokenecname_target. - Configure o DNSCrie um registro
TXTem_chase.pagar.sualoja.com.brcom o valorchase-verify={verification_token}e umCNAMEdepagar.sualoja.com.brpara ocname_target. - Verifique
POST /v1/user/domains/{id}/verifydepois que o DNS propagar (pode levar algumas horas). - Use no checkoutEnvie
"domain": "pagar.sualoja.com.br"ao criar ou alterar o checkout.
Editar e apagar produto
/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.
/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.
- 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.
- 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.
- 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.
| Acompanhamento | Como |
|---|---|
| Venda criada | A cobrança aparece como pending, com external_id começando por ip_. Não há charge.pending. |
| Pagamento aprovado | Status paid e evento charge.paid (sem charge.received). |
| Consulta | GET /v1/transactions/by-external/ip_…. A URL pública /pub/card-payments/…/status não vale para este link. |
| Cancelamento ou estorno | Não gera webhook: a venda volta para análise. Acompanhe pelo painel. |
Alterar ou desativar
/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
- No painel, crie um link de pagamentoInforme o nome e escolha pagamento único.
- Escolha a moeda e o preçoSelecione a moeda do comprador (ex.: USD) e o valor nessa moeda, de 1 a 1.000.000.
- 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=enno 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
| Pagamento | Só cartão, à vista. Sem Pix, boleto, parcelamento ou assinatura em moeda estrangeira. |
| Extras | Cupom, order bump e upsell ficam desligados. |
| Taxa | Hoje, 15% + R$ 4,80 sobre o valor convertido em reais. Confira a taxa atual da sua conta no painel. |
| Limite | O valor convertido não pode passar do teto de venda no cartão da sua conta. |
| Conta | Precisa estar aprovada, com recebimento e cartão liberados. |
Status e webhooks
- Pagamento aprovadoA venda aparece como
processing, com “saldo em conversão” na descrição. Ainda não é dinheiro disponível. - Conversão concluídaA Chase converte para reais, atualiza
amount_cents,fee_centsenet_centsem reais e muda parapaid. Nesse momento chegamcharge.paidecharge.received. - 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ão | Na página da Chase | Na página de pagamento segura da Chase (nova aba) |
| Você lida com número do cartão | Não | Não |
| Quem cria a venda | O link do checkout | O seu servidor, com o seu pedido (external_id) |
| Pix e boleto na mesma tela | Sim | Não (crie a cobrança Pix ou boleto à parte) |
| Esforço | Criar o link e ouvir o webhook | Uma 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
- Seu servidor cria a cobrançaPega o preço do seu banco de dados (nunca do navegador) e chama
POST /v1/chargescommethod: "card". Não precisa de dados do cartão. - A API devolve a página de pagamentoResposta
202comstatus: "requires_action"e o endereço empayment_url(o mesmo valor vem emredirect_url). - 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.
- Você confirma no servidorPelo webhook
charge.paidou 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_enabledemGET /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.paidecharge.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) oucard_link_nitro(recebe em 2 dias úteis, se o Nitro estiver ligado no painel). Veja os valores emGET /v1/fees. A resposta da cobrança trazfee_cents,net_cents,receivingerelease_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"responde422.
Passo 1 — Seu servidor cria a cobrança
/v1/charges| Campo | De onde vem | Regras |
|---|---|---|
methodobrigatório | Fixo | card (ou card_credit). |
amount_centsobrigatório | Seu banco de dados | Total final. Nunca aceite valor vindo do navegador. |
external_id | Seu pedido | Único. Volta no webhook e na consulta. Use um novo para cada nova tentativa. |
descriptionobrigatório | Seu produto | Nome 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. |
receiving | Você | "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.email | Comprador | Opcionais. 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
| Resposta | Significa | O que fazer |
|---|---|---|
202 + requires_action | Página de pagamento pronta. | Abra o payment_url numa nova aba (Passo 3). |
403 | Cartão não está liberado nesta conta (ou a conta não pode receber agora). | Fale com o seu gerente. Ofereça Pix. |
422 | Valor fora do limite de cartão, ou que não cobre a tarifa. | Mostre a mensagem. Para tentar de novo, use outro external_id. |
409 | external_id já usado. | Consulte a cobrança existente. Não crie outra. |
429 | Muitas 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, 503 | Resultado 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ágina | Vem de |
|---|---|
| Nome do produto | description (até 160 caracteres) |
| Valor e total | amount_cents. O comprador paga exatamente esse valor; a taxa da Chase sai do seu líquido (net_cents). |
| Nome da loja | O 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ão | O 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 Nitro | Nã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). |
- Abra o
payment_urlexatamente 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. - O link vale 24 horasAté
expires_at. Depois disso, crie uma nova cobrança com outroexternal_id. - 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.
- 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.paidcom a assinatura válida. Ao criar a cobrança, chegacharge.pending. - Consulta:
GET /v1/transactions/by-external/{external_id}comstatus: "paid". Antes do pagamento, a cobrança aparece comopending. - Confira
amount_centse 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
- Criar sem pagarCrie uma cobrança de R$ 1,00 a R$ 5,00. A resposta deve ser
202compayment_url. Abra a página e não pague: a cobrança ficapendinge o link vence em 24 horas. Nada é cobrado. - 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.
- 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
/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"
}
}| Campo | Regra |
|---|---|
idempotency_keyobrigatóriostring | 16 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óriointeger | Valor nominal em centavos (R$ 199,90 = 19990). Defina uma vez e mantenha em novas tentativas. |
payer_requested_proposalobrigatórioboolean | true: confirma que o cliente pediu a proposta. Fica na Chase; não vai para o banco. |
payer_request_referenceobrigatóriostring | Referê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órioobject | Nome (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_descriptionopcionalstring | 3 a 255 caracteres. Vazio usa a descrição padrão de /defaults. Vai no recibo do boleto e volta na resposta. |
offer_termsopcionalstring | Condiçõ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_dateignorado | Legado. 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
| Rota | O que faz |
|---|---|
GET /v1/boleto-proposals/defaults | Descrição e termos padrão. Não emite nada. |
POST /v1/boleto-proposals | Emissã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,124 | Até 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}/pdf | PDF do boleto (arquivo, sem JSON) para proposta registrada e aberta. Indisponível: 409. |
POST /v1/boleto-proposals/validate | Envia 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
- ArquivoCSV UTF-8 com cabeçalho
nome;cpf;email;endereco. Emendereco, useRua e número | Bairro | Cidade | UF | CEP. Planilhas antigas com endereço, bairro, cidade, UF e CEP em colunas separadas continuam aceitas. - 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.
- 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
}
}| Estado | O que fazer |
|---|---|
creating / uncertain | Não envie o boleto nem crie outra chave. Consulte e confira o original. |
pending | Registro aberto. Libere só depois de conferir. Ainda não é pagamento. |
payment_processing / paid_processing | Em compensação. Não presuma pagamento integral. |
paid_amount_pending | Pagamento indicado, valor ainda não confirmado. Não use o nominal no lugar. |
paid | Confira paid_cents == amount_cents antes de liberar o que foi vendido. |
paid_partial / paid_divergent | Pago a menos ou valor diferente do nominal. Confira à parte; não conta como integral. |
rejected / canceled / reversed | Recusado, 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:
401autenticação;403conta sem boleto ativo ou sem habilitação;404proposta não encontrada na conta;409chave em conflito, em processamento ou PDF indisponível;422dados inválidos;502banco indisponível ou retorno incompatível. Leia sempredata.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âmetro | Uso comum |
|---|---|
utm_source | Origem: facebook, google, tiktok, instagram. |
utm_medium | Tipo de tráfego: cpc, organico, email. |
utm_campaign | Campanha. |
utm_content | Criativo ou anúncio. |
utm_term | Pú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:
| Campo | Descrição |
|---|---|
ui.trackingAtivoobrigatório | true para carregar os pixels abaixo. |
ui.fbPixel | ID do Pixel do Meta (só números). |
ui.gtm | ID do Google Tag Manager (GTM-…). |
ui.ga4 | ID 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:
/v1/user/integrations| provider | config | Onde pegar |
|---|---|---|
utmify | token | Credencial (token) de API criada no painel da Utmify. |
xtracky | webhookUrl, token | URL de webhook e token do painel da xTracky. |
adoptify | webhookUrl, token | URL de webhook e token da Adoptify. |
otimizei | webhookUrl, token | URL de webhook e token da Otimizei. |
facebook | pixelId, 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:
PUTcom{"active": false}. Remover:DELETE /v1/user/integrations/{id}. - Listar:
GET /v1/user/integrations. POST /v1/user/integrations/{id}/testsó 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
/v1/payouts| Campo | Descrição |
|---|---|
amount_centsobrigatóriointeger | Valor pedido, em centavos. A taxa de saque é descontada dele. |
pix_keyobrigatóriostring | Chave Pix de destino. |
key_typerecomendadostring | cpf, cnpj, email, phone ou evp (aleatória). Com cpf, a chave precisa ser o CPF do titular da conta. |
pinse a conta tiver PINstring | PIN 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
| Status | Significado |
|---|---|
| pending | Aguardando aprovação manual da Chase (algumas contas). |
| processing / awaiting_admin | Em envio ou em conferência. Não peça de novo. |
| paid | Pago. end_to_end_id traz o identificador do Pix. |
| failed / cancelled / refunded | Nã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/limitsantes 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_idem saque. Em timeout, consulte a lista antes de pedir de novo.
Erros comuns
| HTTP | Mensagem |
|---|---|
403 | PIN de saque obrigatorio / PIN de saque incorreto. |
403 | Saques temporariamente desabilitados para esta conta. |
403 | Saques liberados somente apos aprovacao do KYC. |
409 | Outra solicitação de saque está em processamento. Tente novamente. (Pedidos simultâneos esperam até 10 s antes desse erro.) |
429 | Muitas tentativas de PIN incorretas. Tente novamente mais tarde. (5 erros em 15 min ou 10 no dia.) |
422 | Abaixo 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. |
503 | Saques pausados pela plataforma ou manutenção. Tente mais tarde. |
Listar e consultar saques
/v1/payoutsDo mais recente ao mais antigo, limit até 100. Resposta: {"data": [...], "total", "page", "limit"}.
/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
/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"
}
}| Campo | Descrição |
|---|---|
available_cents | Disponível para saque agora. |
settling_cents | Vendas pagas aguardando liberação (boleto e cartão), com o detalhe em settling_transactions e a data em release_at. |
blocked_cents | Bloqueado por MED, reembolso pedido ou análise. |
debt_cents | Débito da conta com a Chase (ex.: estorno maior que o saldo disponível). |
boleto_settlement_days / card_settlement_days | Prazo de liberação em dias úteis. |
received_cents / withdrawn_cents | Totais históricos recebidos e sacados. |
Saldo por método
/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
| Evento | Quando |
|---|---|
charge.pending | Cobranç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.paid | Pagamento aprovado. É o evento para liberar o pedido. |
charge.received | Enviado 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.failed | Pagamento recusado ou cancelado. |
charge.disputed | Você pediu reembolso; valor bloqueado em análise. |
charge.refunded | Valor devolvido ao comprador. |
charge.chargeback | Contestação do banco ou MED aberta. Veja MED. |
payout.created / payout.paid / payout.failed | Saque criado, pago ou com falha. |
webhook.test | Disparo 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_atdo evento vem em UTC (ISO 8601). As datas dentro dedatavêm no horário de Brasília.- Em eventos
charge.*,dataé a cobrança. Empayout.*, é o saque. datapode trazer campos internos além dos documentados. Use só os documentados; não dependa dos outros.
Entrega e novas tentativas
| Regra | Valor |
|---|---|
| Primeiro envio | Em até ~15 segundos depois do evento (os avisos saem por uma fila; um endpoint lento nunca atrasa o pagamento). |
| Sucesso | Resposta 2xx. Redirecionamentos não são seguidos. |
| Tempo limite | 8 segundos (3 s para conectar). |
| Novas tentativas | Até 5 envios no total: depois de 1, 5, 15 e 60 minutos. |
| Mesmo evento | Cada nova tentativa manda o mesmo corpo, com o mesmo id evt_…. |
| Evento desatualizado | Se 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
- Tenha uma chave de API ativaSem nenhuma chave, o cadastro é recusado. Veja Autenticação.
- Publique a URL que vai receberHTTPS, pública e já respondendo. O domínio precisa existir no DNS no momento do cadastro.
- CadastrePelo painel, na área de Webhooks, ou pela API, abaixo.
- Guarde o secretEle volta uma única vez e é usado para validar a assinatura.
- TesteUse Testar endpoint e confira que o seu servidor respondeu
200.
/v1/user/webhooks| Campo | Descrição |
|---|---|
urlobrigatóriostring | Endereço HTTPS do seu servidor. Não aceita IP privado, localhost ou rede interna. |
eventsrecomendadoarray | Eventos da tabela de eventos, ou ["*"] para todos. |
nameopcionalstring | Nome 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 emsuccess_count/fail_count. - O
secretaparece 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
| HTTP | Mensagem |
|---|---|
422 | Para criar webhooks voce precisa ter ao menos uma Chave de API ativa… |
422 | URL do webhook deve usar HTTPS. |
422 | URL do webhook invalida. (domínio não resolve no DNS) |
422 | URL do webhook nao pode apontar para enderecos privados. |
422 | Não inclua usuário ou senha na URL do webhook. |
422 | Evento 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
/v1/user/webhooksCada item traz success_count e fail_count das últimas 24 h, last_triggered, last_status_code e last_success.
Atualizar endpoint
/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
/v1/user/webhooks/{id}Resposta: {"data": {"deleted": true}}.
Testar endpoint
/v1/user/webhooks/{id}/testEnvia 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
/v1/user/webhooks/{id}/rotate-secretResposta: {"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
/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
| Header | Conteúdo |
|---|---|
X-Chase-Signature-V2 | t=<unix>,v1=<hex> — HMAC-SHA256 de "<t>." + corpo_bruto. Recomendado. |
X-Chase-Timestamp | Horário do envio (segundos Unix), o mesmo t da V2. |
X-Chase-Signature | sha256=<hex> — HMAC-SHA256 só do corpo bruto. Continua sendo enviado para quem já valida assim. |
X-Chase-Event | O tipo do evento (ex.: charge.paid). |
Como validar (V2)
- Leia o corpo brutoOs bytes exatos que chegaram, antes de converter para JSON.
- Separe
tev1DeX-Chase-Signature-V2. - Confira o horárioRecuse se
testiver a mais de 300 segundos do seu relógio (ajuste o relógio do servidor com NTP). - Calcule e compare
hex(HMAC_SHA256(secret, t + "." + corpo_bruto))igual av1, comparando em tempo constante. Diferente? Responda401.
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 depoisimport 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 "", 200Validaçã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
iddo evento: novas tentativas repetem o mesmoevt_…com horário novo. - Confira no seu banco. O pedido do
external_idexiste, ainda não foi liberado e oamount_centsé o esperado. - Segredo vazou?
POST /v1/user/webhooks/{id}/rotate-secretgera 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
| Status | Significado | Valor |
|---|---|---|
| open | Contestação aberta, aguardando sua defesa. | Bloqueado no saldo. |
| under_review | Defesa enviada (ou contestação reconhecida) e em análise pela instituição. | Continua bloqueado. |
| accepted | Contestação procedente: o valor é devolvido ao comprador. | Sai do saldo; a cobrança vira refunded. |
| rejected | Contestaçã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
/v1/user/disputesRetorna 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"
}
]
}| Campo | Descrição |
|---|---|
idinteger | ID da contestação. Use nas rotas abaixo. |
statusstring | open, under_review, accepted ou rejected. |
reason / reason_labelstring | Motivo: nao_autorizado, produto_nao_recebido, produto_defeituoso, fraude, valor_divergente, duplicidade. Outros motivos aparecem como “Transação contestada”. |
amount_centsinteger | Valor contestado. |
frozen_centsinteger | Valor bloqueado agora por esta contestação. |
tx_external_idstring | O external_id da cobrança original — ligue ao seu pedido por ele. |
buyer_*string | null | Dados do comprador: nome, documento, e-mail, telefone, cidade e UF, quando existirem. |
evidencearray | Defesas já enviadas: description, attachments e submitted_at. |
A resposta pode trazer outros campos internos; use apenas os documentados acima.
Consultar uma contestação
/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
/v1/user/disputes/{id}/uploadEnvie 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
/v1/user/disputes/{id}/evidence| Campo | Descrição |
|---|---|
descriptionobrigatóriostring | Sua defesa, de 1 a 5.000 caracteres. Explique a entrega, o contato com o comprador e o que comprova a venda. |
attachmentsopcionalarray de string | As 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
/v1/user/disputes/{id}/acceptUse 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
| HTTP | Quando |
|---|---|
404 | Contestação não encontrada nesta conta (“Disputa não encontrada” na consulta; “Registro não encontrado.” nas ações). |
400 | Upload 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"}}. |
413 | Arquivo acima de 8 MB (resposta em HTML). |
409 | Contestação já concluída, defesa já enviada ou em processamento. |
422 | Defesa vazia ou acima de 5.000 caracteres, anexo inválido, ou mais de 5 anexos. |
503 | A instituição não confirmou o envio. Não reenvie; fale com o suporte. |
No webhook
| Momento | Cobrança | Evento |
|---|---|---|
| Chega uma MED ou contestação do banco | chargeback | charge.chargeback |
| Você pede reembolso pela API | disputed | charge.disputed |
| Encerrada com devolução ao comprador | refunded | charge.refunded |
| Encerrada com a venda mantida | paid | sem 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/charges | Criar cobrança Pix, boleto ou cartão |
| GET | /v1/transactions | Listar 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}/refund | Pedir reembolso |
| GET | /pub/card-payments/{id}/status | Status público do pagamento com cartão (sem chave) |
Checkout
| POST | /v1/user/products | Criar produto |
| GET | /v1/user/products | Listar produtos |
| POST | /v1/user/checkouts | Criar checkout |
| GET | /v1/user/checkouts | Listar checkouts |
| PUT | /v1/user/checkouts/{id} | Alterar ou desativar checkout |
Saldo e saques
| GET | /v1/balance | Saldo disponível, em liberação e bloqueado |
| GET | /v1/balance/breakdown | Saldo por método |
| POST | /v1/payouts | Solicitar saque Pix |
| GET | /v1/payouts | Listar saques |
| GET | /v1/payouts/{id} | Consultar saque |
Webhooks
| POST | /v1/user/webhooks | Cadastrar endpoint |
| GET | /v1/user/webhooks | Listar endpoints |
| PUT | /v1/user/webhooks/{id} | Atualizar endpoint |
| DELETE | /v1/user/webhooks/{id} | Remover endpoint |
| POST | /v1/user/webhooks/{id}/test | Enviar teste |
| POST | /v1/user/webhooks/{id}/rotate-secret | Trocar o segredo |
| GET | /v1/user/webhooks/{id}/deliveries | Histórico de entregas |
MED e contestações
| GET | /v1/user/disputes | Listar contestações |
| GET | /v1/user/disputes/{id} | Consultar contestação |
| POST | /v1/user/disputes/{id}/upload | Enviar anexo |
| POST | /v1/user/disputes/{id}/evidence | Enviar defesa |
| POST | /v1/user/disputes/{id}/accept | Reconhecer contestação |
Conta, cupons, domínio e rastreamento
| GET | /v1/fees | Taxas da conta |
| GET | /v1/user/limits | Limites de saque e uso do dia |
| PATCH | /v1/user/products/{id} | Alterar produto |
| DELETE | /v1/user/products/{id} | Apagar produto |
| POST | /v1/user/coupons | Criar cupom (também GET, PATCH e DELETE) |
| POST | /v1/user/domains | Cadastrar domínio próprio |
| POST | /v1/user/domains/{id}/verify | Verificar DNS |
| POST | /v1/user/integrations | Ligar 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.
| Status | Significado | Evento |
|---|---|---|
| pending | Pix 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_payment | Cartão em análise ou aguardando autenticação. | charge.pending |
| processing | Resposta do banco incerta. Consulte de novo; não crie outra. | — |
| paid | Pago. Libere o pedido. | charge.paid (e, na maioria, charge.received) |
| failed | Recusado, cancelado ou expirado. | charge.failed (quando houver recusa) |
| disputed | Reembolso pedido por você, valor bloqueado. | charge.disputed |
| chargeback | Contestação do banco ou MED. | charge.chargeback |
| refunded | Valor 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.
| HTTP | Significado | O que fazer |
|---|---|---|
400 | Requisição malformada (JSON inválido, upload sem arquivo). | Corrija o corpo. |
401 | Chave ausente, inválida, revogada ou vencida. | Veja Autenticação. |
403 | Conta 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. |
404 | Recurso não existe nesta conta. | Confira o ID. |
409 | external_id já usado; operação em andamento; contestação já respondida. | Consulte o recurso existente. Não repita. |
422 | Validação: campo faltando, valor fora do limite, documento inválido, cartão recusado. | Corrija os dados conforme a mensagem. |
429 | Muitas requisições ou cobrança duplicada. Pode vir em HTML. | Espere e tente com pausa crescente. |
500 | Erro interno. | Consulte pelo external_id antes de repetir. |
502 / 503 | Instabilidade 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.jsonpassa 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 porexternal_idesourceno 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.bre no domínio próprio, sem configurar nada. - Para fixar o idioma, acrescente
?lang=pt,enouesao 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/chargescommethod: "card"agora responde202comstatus: "requires_action"epayment_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,deviceebrowsercontinua sendo aceito: os dados são ignorados (card_data_ignored: true) e a resposta traz a página de pagamento. Ostatus_urlcontinua público e o webhookcharge.paidsai com o seuexternal_id. - Taxa e prazo do cartão pela API são os da venda por link (
card_link_normaloucard_link_nitroemGET /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 respondia422. - Cupom com código repetido responde
409“Já existe um cupom com este código.”; antes,500. - Cobrança pela API com
checkout_sluge cupom registradiscount_centse 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_issuereboleto_nominalvêm vazios;details_sourcevemprovider,storedoudemo). - Segurança: chave de API não acessa rotas administrativas; webhooks com
X-Chase-TimestampeX-Chase-Signature-V2contra 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
| Antes | Como funciona de verdade |
|---|---|
Checkout com settings.advanced.payCard | Use settings.card e settings.pix. O campo antigo não liga o meio de pagamento. |
Saque com totp_code | Saque usa pin (quando a conta tem PIN) e aceita key_type. |
| Webhook sem novas tentativas | Até 5 envios: depois de 1, 5, 15 e 60 minutos, com o mesmo evt_…. |
charge.created, charge.expired, balance.updated | Aceitos no cadastro, mas hoje não são enviados. |
MED gera charge.disputed | MED do banco gera charge.chargeback; charge.disputed é quando você pede reembolso. |
| Chave sem validade | A chave vale 365 dias, e trocar a senha revoga todas. |