Payment Intents - Chargefy

Um payment intent representa uma cobrança ao longo de todo o seu ciclo de vida — da intenção de cobrar até o desfecho final. Ele concentra num só objeto o valor, a moeda, o customer, os métodos permitidos, a tentativa mais recente, o status atual e a próxima ação que cabe ao comprador. É por ele que o seu sistema sabe se o dinheiro entrou, está em trânsito ou foi recusado.

Payment Intent ≠ Charge ≠ Setup IntentO payment intent é o processo da cobrança — vive por todo o ciclo. Cada tentativa concreta de mover dinheiro vira uma charge, e o intent aponta a mais recente em latest_charge. Já um setup intent apenas salva um meio de pagamento para uso futuro, sem cobrar.

Modelo conceitual

Objeto	Responsabilidade	Campos centrais
payment_intent	O processo da cobrança e seu estado financeiro	`amount`, `currency`, `customer`, `payment_method_types`, `status`, `next_action`, `latest_charge`
charge	Cada tentativa concreta de mover dinheiro	gerada na confirmação; o intent referencia a última em `latest_charge`
invoice	Quando a cobrança vem de uma assinatura/fatura	o intent referencia a fatura de origem em `invoice`

O schema público completo está em Objeto payment_intent.

Para que serve

Use payment intents quando você quer controlar a cobrança diretamente pela API, sem depender de uma Checkout Session:

você tem Checkout white-label e quer confirmar a cobrança via API;
precisa cobrar um meio de pagamento salvo (payment_method);
quer separar a criação da cobrança da confirmação;
precisa autorizar agora e capturar depois (cartão);
quer acompanhar tentativas, falhas e sucesso de forma previsível, reagindo por webhook.

Quem prefere uma página de pagamento pronta e hospedada não precisa orquestrar o intent manualmente — uma Checkout Session cria e confirma o payment intent por baixo dos panos.

Anatomia do payment intent

Campo	Tipo	Descrição
`amount`	`integer`	Total em centavos. Pode superar o subtotal quando há juros de parcelamento.
`amount_capturable`	`integer`	Autorizado e ainda não capturado. Preenchido em captura manual.
`amount_received`	`integer`	Já recebido. `0` antes do pagamento; igual a `amount` quando chega a `succeeded`.
`amount_details`	`object`	Quebra do valor: `subtotal`, `installment_interest`, `total`.
`currency`	`string`	ISO 4217 minúsculo, como `brl`.
`customer`	`string \| null`	Customer associado, quando houver.
`invoice`	`string \| null`	Fatura de origem, quando o intent nasceu de uma cobrança recorrente.
`latest_charge`	`string \| object \| null`	Tentativa mais recente. ID `ch_*` por padrão; expandível.
`payment_method`	`string \| object \| null`	Meio de pagamento salvo usado. ID `pm_*` por padrão; expandível.
`payment_method_types`	`array`	Métodos permitidos: `credit_card`, `pix`, `boleto`.
`payment_method_options`	`object`	Opções por método, como parcelamento de cartão.
`status`	`string`	Estado atual da cobrança (veja abaixo).
`capture_method`	`string`	`automatic` ou `manual`.
`confirmation_method`	`string`	`automatic` ou `manual`.
`setup_future_usage`	`string \| null`	`off_session`, `on_session` ou `null`.
`cancellation_reason`	`string \| null`	`duplicate`, `fraudulent`, `requested_by_customer`, `abandoned` ou `null`.
`next_action`	`object \| null`	O que falta o comprador fazer (PIX/boleto).
`client_secret`	`string`	Credencial de runtime para confirmação client-side.
`last_payment_error`	`object \| null`	Último erro de pagamento, quando houver.
`metadata`	`object`	Pares chave→valor livres, controlados por você.

Ciclo de vida e status

O status reflete o que falta para concluir o pagamento. Cartão costuma resolver na hora; PIX e boleto ficam pendentes até a confirmação assíncrona chegar.

Status	Significado
`requires_payment_method`	Falta definir o método de pagamento, ou o anterior falhou.
`requires_confirmation`	Método definido; pronto para confirmar.
`pending`	Aguardando ação do comprador ou confirmação assíncrona (PIX/boleto).
`processing`	Pagamento em processamento.
`requires_capture`	Cartão autorizado; falta capturar (somente captura manual).
`succeeded`	Pagamento concluído.
`failed`	Pagamento falhou.
`canceled`	Cobrança cancelada.

Numa cobrança de cartão confirmada, latest_charge aponta a tentativa e last_payment_error registra o motivo quando ela é recusada — momento em que o intent volta para requires_payment_method, pronto para uma nova tentativa.

Como funciona

Crie o payment intent

Informe amount, currency, customer e payment_method_types. Sem método definido, ele nasce em requires_payment_method; com método salvo ou PIX, já em requires_confirmation.

Confirme a cobrança

POST /v1/payment-intents/{id}/confirm inicia a tentativa. Você também pode criar e confirmar de uma vez com confirm: true no create.

Apresente a próxima ação (se houver)

PIX e boleto retornam next_action com o QR code ou a linha digitável. Mostre ao comprador e aguarde a confirmação assíncrona.

Reaja ao resultado

O intent termina em succeeded, volta para requires_payment_method (recusa), fica em requires_capture (captura manual) ou em canceled. Confie nos webhooks para liberar o produto.

Criar e confirmar

O payment_method_types aceita credit_card e pix no create direto pela API; boleto é resolvido nos fluxos hospedados de checkout e fatura. Cada caminho de criação tem um comportamento distinto.

