> ## Documentation Index > Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt > Use this file to discover all available pages before exploring further. # Payment Intents > Entenda Payment Intents de ponta a ponta: objeto, estados, PIX em next_action, cartão, cancelamento, charges, transactions, endpoints e eventos. 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**. Passo a passo com PIX, cartão salvo, webhook e estado local. Campos, tipos, enums, timestamps e payload completo. **Payment Intent ≠ Charge ≠ Cadastro de cartão** O **payment intent** é o processo da cobrança — vive por todo o ciclo. Cada tentativa concreta de mover dinheiro vira uma [`charge`](/payments/charges), 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](/api-reference/payment-intents/object). ## Para que serve Use payment intents quando você quer **controlar a cobrança diretamente pela API**, sem depender de uma [Checkout Session](/payments/create-checkout-page): * 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](/payments/create-checkout-page) 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](#ciclo-de-vida-e-status)). | | `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 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. `POST /v1/payment-intents/{id}/confirm` inicia a tentativa. Você também pode criar e confirmar de uma vez com `confirm: true` no create. 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. 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. ```bash Cartão salvo + confirm theme={"theme":"css-variables"} 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"] }' ``` ```json theme={"theme":"css-variables"} { "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. ```bash Criar PIX theme={"theme":"css-variables"} 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"] }' ``` ```json theme={"theme":"css-variables"} { "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. ```bash Cartão parcelado theme={"theme":"css-variables"} 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. 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. 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: ```bash theme={"theme":"css-variables"} 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](/payments/charges). ## 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`](/api-reference/webhooks/payment.intent.created) | Registrar o início da tentativa. Não libera o pedido. | | [`payment.intent.updated`](/api-reference/webhooks/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`](/api-reference/webhooks/payment.intent.succeeded) | Confirmar o pagamento e avançar a operação de negócio. | | [`payment.intent.canceled`](/api-reference/webhooks/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`](/api-reference/webhooks/charge.updated) | Acompanhar mudanças na tentativa concreta indicada por `latest_charge`. | ## Próximos passos Schema público completo e campos retornados. A tentativa concreta de cobrança gerada pelo intent. Contrato do `POST /v1/payment-intents`. Página hospedada que cria e confirma o intent por você. Assinatura, timeout, retries, duplicação e ordem.