Pagamentos

Um payment_intent representa uma cobrança ao longo de todo o ciclo de vida: criação, escolha do método, confirmação, ação do comprador e desfecho. Ele concentra o valor, o customer, os métodos permitidos, a Charge mais recente, o estado atual e a próxima ação. Cada tentativa concreta de pagar essa cobrança é registrada por uma charge. Use o Payment Intent como fonte do estado da cobrança. Cartão costuma resolver na confirmação; PIX e boleto podem ficar pending até o resultado assíncrono. Não use redirect ou callback do frontend como prova de pagamento.

Implementar Payment Intents

Fluxo completo de criação, PIX, webhook, cancelamento e nova tentativa.

Estados e lifecycle

Relação entre Payment Intent, Charge, Transaction e Invoice.

Criar Payment Intent

Parâmetros para cartão e PIX, confirmação imediata e respostas.

Eventos de Payment Intent

Os cinco eventos, quando usar cada um e os payloads completos.

Objeto payment_intent

Este é o formato completo retornado em create, get, update, confirm, capture, cancel, itens de list e em data.object dos webhooks payment.intent.*.

{
  "id": "pi_BPKFMPF4Wfo7pgKE",
  "object": "payment_intent",
  "amount": 7500,
  "amount_capturable": 0,
  "amount_details": {
    "amount": 7500,
    "installment_interest_amount": 0,
    "principal_amount": 7500,
    "surcharge_amount": 0
  },
  "amount_received": 0,
  "canceled_at": null,
  "cancellation_reason": null,
  "capture_method": "automatic",
  "client_secret": "pi_BPKFMPF4Wfo7pgKE_secret_0cdeca0eddbff3e58db1358bebae30a022ba04732cb1bbf0",
  "confirmation_method": "automatic",
  "created_at": "2026-05-16T18:34:58Z",
  "currency": "brl",
  "customer": "cus_4tcvgA2KBNKLxV7k",
  "installment_interest_amount": 0,
  "installments": null,
  "invoice": "inv_AumEjho7t62hR9Pn",
  "last_payment_error": null,
  "latest_charge": "ch_BzjW6YiUPkbcxGK3",
  "livemode": true,
  "metadata": {},
  "next_action": {
    "pix_display_qr_code": {
      "expires_at": "2026-05-16T19:35:00Z",
      "qr_code": "00020101021226860014br.gov.bcb.pix...",
      "qr_code_url": "https://pay.chargefy.io/qr/pi_BPKFMPF4Wfo7pgKE.png"
    },
    "type": "pix_display_qr_code"
  },
  "payment_method": null,
  "payment_method_options": {},
  "payment_method_types": [
    "pix"
  ],
  "principal_amount": 7500,
  "status": "pending",
  "surcharge_amount": 0,
  "updated_at": "2026-05-16T18:35:00Z"
}

string

Identificador do payment intent. Usa o prefixo pi_*.

string

Sempre "payment_intent".

integer

Valor total do intent em centavos. Quando há juros de parcelamento, pode ser maior que o valor principal original.

integer

Valor autorizado e ainda não capturado. Fica preenchido em captura manual.

object

Quebra do valor usado na cobrança.

Show Campos comuns de amount_details

integer

Total cobrado em centavos. Sempre principal_amount + surcharge_amount + installment_interest_amount.

integer

Juros de parcelamento em centavos.

integer

Valor do produto ou serviço, antes de repasse de taxa e juros de parcelamento.

integer

Repasse de taxa pago pelo comprador quando has_surcharge é true; 0 caso contrário.

integer

Valor já recebido. Em geral fica 0 antes do pagamento e igual a amount quando o intent chega a succeeded.

string | null

Data de cancelamento em ISO 8601.

string | null

Motivo do cancelamento. Vem null enquanto o intent não foi cancelado.

Os motivos se dividem em dois grupos. Os informados por você são os que você envia em POST /v1/payment-intents/:id/cancel — disponível para os intents que você criou direto pela API. Se o intent nasceu de um checkout, quem encerra é a sessão, e o motivo vem do segundo grupo:

duplicate — cobrança duplicada de outro intent.
fraudulent — suspeita de fraude.
requested_by_customer — o cliente pediu o cancelamento.
abandoned — o fluxo de pagamento foi abandonado sem uma causa mais específica.

Os gerados pela Chargefy são somente de leitura. Você recebe esses valores, nunca os envia:

