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

# Captura assíncrona

> Entenda a diferença entre captura automática, captura manual de cartão e pagamentos concluídos de forma assíncrona.

Na Chargefy, `capture_method` aceita `automatic` ou `manual`. Não existe um
terceiro modo configurável de captura assíncrona.

O que pode acontecer de forma assíncrona é a **conclusão do pagamento**. PIX e
boleto retornam antes da confirmação financeira e mudam de status depois. Em
cartão, captura significa outra coisa: efetivar um valor que já foi autorizado.

| Fluxo                         | Configuração                  | Resposta inicial comum   | Conclusão                                 |
| ----------------------------- | ----------------------------- | ------------------------ | ----------------------------------------- |
| Cartão com captura automática | `capture_method: "automatic"` | `succeeded` ou `failed`  | Normalmente acontece na confirmação.      |
| Cartão com captura manual     | `capture_method: "manual"`    | `requires_capture`       | Acontece quando você chama `/capture`.    |
| PIX                           | Não tem etapa de captura      | `pending` com QR code    | Acontece quando o pagamento é confirmado. |
| Boleto                        | Não tem etapa de captura      | `pending` com instruções | Acontece depois da compensação.           |

## Captura automática

Com `capture_method: "automatic"`, a confirmação de um cartão tenta autorizar e
capturar o valor no mesmo fluxo. Quando a operação termina em `succeeded`, o
pagamento pode ser processado.

Esse é o padrão. Omita `capture_method` se você não precisa separar autorização
e captura.

## Captura manual

Use captura manual quando você precisa reservar o valor no cartão e efetivar a
cobrança depois, por exemplo após confirmar estoque ou concluir uma reserva.
Esse fluxo está disponível somente para cartão.

<Steps>
  <Step title="Crie o intent com captura manual">
    Envie `capture_method: "manual"` e confirme o cartão.
  </Step>

  <Step title="Aguarde requires_capture">
    Uma autorização aprovada deixa o intent em `requires_capture` e preenche
    `amount_capturable`.
  </Step>

  <Step title="Capture ou cancele">
    Capture o valor integral pelo endpoint `/capture`. Se não for concluir a
    venda, cancele o intent para liberar a autorização.
  </Step>

  <Step title="Processe o resultado">
    Uma captura concluída leva o intent a `succeeded` e emite
    `payment.intent.succeeded`.
  </Step>
</Steps>

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/payment-intents" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8f4c2a-authorization-1" \
  -d '{
    "amount": 15000,
    "capture_method": "manual",
    "confirm": true,
    "currency": "brl",
    "customer": "cus_iGRTfEaHZKFX8zMy",
    "payment_method": "pm_1D1kiMhLvghrpm2J",
    "payment_method_types": ["credit_card"]
  }'
```

Depois que o intent estiver em `requires_capture`:

```bash theme={"theme":"css-variables"}
curl -X POST \
  "https://api.chargefy.io/v1/payment-intents/pi_cgW23Snx4NNeW238/capture" \
  -H "Authorization: Bearer {{API_KEY}}"
```

<Note>
  A captura atual é integral. Se você enviar `amount_to_capture`, o valor deve
  ser igual a `amount_capturable`.
</Note>

## Pagamentos que terminam de forma assíncrona

PIX e boleto não usam captura manual. A confirmação cria a instrução de
pagamento e retorna o intent em `pending`. O dinheiro ainda não foi recebido.

Apresente `next_action` ao comprador e espere um evento terminal:

| Evento                     | Ação                                                           |
| -------------------------- | -------------------------------------------------------------- |
| `payment.intent.succeeded` | Libere o pedido uma única vez.                                 |
| `charge.failed`            | Registre a tentativa recusada e permita outra no mesmo intent. |
| `payment.intent.canceled`  | Encerre a tentativa; verifique se houve expiração.             |

Não transforme um `pending` ou `processing` em sucesso no seu sistema. Também
não dependa de uma página aberta: o comprador pode pagar fora do navegador e a
confirmação chegar depois.

## Escolha o fluxo certo

* Use captura automática para cobranças de cartão que podem ser concluídas
  imediatamente.
* Use captura manual quando autorização e captura precisam acontecer em
  momentos diferentes.
* Para PIX e boleto, trate o pagamento como assíncrono e reaja por webhook;
  não tente chamar `/capture`.

<CardGroup cols={2}>
  <Card title="Capturar um pagamento" icon="hand-holding-dollar" href="/api-reference/payment-intents/capture">
    Contrato do endpoint de captura manual.
  </Card>

  <Card title="Atualizações do status" icon="arrows-rotate" href="/payments/payment-intents">
    Como acompanhar transições e eventos terminais.
  </Card>
</CardGroup>