(a) Cartão salvo, cobrando na hora

Passe um payment_method salvo do customer e confirm: true. O cartão resolve de forma síncrona.

curl https://api.chargefy.io/v1/payment-intents \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9900,
    "confirm": true,
    "currency": "brl",
    "customer": "cus_123",
    "payment_method": "pm_456",
    "payment_method_types": ["credit_card"]
  }'

{
  "id": "pi_123",
  "object": "payment_intent",
  "amount": 9900,
  "amount_received": 9900,
  "currency": "brl",
  "customer": "cus_123",
  "latest_charge": "ch_789",
  "payment_method": "pm_456",
  "status": "succeeded"
}

(b) PIX, com QR code para o comprador

PIX nasce em requires_confirmation. Ao confirmar, o intent vai para pending e devolve o next_action com o código a exibir.

curl https://api.chargefy.io/v1/payment-intents \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 7500,
    "currency": "brl",
    "customer": "cus_123",
    "payment_method_types": ["pix"]
  }'

{
  "id": "pi_123",
  "object": "payment_intent",
  "amount": 7500,
  "currency": "brl",
  "next_action": {
    "pix_display_qr_code": {
      "expires_at": "2026-05-16T19:35:00Z",
      "qr_code": "00020101021226860014br.gov.bcb.pix...",
      "qr_code_url": null
    },
    "type": "pix_display_qr_code"
  },
  "status": "pending"
}

(c) Cartão a definir, parcelado

Sem payment_method, o intent nasce em requires_payment_method. Defina o número de parcelas em payment_method_options.credit_card.installments — o amount final reflete os juros aplicados.

curl https://api.chargefy.io/v1/payment-intents \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12000,
    "currency": "brl",
    "customer": "cus_123",
    "payment_method_options": {
      "credit_card": { "installments": { "count": 3, "has_interest": true } }
    },
    "payment_method_types": ["credit_card"]
  }'

installments.count vai de 1 a 12 e respeita um teto calculado pelo valor da cobrança. Quando omitido, usa 1. has_interest define quem absorve o juro: true faz o comprador pagar o acréscimo e false mantém a venda sem juros para o comprador. Quando omitido, vale a configuração da organização. Os juros de parcelamento aparecem em amount_details.

Próxima ação do comprador

Métodos assíncronos preenchem next_action. Use o type para decidir o que renderizar.

PIX — pix_display_qr_code

Traz qr_code (código EMV copia-e-cola), qr_code_url (imagem do QR, quando disponível) e expires_at. Exiba o QR e o botão de copiar; o pagamento confirma de forma assíncrona.

Boleto — boleto_display_details

Traz hosted_voucher_url, pdf, number (linha digitável), barcode e expires_at. O boleto pode ser regerado enquanto está pending com POST /v1/payment-intents/{id}/regenerate_boleto.

Não trate next_action ausente como pagamento confirmado. Quem confirma o sucesso de PIX e boleto é o webhook payment.intent.succeeded, não a resposta síncrona da confirmação.

Captura manual

Com capture_method: "manual" (hoje, somente credit_card), a confirmação autoriza o valor e o intent fica em requires_capture, com amount_capturable preenchido. Você captura depois:

curl https://api.chargefy.io/v1/payment-intents/pi_123/capture \
  -H "Authorization: Bearer {{API_KEY}}"

Cancelar um intent em requires_capture libera a autorização do cartão. A captura e o cancelamento retornam o payment intent completo atualizado.

Atualizar e cancelar

Operação	Quando	Efeito
`POST /v1/payment-intents/{id}`	Apenas em `requires_payment_method` ou `requires_confirmation`	Merge de campos como `amount`, `metadata` e método.
`POST /v1/payment-intents/{id}/cancel`	Qualquer status exceto `succeeded`/`canceled`	Status vira `canceled`; autorização de cartão é estornada quando aplicável.

Depois de confirmado e pago, o payment intent é imutável. O update só vale enquanto a cobrança ainda não saiu — para reverter dinheiro já recebido, o caminho é um reembolso sobre a charge.

Eventos

Para liberar produto, crédito, assinatura ou acesso, prefira reagir por webhook em vez de depender só da resposta síncrona:

payment.intent.created
payment.intent.updated
payment.intent.succeeded
payment.intent.failed
payment.intent.canceled
charge.updated — acompanha a tentativa em latest_charge

Próximos passos

Objeto payment_intent

Schema público completo e campos retornados.

Charges

A tentativa concreta de cobrança gerada pelo intent.

Criar payment intent (API)

Contrato do POST /v1/payment-intents.

Checkout Sessions

Página hospedada que cria e confirma o intent por você.

​Modelo conceitual

​Para que serve

​Anatomia do payment intent

​Ciclo de vida e status

​Como funciona

​Criar e confirmar

​(a) Cartão salvo, cobrando na hora

​(b) PIX, com QR code para o comprador

​(c) Cartão a definir, parcelado

​Próxima ação do comprador

​Captura manual

​Atualizar e cancelar

​Eventos

​Próximos passos

Objeto payment_intent

Charges

Criar payment intent (API)

Checkout Sessions

Modelo conceitual

Para que serve

Anatomia do payment intent

Ciclo de vida e status

Como funciona

Criar e confirmar

(a) Cartão salvo, cobrando na hora

(b) PIX, com QR code para o comprador

(c) Cartão a definir, parcelado

Próxima ação do comprador

Captura manual

Atualizar e cancelar

Eventos

Próximos passos