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

# Confirm a Payment Intent

> Confirma um payment intent.

Confirma um `payment_intent` e inicia a cobrança. A confirmação cria uma
`charge`, que representa a tentativa de pagamento dentro do intent. Para cartão, use um
`payment_method` salvo. Para PIX, informe `payment_method_type: "pix"` ou crie
o intent apenas com `payment_method_types: ["pix"]`; a resposta traz o QR code
em `next_action.pix_display_qr_code` e o status fica `pending` até a
confirmação assíncrona.

Para **boleto**, o mesmo padrão se aplica: `payment_method_type: "boleto"`
(opcionalmente `boleto_due_date` em ISO `YYYY-MM-DD`). A resposta traz a
linha digitável, código de barras e URL do PDF em
`next_action.boleto_display_details`; o status fica `pending` até o pagamento
ser confirmado pelo banco.

Confirme um intent pelo próprio ID `pi_*`. Quando o intent foi criado por outro
fluxo, trate esse fluxo como origem ou contexto, não como chave da tentativa de
pagamento. O estado financeiro mora no `payment_intent` e nos webhooks de
`payment.intent.*`. Não crie `charges` diretamente: para cobrar alguém, crie e
confirme um `payment_intent`.

Quando `capture_method` é `manual`, a confirmação de cartão autoriza o valor e
retorna o intent em `requires_capture` com `amount_capturable` preenchido. Use
`POST /v1/payment-intents/:id/capture` para capturar.

<ParamField path="id" type="string" required>
  ID do payment intent (`pi_*`).
</ParamField>

<ParamField body="customer" type="string">
  Customer associado. Obrigatório se o intent foi criado sem customer.
</ParamField>

<ParamField body="payment_method" type="string">
  Payment method salvo para cartão. Obrigatório para cobrança de cartão se o
  intent ainda não tem método.
</ParamField>

<ParamField body="payment_method_type" type="string">
  Método a confirmar quando o intent permite mais de um método. Aceita
  `credit_card` ou `pix`.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/payment-intents/pi_123/confirm" \
    -H "Authorization: Bearer {{API_KEY}}"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={}
  {
    "id": "pi_123",
    "object": "payment_intent",
    "amount": 10528,
    "amount_capturable": 0,
    "amount_details": {
      "installment_interest": 528,
      "subtotal": 10000,
      "total": 10528
    },
    "amount_received": 10528,
    "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": {},
    "next_action": null,
    "payment_method": "pm_123",
    "payment_method_options": {
      "credit_card": {
        "installments": {
          "amount_subtotal": 10000,
          "amount_total": 10528,
          "count": 3,
          "has_interest": true,
          "interest_amount": 528
        }
      }
    },
    "payment_method_types": [
      "credit_card"
    ],
    "setup_future_usage": null,
    "status": "succeeded",
    "updated_at": "2026-05-16T18:35:00Z"
  }
  ```
</ResponseExample>

## Confirmar PIX

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/payment-intents/pi_pix_123/confirm" \
    -H "Authorization: Bearer {{API_KEY}}"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={}
  {
    "id": "pi_pix_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_pix_123_secret_abc",
    "confirmation_method": "automatic",
    "created_at": "2026-05-16T18:34:58Z",
    "currency": "brl",
    "customer": null,
    "invoice": null,
    "last_payment_error": null,
    "latest_charge": "ch_pix_123",
    "livemode": true,
    "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"
    ],
    "setup_future_usage": null,
    "status": "pending",
    "updated_at": "2026-05-16T18:35:00Z"
  }
  ```

  ```json Boleto pending theme={}
  {
    "id": "pi_boleto_456",
    "object": "payment_intent",
    "amount": 14990,
    "amount_capturable": 0,
    "amount_details": {
      "installment_interest": 0,
      "subtotal": 14990,
      "total": 14990
    },
    "amount_received": 0,
    "canceled_at": null,
    "cancellation_reason": null,
    "capture_method": "automatic",
    "client_secret": "pi_boleto_456_secret_abc",
    "confirmation_method": "automatic",
    "created_at": "2026-05-16T18:34:58Z",
    "currency": "brl",
    "customer": null,
    "invoice": null,
    "last_payment_error": null,
    "latest_charge": "ch_boleto_456",
    "livemode": true,
    "metadata": {},
    "next_action": {
      "boleto_display_details": {
        "barcode": "23791966600000149903381286008296100211202300",
        "expires_at": "2026-05-19",
        "hosted_voucher_url": "https://provider.example.com/boletos/abc.pdf",
        "number": "23793.38128 60082.961002 11202.300008 1 96660000014990",
        "pdf": "https://provider.example.com/boletos/abc.pdf"
      },
      "type": "boleto_display_details"
    },
    "payment_method": null,
    "payment_method_options": {},
    "payment_method_types": ["boleto"],
    "setup_future_usage": null,
    "status": "pending",
    "updated_at": "2026-05-16T18:35:00Z"
  }
  ```

  <Note>
    `hosted_voucher_url` aponta para o **PDF do boleto** por enquanto. A Chargefy
    planeja uma página hospedada dedicada em release futuro; até lá, o valor é
    idêntico a `pdf`.
  </Note>
</ResponseExample>

<ResponseExample>
  ```json 400 theme={}
  {
    "error": {
      "code": "invalid_request",
      "message": "payment_method is required for credit_card confirmation.",
      "param": "payment_method",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={}
  {
    "error": {
      "code": "authentication_failed",
      "message": "Invalid API key provided.",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={}
  {
    "error": {
      "code": "payment_failed",
      "message": "Payment method was declined.",
      "type": "card_error"
    }
  }
  ```

  ```json 404 theme={}
  {
    "error": {
      "code": "resource_missing",
      "message": "Payment intent not found.",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 409 theme={}
  {
    "error": {
      "code": "resource_state_conflict",
      "message": "Payment intent cannot be confirmed in status succeeded.",
      "type": "invalid_request_error"
    }
  }
  ```
</ResponseExample>

## Erros comuns

| Status | `code`                    | Quando ocorre                                                                                                  |
| ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request`         | Falta `customer` ou `payment_method` para cartão, ou falta `payment_method_type` quando há múltiplos métodos.  |
| `402`  | `payment_failed`          | A tentativa de pagamento foi recusada. Consulte `last_payment_error` no payment intent para o motivo granular. |
| `409`  | `resource_state_conflict` | O payment intent não pode mais ser confirmado.                                                                 |