> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment intents

> Create and manage a payment from start to finish.

A PaymentIntent tracks one payment from creation through completion. Create it
with an amount and currency, then confirm it with a payment method. Use one
PaymentIntent per order.

Each confirmation creates a Charge. If a card is declined, confirm the same
PaymentIntent again with a different payment method instead of creating a new
one.

## Endpoints

| Endpoint                                                                          | Use it for                                                  |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [Create payment intent](/api-reference/payment-intents/create-a-payment-intent)   | Set the amount and currency for a payment.                  |
| [List payment intents](/api-reference/payment-intents/list-payment-intents)       | Review payments or build reporting.                         |
| [Get payment intent](/api-reference/payment-intents/retrieve-a-payment-intent)    | Check the current status and see previous payment attempts. |
| [Confirm payment intent](/api-reference/payment-intents/confirm-a-payment-intent) | Submit a payment method and attempt the payment.            |
| [Capture payment intent](/api-reference/payment-intents/capture-a-payment-intent) | Capture an authorized manual-capture intent.                |
| [Cancel payment intent](/api-reference/payment-intents/cancel-a-payment-intent)   | Cancel an intent before funds are captured.                 |

## Returned objects

* A PaymentIntent (`pi_…`) contains the amount, currency, and overall payment
  status.
* A Charge (`ch_…`) represents one confirmation attempt. It includes the
  outcome, authorization details, decline details, and settlement status.
* A Refund (`rf_…`) represents money returned from a completed Charge.

A secret-key retrieval includes Charge history. A publishable-key retrieval
requires the `client_secret` and returns only the browser-safe data needed to
continue checkout.

## Browser card collection

When a publishable key retrieves a PaymentIntent, the response can include a
`tokenization` object. Use its `tokenization_key` to initialize Ionic Hosted
Card Fields in the browser. The key can create a one-time payment token; it
cannot submit a charge.

The key is returned with the PaymentIntent so the browser can initialize card
fields after retrieving that intent with a publishable key and its
`client_secret`. The browser does not need access to a secret API key or a
separate account-configuration endpoint. Adapter selection is handled by the
Ionic browser SDK and requires no integration logic.

The API does not include this object in secret-key responses, list responses,
capture or cancel responses, or webhooks.

## Statuses

| Status                    | Meaning                                                                     | What to do next                                             |
| ------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `requires_payment_method` | No usable payment method is attached, or the previous attempt was declined. | Collect or attach a payment method.                         |
| `requires_confirmation`   | A payment method is attached and ready.                                     | Confirm the PaymentIntent.                                  |
| `requires_action`         | The buyer must complete an additional step.                                 | Complete the requested action, then check the status again. |
| `processing`              | The payment is still being processed.                                       | Wait for a webhook or retrieve the PaymentIntent again.     |
| `requires_capture`        | The payment is authorized for manual capture.                               | Capture or cancel it before the authorization expires.      |
| `succeeded`               | The payment completed successfully.                                         | Fulfill the order.                                          |
| `canceled`                | The PaymentIntent can no longer be completed.                               | Create a new PaymentIntent if the buyer still wants to pay. |

## Retry and fulfillment rules

* Send an `Idempotency-Key` on create, confirm, capture, and cancel requests so
  retries do not duplicate an operation.
* A `402` decline embeds the current PaymentIntent; inspect its status before
  deciding whether to collect another payment method.
* If you cancel while the status is `processing`, the status can remain
  `processing` until the current attempt finishes. Wait for a webhook or
  retrieve the PaymentIntent again before retrying.
* Fulfill an order only after the API response or a verified webhook reports a
  successful payment. A browser redirect alone is not confirmation.