automatic — a Chargefy encerrou a tentativa por uma regra interna, sem uma causa mais específica.
expired — o prazo da compra acabou. É o motivo de um checkout que expirou com o intent ainda aberto.
failed_invoice — a cobrança da fatura não foi concluída.
void_invoice — a fatura foi cancelada.

Um código PIX ou boleto que vence sem pagamento não cancela o intent: ele encerra apenas aquela tentativa e o intent volta a requires_payment_method, pronto para um novo código no mesmo objeto. Veja Expiração automática de PIX e boleto.

string

automatic para capturar na confirmação, ou manual para autorizar agora e capturar depois.

string

Credencial de runtime do intent. Use apenas em contexto controlado pelo seu frontend quando o fluxo exigir confirmação client-side.

string

Como o intent é confirmado. Hoje retorna automatic ou manual.

string

Data de criação em ISO 8601.

string

Moeda em ISO 4217 minúsculo, como brl.

string | null

Customer associado ao pagamento, quando houver.

integer

Juros de parcelamento cobrados do comprador, em centavos. Retorna 0 quando não há juros repassados ao comprador.

integer | null

Quantidade de parcelas escolhida. Vem null quando parcelamento não se aplica.

string | null

Invoice associada, quando o intent nasceu de uma invoice.

object | null

Motivo da recusa da última tentativa, quando houver. Vem null enquanto não houve falha. Veja Códigos de falhas para a lista completa de códigos e categorias.

Show Campos de last_payment_error

string | null

Orientação da Chargefy para a ocorrência: confirm_card_data, do_not_try_again ou try_again_later.

string | null

Categoria coarse da recusa: issuer_declined, invalid, blocked ou processing_error.

string | null

Código estável e legível do motivo (insufficient_funds, expired_card, …).

string | null

Mensagem em inglês para logs e desenvolvedores.

string | null

Advice bruto da bandeira, quando a rede enviou um. Diagnóstico.

string | null

Código bruto de recusa da rede, quando ela respondeu. Diagnóstico; não é contrato estável.

string | object | null

Tentativa de cobrança mais recente. Por padrão vem como ID ch_*; pode vir expandida quando você usa expand[]=latest_charge.

boolean

true em produção; false em ambiente de teste.

object

Pares string → string para correlacionar o intent com o seu sistema. Aceita até 50 chaves; cada chave tem até 40 caracteres e usa letras, números, _, - ou .; cada valor tem até 500 caracteres. Quando vazio, retorna {}.

object | null

Próxima ação para o comprador. Vem preenchido em fluxos assíncronos como PIX e boleto. Depois que a ação deixa de ser válida, o campo pode voltar a null. Em particular, a expiração automática de PIX limpa next_action.

Show PIX

string

pix_display_qr_code.

string | null

Código EMV do PIX.

string | null

URL de imagem do QR code, quando disponível.

string | null

Prazo de validade daquele código PIX. Passado o prazo, o código não deve mais ser apresentado como pagável. Quando o intent estiver elegível, use /regenerate_pix para emitir um código novo no mesmo intent.

Show Boleto

string

boleto_display_details.

string | null

URL do boleto hospedado.

string | null

Linha digitável.

string | null

URL do PDF.

string | null

Código de barras.

string | null

Vencimento do boleto.

string | object | null

Método de pagamento salvo usado no intent. Por padrão vem como ID pm_*; pode vir expandido quando você usa expand[]=payment_method.

object

Opções por método de pagamento, como parcelamento de cartão.

Show Cartão

integer

Total cobrado no cartão: principal, repasse de taxa e juros de parcelamento.

integer

Quantidade de parcelas usada. Quando omitida na criação/update, fica 1.

boolean

true quando o comprador paga o acréscimo; false quando o lojista absorve.

integer

Acréscimo de parcelamento em centavos. Com repasse de taxa, incide sobre o valor já acrescido do repasse.

integer

Valor do produto ou serviço antes do repasse de taxa e dos juros de parcelamento.

integer

Repasse de taxa pago pelo comprador quando has_surcharge é true; 0 caso contrário.

array

Métodos permitidos para a cobrança. Hoje pode incluir credit_card, pix e boleto, conforme o fluxo.

integer

Valor do produto ou serviço, em centavos, sem o surcharge_amount nem os juros de parcelamento. Sempre vale amount = principal_amount + surcharge_amount + installment_interest_amount.

string

Estado atual da cobrança.

Show Status possíveis

string

