> ## 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. # Overview > O objeto Payment Intent 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ó lugar o valor, a moeda, o `customer`, os métodos permitidos, a tentativa de cobrança mais recente, o estado atual e a próxima ação que cabe ao comprador, e é por ele que o seu sistema sabe se o dinheiro entrou, está em trânsito ou foi recusado. Ele nasce quando uma cobrança começa, seja criada diretamente pela API ou resolvida por um checkout hospedado, e atravessa um `status` que reflete o que falta para concluir o pagamento: cartão costuma resolver na hora, enquanto PIX e boleto ficam `pending` até a confirmação assíncrona chegar. À medida que avança, ele se liga à `charge` que materializa cada tentativa e, quando origina de uma cobrança recorrente, à `invoice` correspondente — sendo o estado financeiro que conecta esses objetos à pessoa que paga. ## 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.*`. ```json theme={} { "id": "pi_123", "object": "payment_intent", "amount": 7500, "amount_capturable": 0, "amount_details": { "installment_interest": 0, "subtotal": 7500, "total": 7500 }, "amount_received": 0, "canceled_at": null, "cancellation_reason": null, "capture_method": "automatic", "client_secret": "pi_123_secret_abc", "confirmation_method": "automatic", "created_at": "2026-05-16T18:34:58Z", "currency": "brl", "customer": "cus_123", "invoice": null, "last_payment_error": null, "latest_charge": "ch_123", "livemode": true, "metadata": { "order_id": "id_456" }, "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"], "setup_future_usage": null, "status": "pending", "updated_at": "2026-05-16T18:35:00Z" } ``` Identificador do payment intent. Usa o prefixo `pi_*`. Sempre `"payment_intent"`. Valor total do intent em centavos. Quando há juros de parcelamento, pode ser maior que o subtotal original. Valor autorizado e ainda não capturado. Fica preenchido em captura manual. Quebra do valor usado na cobrança. Valor antes de juros de parcelamento. Juros de parcelamento em centavos. Total cobrado em centavos. Valor já recebido. Em geral fica `0` antes do pagamento e igual a `amount` quando o intent chega a `succeeded`. Data de cancelamento em ISO 8601. Motivo do cancelamento: `duplicate`, `fraudulent`, `requested_by_customer`, `abandoned` ou `null`. `automatic` para capturar na confirmação, ou `manual` para autorizar agora e capturar depois. Credencial de runtime do intent. Use apenas em contexto controlado pelo seu frontend quando o fluxo exigir confirmação client-side. Como o intent é confirmado. Hoje retorna `automatic` ou `manual`. Data de criação em ISO 8601. Moeda em ISO 4217 minúsculo, como `brl`. Customer associado ao pagamento, quando houver. Invoice associada, quando o intent nasceu de uma invoice. Motivo da recusa da última tentativa, quando houver. Vem `null` enquanto não houve falha. Veja [Códigos de falhas](/api-reference/charges/failure-codes) para a lista completa de códigos e categorias. Categoria coarse da recusa: `issuer_declined`, `invalid`, `blocked` ou `processing_error`. Código estável e legível do motivo (`insufficient_funds`, `expired_card`, …). Mensagem em inglês para logs e desenvolvedores. Tentativa de cobrança mais recente. Por padrão vem como ID `ch_*`; pode vir expandida quando você usa `expand[]=latest_charge`. `true` em produção; `false` em ambiente de teste. Objeto livre para correlacionar o intent com o seu sistema. Quando vazio, retorna `{}`. Próxima ação para o comprador. Vem preenchido em fluxos assíncronos como PIX e boleto. `pix_display_qr_code`. Código EMV do PIX. URL de imagem do QR code, quando disponível. Expiração do QR code. `boleto_display_details`. URL do boleto hospedado. Linha digitável. URL do PDF. Código de barras. Vencimento do boleto. Método de pagamento salvo usado no intent. Por padrão vem como ID `pm_*`; pode vir expandido quando você usa `expand[]=payment_method`. Opções por método de pagamento, como parcelamento de cartão. Valor base antes do acréscimo de parcelamento. Total cobrado no cartão. Quantidade de parcelas usada. Quando omitida na criação/update, fica `1`. `true` quando o comprador paga o acréscimo; `false` quando o lojista absorve. Acréscimo de parcelamento em centavos. Métodos permitidos para a cobrança. Hoje pode incluir `credit_card`, `pix` e `boleto`, conforme o fluxo. `off_session`, `on_session` ou `null`, quando o método também será usado no futuro. Estado atual da cobrança. Falta definir o método de pagamento. Pronto para confirmar. Cartão autorizado; falta capturar. Aguardando ação do comprador ou confirmação assíncrona. Pagamento em processamento. Pagamento concluído. Pagamento falhou. Pagamento cancelado. Data da última atualização em ISO 8601. ## Operações * [Listar payment intents](/api-reference/payment-intents/list) * [Criar payment intent](/api-reference/payment-intents/create) * [Consultar payment intent](/api-reference/payment-intents/get) * [Atualizar payment intent](/api-reference/payment-intents/update) * [Confirmar payment intent](/api-reference/payment-intents/confirm) * [Capturar payment intent](/api-reference/payment-intents/capture) * [Cancelar payment intent](/api-reference/payment-intents/cancel) ## Test helpers Em sandbox, você pode avançar um `payment_intent` de teste sem esperar a compensação assíncrona. Test helpers só aceitam chaves `ch_test_...`; chamadas em live mode retornam erro `testmode_required`. | Ação | Endpoint | Resultado | | ------------------------------------------------------------------------------------ | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | [Succeed a Test Payment Intent](/api-reference/test-helpers/payment-intents/succeed) | `POST /v1/test-helpers/payment-intents/{id}/succeed` | Marca o intent como `succeeded`, atualiza a charge como paga e emite os webhooks de sucesso. | | [Fail a Test Payment Intent](/api-reference/test-helpers/payment-intents/fail) | `POST /v1/test-helpers/payment-intents/{id}/fail` | Marca o intent como `failed`, registra `last_payment_error` e emite os webhooks de falha. | | [Expire a Test Payment Intent](/api-reference/test-helpers/payment-intents/expire) | `POST /v1/test-helpers/payment-intents/{id}/expire` | Cancela o intent com `cancellation_reason: "abandoned"` e emite os webhooks de expiração/falha. | Todos retornam `200 OK` com o objeto `payment_intent` completo atualizado. ## Webhooks Para liberar produto, crédito, assinatura ou acesso, prefira webhooks em vez de depender só da resposta síncrona. Eventos principais: * [`payment.intent.created`](/api-reference/webhooks/payment.intent.created) * [`payment.intent.updated`](/api-reference/webhooks/payment.intent.updated) * [`payment.intent.succeeded`](/api-reference/webhooks/payment.intent.succeeded) * [`payment.intent.failed`](/api-reference/webhooks/payment.intent.failed) * [`payment.intent.canceled`](/api-reference/webhooks/payment.intent.canceled)