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 em requires_action até o resultado assíncrono.
Não use redirect ou callback do frontend como prova de pagamento.
Cada pagamento recebe um number de seis caracteres, como J9N6R8, único
na organização e no ambiente de produção ou teste. Ele é gerado na criação,
mesmo sem cliente, e não muda. As cobranças usam essa referência seguida
da tentativa: J9N6R8-001, J9N6R8-002. Os endpoints continuam usando o id.
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 emcreate, get, update, confirm,
capture, cancel, itens de list e em data.object dos webhooks
payment.intent.*.
Referência legível de seis caracteres, gerada automaticamente e imutável.
Usa letras maiúsculas e números, sem
0, O, 1 e I.Comissões de afiliados acordadas para este pagamento;
[] quando ausentes.
Cada item contém affiliation e affiliate_fee_rate, em pontos-base.
São termos do pagamento, não confirmação de recebimento: a cobrança registra
separadamente as partes que não puderam receber.Total que o comprador paga, na menor unidade da moeda (centavos em
brl). Inclui os juros do parcelamento
quando interest_payer é buyer; quando é organization, é igual a
principal_amount + surcharge_amount e o juro sai do líquido da organização.Valor já recebido. Em geral fica
0 antes do pagamento e igual a amount
quando o intent chega a succeeded.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.
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.Data do pedido de cancelamento do pagamento, em ISO 8601. Em boleto, o pedido
aguarda confirmação bancária; o estado só vira
canceled depois dela. Permanece
no histórico se o pagamento chegar durante a espera.Credencial de runtime do intent. Use apenas em contexto controlado pelo seu
frontend quando o fluxo exigir confirmação client-side.
Juros do parcelamento da venda, na menor unidade da moeda (centavos em
brl), seja quem for que os pague —
espelho de amount_details.installment_interest_amount. Entra no amount
quando interest_payer é buyer; quando é organization, o comprador não o
paga e ele é descontado do líquido da organização. Retorna 0 em 1x.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.Tentativa de cobrança mais recente. Por padrão vem como ID
ch_*; pode vir
expandida quando você usa expand[]=latest_charge. A cobrança expandida
traz o total estornado. Para listar os estornos, use
GET /v1/refunds?charge=<id>.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 {}.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.Método de pagamento salvo usado no intent. Por padrão vem como ID
pm_*; pode
vir expandido quando você usa expand[]=payment_method. Um pagamento de
cartão pode terminar pago com payment_method: null: é o cartão de uso
único ou não suportado para cobranças futuras (single_use_card), cobrado
diretamente sem ficar salvo — a cobrança correspondente traz o snapshot em
payment_method_details.Métodos permitidos para a cobrança. Hoje pode incluir
credit_card, pix e
boleto, conforme o fluxo.Valor do produto ou serviço, na menor unidade da moeda (centavos em
brl), sem o surcharge_amount nem os
juros de parcelamento. Vale amount = principal_amount + surcharge_amount + installment_interest_amount quando interest_payer é buyer, e amount = principal_amount + surcharge_amount quando é organization.Valor da taxa repassada ao comprador, na menor unidade da moeda (centavos em
brl). Retorna 0 quando não há
repasse. O detalhamento equivalente aparece em
amount_details.surcharge_amount.Estados e transições
Ostatus diz qual ação ainda falta ou qual foi o desfecho. Nem todo intent
passa por todos os estados.
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 únicoexpires_at top-level no Payment Intent. Cada timestamp
responde a uma pergunta diferente:
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, comcancellation_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 emrequires_action vence
sem pagamento, apenas aquela tentativa termina — o Payment Intent continua
vivo e pronto para um novo código.
O Pix termina assim que o prazo do QR Code acaba. O boleto deixa de ser pagável
no fim do dia de vencimento (boleto_display_details.expires_at), mas a
tentativa só termina quando o banco confirma que não houve pagamento — em geral
de 2 a 3 dias úteis depois, porque um pagamento feito no último dia ainda pode
ser compensado. Até lá o intent continua em requires_action. Se essa
confirmação não chegar em 10 dias, a Chargefy encerra a tentativa do mesmo
jeito. Quando a tentativa termina:
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
requires_action 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 eventospayment.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_chargeaponta 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
succeededpor outra Charge. - Depois do processamento financeiro,
transactionregistra os movimentos do extrato, taxas, líquido e liquidação. invoicevem preenchida quando a cobrança nasceu de uma invoice.
Operações
- Listar payment intents
- Criar payment intent
- Consultar payment intent
- Atualizar payment intent
- Confirmar payment intent
- Capturar payment intent
- Cancelar payment intent
- Regenerar Pix
- Regenerar boleto
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.

