> ## 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

> Uma cobrança ao longo de todo o ciclo de vida — criação, confirmação, próxima ação do comprador, falha, sucesso e captura.

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**.

<Info>
  **Payment Intent ≠ Charge ≠ Setup Intent**

  O **payment intent** é o processo da cobrança — vive por todo o ciclo. Cada tentativa concreta de mover dinheiro vira uma [`charge`](/features/charges), 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.
</Info>

## Modelo conceitual

```mermaid theme={}
flowchart LR
  PI[payment_intent] -- latest_charge --> CH[charge]
  PI -. nasce de .-> INV[invoice]
  PI -- customer --> CUS[customer]
  PI -- next_action --> BUY[comprador paga PIX/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`                             |
| **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).

## Para que serve

Use payment intents quando você quer **controlar a cobrança diretamente pela API**, sem depender de uma [Checkout Session](/features/checkout-sessions):

* 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.

<Note>
  Quem prefere uma página de pagamento pronta e hospedada não precisa orquestrar
  o intent manualmente — uma [Checkout Session](/features/checkout-sessions)
  cria e confirma o payment intent por baixo dos panos.
</Note>

## 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](#ciclo-de-vida-e-status)).                |
| `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.

```mermaid theme={}
stateDiagram-v2
  [*] --> requires_payment_method
  [*] --> requires_confirmation
  requires_payment_method --> requires_confirmation: método definido
  requires_confirmation --> processing: confirm (cartão)
  requires_confirmation --> pending: confirm (PIX / boleto)
  pending --> succeeded: comprador pagou
  processing --> succeeded
  processing --> requires_capture: capture_method = manual
  requires_capture --> succeeded: capture
  processing --> requires_payment_method: recusado
  requires_payment_method --> canceled: cancel
  requires_confirmation --> canceled: cancel
  pending --> canceled: cancel / expirou
  requires_capture --> canceled: cancel (estorna autorização)
  succeeded --> [*]
  canceled --> [*]
```

| 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.                                                  |

<Note>
  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.
</Note>

## Como funciona

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

<CodeGroup>
  ```bash Cartão salvo + confirm theme={}
  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"]
    }'
  ```
</CodeGroup>

```json theme={}
{
  "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.

<CodeGroup>
  ```bash Criar PIX theme={}
  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"]
    }'
  ```
</CodeGroup>

```json theme={}
{
  "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.

<CodeGroup>
  ```bash Cartão parcelado theme={}
  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"]
    }'
  ```
</CodeGroup>

<Note>
  `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`.
</Note>

## Próxima ação do comprador

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>
</AccordionGroup>

<Warning>
  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.
</Warning>

## 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={}
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. |

<Tip>
  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](/features/charges).
</Tip>

## 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

<CardGroup cols={2}>
  <Card title="Objeto payment_intent" icon="cube" href="/api-reference/payment-intents">
    Schema público completo e campos retornados.
  </Card>

  <Card title="Charges" icon="receipt" href="/features/charges">
    A tentativa concreta de cobrança gerada pelo intent.
  </Card>

  <Card title="Criar payment intent (API)" icon="code" href="/api-reference/payment-intents/create">
    Contrato do `POST /v1/payment-intents`.
  </Card>

  <Card title="Checkout Sessions" icon="cart-shopping" href="/features/checkout-sessions">
    Página hospedada que cria e confirma o intent por você.
  </Card>
</CardGroup>