Falta definir o método de pagamento.

string

Pronto para confirmar.

string

Cartão autorizado; falta capturar.

string

Aguardando ação do comprador ou confirmação assíncrona.

string

Pagamento em processamento.

string

Pagamento concluído.

string

Pagamento falhou.

string

Pagamento cancelado.

integer

Valor da taxa repassada ao comprador, em centavos. Retorna 0 quando não há repasse. O detalhamento equivalente aparece em amount_details.surcharge_amount.

string | null

Data da última atualização em ISO 8601.

Estados e transições

O status diz qual ação ainda falta ou qual foi o desfecho. Nem todo intent passa por todos os estados.

Estado atual	Significado	Próximo passo comum
`requires_payment_method`	Não há tentativa em andamento: o intent acabou de nascer sem método, uma tentativa foi recusada ou um código venceu.	Confirme de novo — mesmo cartão corrigido, outro cartão ou novo código no mesmo intent. `last_payment_error` explica a recusa quando houve uma.
`requires_confirmation`	O intent está pronto para iniciar a cobrança.	Chame `/confirm`.
`pending`	Aguarda o comprador ou uma confirmação assíncrona.	Exiba `next_action` e espere o webhook.
`processing`	O pagamento foi enviado e está sendo processado.	Espere o webhook; não crie outra cobrança automaticamente.
`requires_capture`	O cartão foi autorizado com captura manual.	Chame `/capture` ou cancele a autorização.
`succeeded`	O pagamento foi concluído.	Processe `payment.intent.succeeded` e avance a operação no seu sistema.
`failed`	Estado histórico: cobrança de fatura que terminou em falha, ou intents anteriores ao modelo atual. Recusa em intent avulso não produz mais `failed`.	Leia `last_payment_error`. Para faturas, acompanhe `invoice.payment.failed`.
`canceled`	A cobrança foi encerrada por decisão: cancelamento direto, checkout expirado ou fatura anulada.	Leia `cancellation_reason`; crie outro intent somente se ainda precisar cobrar.

Um timeout ou erro 5xx durante a confirmação não transforma automaticamente a tentativa em failed. Ela pode continuar processing enquanto a Chargefy confirma o resultado externo. Consulte o mesmo Payment Intent e aguarde o webhook; não inicie outra cobrança enquanto esse estado persistir.

Acontecimento	Transição
Método definido	`requires_payment_method` → `requires_confirmation`
Cancelamento antes de definir o método	`requires_payment_method` → `canceled`
Confirmação assíncrona	`requires_confirmation` → `pending`
Envio para processamento	`requires_confirmation` → `processing`
Autorização com captura manual	`requires_confirmation` → `requires_capture`
Pagamento concluído imediatamente	`requires_confirmation` → `succeeded`
Recusa na confirmação	`requires_confirmation`/`processing` → `requires_payment_method`
Cancelamento antes de confirmar	`requires_confirmation` → `canceled`
Pagamento confirmado	`pending` → `succeeded`
Recusa assíncrona	`pending`/`processing` → `requires_payment_method`
Código PIX/boleto vence sem pagamento	`pending` → `requires_payment_method`
Cancelamento	`pending` → `canceled`
Pagamento confirmado após processamento	`processing` → `succeeded`
Falha de cobrança de fatura	`processing` → `failed`
Confirmação tardia da mesma tentativa	`failed` → `succeeded`
Captura concluída	`requires_capture` → `succeeded`
Autorização cancelada	`requires_capture` → `canceled`

Os únicos estados terminais são succeeded e canceled. Uma recusa devolve o intent a requires_payment_method com o motivo em last_payment_error — o mesmo objeto aceita nova confirmação, com o mesmo cartão corrigido ou outro método. Cada tentativa executada vira uma charge; um intent aceita até 10 tentativas, e além disso a confirmação responde 409.

Datas e expiração

Não existe um único expires_at top-level no Payment Intent. Cada timestamp responde a uma pergunta diferente:

Campo	O que representa
`created_at`	Quando o intent foi criado.
`updated_at`	Quando algum campo público mudou pela última vez.
`canceled_at`	Quando o intent entrou em `canceled`.
`next_action.pix_display_qr_code.expires_at`	Até quando aquele código PIX é válido.
`next_action.boleto_display_details.expires_at`	Vencimento daquele boleto.

