Payment Intents

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.

Implementar Payment Intents

Passo a passo com PIX, cartão salvo, webhook e estado local.

Contrato do objeto

Campos, tipos, enums, timestamps e payload completo.

Payment Intent ≠ Charge ≠ Cadastro de cartãoO 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 cadastro de cartão (setup_intent) apenas salva um cartão para uso futuro, sem cobrar ou reservar limite.

Como os recursos se relacionam

Origem	Campo ou ação	Destino
`payment_intent`	`latest_charge`	`charge` mais recente
`charge`	Processamento financeiro	Uma ou mais `transactions`
`invoice`	Inicia a cobrança quando aplicável	`payment_intent`
`payment_intent`	`customer`	Cliente cobrado
`payment_intent`	`next_action`	Instrução para o comprador pagar PIX ou boleto

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`
transaction	Cada movimento do extrato, incluindo parcelas	gerada pelo processamento financeiro; registra bruto, taxas, líquido e liquidação
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.

Práticas de integração

Crie um Payment Intent quando o valor da compra estiver definido.
Reutilize o mesmo intent quando o comprador retomar a mesma tentativa.
Envie Idempotency-Key em escritas que podem ser repetidas após timeout ou falha de rede.
Mantenha a API key no servidor e use metadata apenas para referências como o ID do pedido, nunca para regra de negócio ou dado sensível.
Confirme o resultado por webhook; retorno do navegador não prova pagamento.

Anatomia do payment intent

Campo	Tipo	Descrição
`amount`	`integer`	Total em centavos. Pode superar o valor principal 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: `amount`, `installment_interest_amount`, `principal_amount` e `surcharge_amount`.
`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`.
`cancellation_reason`	`string \| null`	Informado por você (`duplicate`, `fraudulent`, `requested_by_customer`, `abandoned`) ou gerado pela Chargefy (`automatic`, `expired`, `failed_invoice`, `void_invoice`). `abandoned` só aparece se você enviar; a Chargefy nunca o escreve.
`next_action`	`object \| null`	O que falta o comprador fazer (PIX/boleto).
`client_secret`	`string`	Segredo opaco associado ao intent. As operações públicas documentadas continuam autenticadas por API key.
`last_payment_error`	`object \| null`	Último erro de pagamento, quando houver.
`metadata`	`object`	Pares chave→valor livres, controlados por você.
`created_at` / `updated_at`	`string` / `string \| null`	Criação e última mudança do intent em ISO 8601.
`canceled_at`	`string \| null`	Momento do cancelamento, quando aplicável.

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.

Acontecimento	Transição
Criação sem método definido	Início → `requires_payment_method`
Criação com método definido	Início → `requires_confirmation`
Método definido	`requires_payment_method` → `requires_confirmation`
Cartão confirmado	`requires_confirmation` → `processing`
PIX ou boleto confirmado	`requires_confirmation` → `pending`
Comprador pagou	`pending` → `succeeded`
Pagamento aprovado com captura automática	`processing` → `succeeded`
Cartão autorizado com captura manual	`processing` → `requires_capture`
Captura concluída	`requires_capture` → `succeeded`
Recusa da tentativa	`processing` ou `requires_confirmation` → `requires_payment_method`
Falha de cobrança de fatura	`processing` → `failed`
Cancelamento antes da confirmação	`requires_payment_method` ou `requires_confirmation` → `canceled`
Código PIX/boleto vence sem pagamento	`pending` → `requires_payment_method`
Cancelamento	`pending` → `canceled`
Cancelamento da autorização	`requires_capture` → `canceled`

Status	Significado
`requires_payment_method`	Sem tentativa em andamento: intent novo, recusa ou código vencido. Aceita nova confirmação.
`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`	Estado histórico: falha de cobrança de fatura ou intents antigos.
`canceled`	Cobrança encerrada por decisão.

Numa cobrança de cartão confirmada, latest_charge aponta a tentativa e last_payment_error registra o motivo quando ela é recusada. A recusa não encerra o intent: ele volta a requires_payment_method e o mesmo objeto aceita nova confirmação — com o cartão corrigido ou outro cartão. Cada tentativa executada vira uma charge, até o limite de 10 por intent.

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. O create direto aceita cartão e Pix; intents de boleto são materializados por checkout hospedado ou invoice.

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 direto retorna next_action com o QR code. Um intent de boleto criado por checkout hospedado ou invoice pode trazer a linha digitável. Mostre a ação 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_rvaJTZBW2D3zPbhi",
    "payment_method": "pm_iDsKhXq2EPXbefBJ",
    "payment_method_types": ["credit_card"]
  }'

{
  "id": "pi_FwR94SrqRiPsQ9m8",
  "object": "payment_intent",
  "amount": 9900,
  "amount_capturable": 0,
  "amount_details": {
    "amount": 9900,
    "installment_interest_amount": 0,
    "principal_amount": 9900,
    "surcharge_amount": 0
  },
  "amount_received": 9900,
  "canceled_at": null,
  "cancellation_reason": null,
  "capture_method": "automatic",
  "client_secret": "pi_FwR94SrqRiPsQ9m8_secret_ced78523574e510f12882733956d7bd4a0b1567cd2af3864",
  "confirmation_method": "automatic",
  "created_at": "2026-05-16T14:09:27Z",
  "currency": "brl",
  "customer": "cus_rvaJTZBW2D3zPbhi",
  "installment_interest_amount": 0,
  "installments": 1,
  "invoice": null,
  "last_payment_error": null,
  "latest_charge": "ch_FC8rQHJ2hP5guUY6",
  "livemode": false,
  "metadata": {},
  "next_action": null,
  "payment_method": "pm_iDsKhXq2EPXbefBJ",
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "amount": 9900,
        "count": 1,
        "has_interest": false,
        "installment_interest_amount": 0,
        "principal_amount": 9900,
        "surcharge_amount": 0
      }
    }
  },
  "payment_method_types": [
    "credit_card"
  ],
  "principal_amount": 9900,
  "status": "succeeded",
  "surcharge_amount": 0,
  "updated_at": "2026-05-16T14:09:27Z"
}

(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_rvaJTZBW2D3zPbhi",
    "payment_method_types": ["pix"]
  }'

{
  "id": "pi_FwR94SrqRiPsQ9m8",
  "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_FwR94SrqRiPsQ9m8_secret_ced78523574e510f12882733956d7bd4a0b1567cd2af3864",
  "confirmation_method": "automatic",
  "created_at": "2026-05-16T14:09:27Z",
  "currency": "brl",
  "customer": "cus_rvaJTZBW2D3zPbhi",
  "installment_interest_amount": 0,
  "installments": null,
  "invoice": null,
  "last_payment_error": null,
  "latest_charge": null,
  "livemode": false,
  "metadata": {},
  "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"
  },
  "payment_method": null,
  "payment_method_options": {},
  "payment_method_types": [
    "pix"
  ],
  "principal_amount": 7500,
  "status": "pending",
  "surcharge_amount": 0,
  "updated_at": "2026-05-16T14:09:27Z"
}

(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_rvaJTZBW2D3zPbhi",
    "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_FwR94SrqRiPsQ9m8/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:

Evento	Quando usar
`payment.intent.created`	Registrar o início da tentativa. Não libera o pedido.
`payment.intent.updated`	Sincronizar campos e transições intermediárias: confirmação do PIX para `pending`, recusa ou código vencido devolvendo o intent a `requires_payment_method`.
`payment.intent.succeeded`	Confirmar o pagamento e avançar a operação de negócio.
`payment.intent.canceled`	Encerrar a tentativa cancelada de forma deliberada. A expiração de um código não emite este evento: o intent volta a `requires_payment_method` via `payment.intent.updated`.
`charge.updated`	Acompanhar mudanças na tentativa concreta indicada por `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ê.

Entrega de webhooks

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

Pagamentos online

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

Implementar Payment Intents

Contrato do objeto

Como os recursos se relacionam

Para que serve

Práticas de integração

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

Entrega de webhooks

Implementar Payment Intents

Contrato do objeto

​Como os recursos se relacionam

​Para que serve

​Práticas de integração

​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

Entrega de webhooks

Como os recursos se relacionam

Para que serve

Práticas de integração

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