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

# Create a Payment Intent

> Cria um payment intent.

Cria um `payment_intent`, o objeto que representa o ciclo de vida de uma
cobrança. Para cobrar um cartão salvo, informe `customer`, `payment_method` e
confirme o intent. Para PIX, crie o intent com `payment_method_types: ["pix"]`
e confirme para receber o QR code em `next_action`.

Use `payment_intent` como objeto canônico da cobrança. Ele pode ser criado
diretamente pela API, por uma invoice ou por uma checkout session. Não use uma
checkout session como chave de idempotência de pagamento nem como ledger
financeiro.

<Tip>
  Veja [Ciclo de pagamento](/integrate/payment-lifecycle) para entender quando
  usar `checkout.session`, `payment_intent`, `invoice` e `payment_method`.
</Tip>

<ParamField body="amount" type="integer" required>
  Valor base em centavos. Quando o comprador paga juros de parcelamento, o
  `amount` retornado passa a ser o total cobrado e o valor original fica em
  `amount_details.subtotal`.
</ParamField>

<ParamField body="currency" type="string">
  Moeda em minúsculas. Padrão: `brl`.
</ParamField>

<ParamField body="customer" type="string">
  Customer associado (`cus_*`).
</ParamField>

<ParamField body="payment_method" type="string">
  Payment method salvo (`pm_*`). Quando informado, o intent nasce em
  `requires_confirmation`.
</ParamField>

<ParamField body="payment_method_types" type="array">
  Aceita `credit_card` e `pix`. Padrão: `["credit_card"]`.
</ParamField>

<ParamField body="payment_method_options" type="object">
  Opções por método de pagamento.
</ParamField>

<ParamField body="capture_method" type="string">
  `automatic` ou `manual`. Use `manual` para autorizar cartão agora e capturar
  depois com `POST /v1/payment-intents/:id/capture`.
</ParamField>

<ParamField body="payment_method_options.credit_card.installments.count" type="integer">
  Número de parcelas de cartão, de `1` a `12`. O máximo também respeita o valor
  mínimo por parcela. Quando omitido, usa `1`.
</ParamField>

<ParamField body="payment_method_options.credit_card.installments.has_interest" type="boolean">
  `true` quando o comprador paga o acréscimo do parcelamento; `false` quando o
  lojista absorve o acréscimo (venda sem juros ao comprador). A taxa é definida
  no plano de parcelamento da organização. Quando omitido, usa a configuração da
  organização.
</ParamField>

<ParamField body="confirm" type="boolean">
  Se `true`, cria e confirma a cobrança na mesma chamada.
</ParamField>

<ParamField body="setup_future_usage" type="string">
  `off_session` ou `on_session`, quando o método também será usado no futuro.
</ParamField>

<ParamField body="metadata" type="object">
  Metadata livre.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/payment-intents" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 10000,
      "customer": "cus_123",
      "payment_method": "pm_123",
      "payment_method_options": {
        "credit_card": {
          "installments": {
            "count": 3
          }
        }
      },
      "payment_method_types": ["credit_card"]
    }'
  ```
</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": 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": null,
    "livemode": true,
    "metadata": {
      "order_id": "id_456"
    },
    "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": "requires_confirmation",
    "updated_at": null
  }
  ```

  ```json 400 theme={}
  {
    "error": {
      "code": "invalid_request",
      "message": "amount must be a positive integer.",
      "param": "amount",
      "type": "invalid_request_error"
    }
  }
  ```

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

  ```json 404 theme={}
  {
    "error": {
      "code": "resource_missing",
      "message": "Customer not found.",
      "param": "customer",
      "type": "invalid_request_error"
    }
  }
  ```
</ResponseExample>