O prazo comercial para concluir a operação pertence ao seu sistema. Ele pode ser menor que a validade do meio de pagamento; nesse caso, encerre a tentativa quando o prazo local terminar — com POST /v1/payment-intents/:id/cancel se você criou o intent direto, ou com POST /v1/checkout-sessions/:id/expire se a tentativa nasceu de um checkout.

Intents criados por um checkout

Quando o intent nasceu de uma sessão de checkout, a sessão é a dona do ciclo de vida dele: enquanto a sessão está aberta o intent fica aberto — é isso que permite ao comprador voltar ao link, trocar de meio de pagamento ou pedir um novo código PIX. Quando a sessão expira, o intent é cancelado junto, com cancellation_reason: "expired". Por isso o cancelamento direto desse intent é recusado com 409, exceto em requires_capture. Para encerrar a tentativa antes do prazo, expire a sessão.

Expiração automática de PIX e boleto

O código tem prazo; o intent não. Quando um PIX ou boleto em pending vence sem pagamento, apenas aquela tentativa termina — o Payment Intent continua vivo e pronto para um novo código:

Campo ou evento	Valor
`status`	`requires_payment_method`
`next_action`	`null`; o código expirado não permanece como próxima ação.
`latest_charge`	Continua apontando para a tentativa que expirou; a charge registra o desfecho dela.
Evento de Payment Intent	Somente `payment.intent.updated`; a expiração não emite `payment.intent.canceled`.

Para emitir um novo código no mesmo intent, use /regenerate_pix ou /regenerate_boleto — cada código novo é uma nova charge sob o mesmo pi_*. Antes disso, a confirmação que levou o intent de requires_confirmation para pending emitiu payment.intent.updated com o código completo. Persista next_action.pix_display_qr_code.expires_at nesse momento: o payload da expiração não repete o prazo.

A ordem acima descreve o lifecycle. As entregas HTTP podem chegar duplicadas ou fora de ordem; deduplique por event.id e use o objeto completo de data.object para reconciliar o estado.

Objeto completo nos webhooks

Nos eventos payment.intent.*, data.object usa este mesmo contrato completo. Ele não é um patch. Quando data.previous_attributes estiver presente, apenas esse campo é parcial: ele contém os valores anteriores dos campos alterados.

Relação com Charge e Transaction

O Payment Intent representa o ciclo da cobrança.
Cada confirmação pode materializar uma charge, que registra a tentativa concreta de cobrar o método.
latest_charge aponta para a tentativa mais recente.
Regenerar PIX ou boleto mantém o mesmo Payment Intent e cria uma nova Charge.
Uma Charge antiga que falha ou expira não rebaixa um Payment Intent que já chegou a succeeded por outra Charge.
Depois do processamento financeiro, transaction registra os movimentos do extrato, taxas, líquido e liquidação.
invoice vem preenchida quando a cobrança nasceu de uma invoice.

Operações

Testar em sandbox

Para PIX e boleto, associe um customer com um dos e-mails de teste do sandbox. O resultado passa pelo fluxo normal de confirmação e, nos cenários delayed, muda automaticamente após cerca de 3 minutos.

Webhooks

Para liberar produto, crédito, assinatura ou acesso, prefira webhooks em vez de depender só da resposta síncrona. Eventos principais:

Entrega e assinatura

Assinatura oficial, timeout, retries, duplicação e ordem.

Cadastrar endpoint

Inscreva os tipos exatos; wildcards não são aceitos.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Implementar Payment Intents

Estados e lifecycle

Criar Payment Intent

Eventos de Payment Intent

Objeto payment_intent

Estados e transições

Datas e expiração

Intents criados por um checkout

Expiração automática de PIX e boleto

Objeto completo nos webhooks

Relação com Charge e Transaction

Operações

Testar em sandbox

Webhooks

Entrega e assinatura

Cadastrar endpoint

Implementar Payment Intents

Estados e lifecycle

Criar Payment Intent

Eventos de Payment Intent

​Objeto payment_intent

​Estados e transições

​Datas e expiração

​Intents criados por um checkout

​Expiração automática de PIX e boleto

​Objeto completo nos webhooks

​Relação com Charge e Transaction

​Operações

​Testar em sandbox

​Webhooks

Entrega e assinatura

Cadastrar endpoint

Objeto payment_intent

Estados e transições

Datas e expiração

Intents criados por um checkout

Expiração automática de PIX e boleto

Objeto completo nos webhooks

Relação com Charge e Transaction

Operações

Testar em sandbox

Webhooks