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

# Payment Lifecycle: Authorize, Capture, Refund, and Cancel

> Understand the Therius payment lifecycle — authorization, capture, partial refunds, and voiding — and choose the right flow for your use case.

Every payment moves through a predictable series of states — from an initial reserve of funds through to final settlement or cancellation. Therius gives you two ways to move a payment through that lifecycle: a one-step flow that authorizes and captures in a single call, and a two-step flow that separates authorization from capture. Knowing which flow to use, and when each post-payment operation applies, will save you from edge cases and disputed charges.

## One-Step Flow: Purchase

Use `POST /payment/purchase` when you can fulfill the order immediately — digital downloads, SaaS subscriptions, and any product you deliver the moment payment completes. A single round-trip reserves the funds and settles them in one go. The response carries `status: "captured"` and an `id` — the payment handle.

```json theme={"dark"}
{
  "id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
  "status": "captured",
  "paymentCode": "PAY-abc123",
  "orderCode": "ORDER-001"
}
```

## Two-Step Flow: Authorize → Capture

Use `POST /payment/authorization` to reserve funds without settling them. This is the right flow when you need to confirm availability before you fulfill — for example, physical goods that may go out of stock, or hotel reservations where you confirm the room before charging.

```txt theme={"dark"}
POST /payment/authorization  →  status: "authorized", id: "<payment id>"
POST /payment/{id}/capture   →  status: "captured"
```

The authorization response includes an `id` (a UUID). That `id` is how you address
the payment for every follow-up operation — pass it as the `{id}` path segment.

A few rules apply:

* **Authorization window** is typically 7 days, though some acquirers allow shorter or longer windows. If you do not capture within the window, the authorization expires and the funds are released automatically.
* **Partial capture** is supported. You can capture any amount up to the authorized amount. For example, authorize $100 and capture $80 if one item is out of stock.
* Once a payment is captured you cannot capture again — use refund for any adjustments.

## Refund

Call `POST /payment/{id}/refund` to return funds on a captured payment. Refunds can be full or partial, and you can issue multiple partial refunds as long as the cumulative total does not exceed the originally captured amount.

```json theme={"dark"}
{
  "merchantCode": "MERCHANT_001",
  "amount": { "currency": "USD", "value": 500, "exponent": 2 }
}
```

A partial refund of $5.00 on a $19.99 payment returns the difference to the cardholder. The payment status moves to `refunded` once a full refund is processed.

## Cancel

Call `POST /payment/{id}/cancel` to void an **authorized** payment before it is captured. Funds are released immediately and the customer is never charged. You cannot cancel a payment that has already been captured — call `POST /payment/{id}/refund` instead.

## Auto Cancel or Refund

If you are not sure whether a payment is in `authorized` or `captured` state, call `POST /payment/{id}/cancel_or_refund`. Therius checks the current state and performs the correct operation automatically — a cancel if the payment is authorized, a full refund if it is captured.

## Payment Statuses

| Status           | Description                                                                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `captured`       | Funds settled. The payment is complete.                                                                                                             |
| `authorized`     | Funds reserved but not yet settled. Capture or cancel next.                                                                                         |
| `refunded`       | A full (or final partial) refund has been issued.                                                                                                   |
| `cancelled`      | Authorization voided before capture. Funds released.                                                                                                |
| `pending_action` | Waiting for an action from the shopper (e.g., redirect to a bank page for APM). The final outcome arrives by [webhook](/webhooks/overview).         |
| `pending_3ds`    | 3DS2 challenge required. Resume with `POST /payment/resume`.                                                                                        |
| `declined`       | Payment was declined by the issuer or acquirer. The response carries a `refusalCode` object — see [Declined Payments](/concepts/declined-payments). |
| `failed`         | A processing error prevented the payment from completing.                                                                                           |

## State Machine

```mermaid theme={"dark"}
stateDiagram-v2
    [*] --> authorized : POST /payment/authorization
    [*] --> captured : POST /payment/purchase
    authorized --> captured : POST /payment/{id}/capture
    authorized --> cancelled : POST /payment/{id}/cancel
    captured --> refunded : POST /payment/{id}/refund
    [*] --> pending_3ds : 3DS challenge triggered
    pending_3ds --> authorized : POST /payment/resume
    pending_3ds --> captured : POST /payment/resume
    [*] --> declined : Issuer decline
    [*] --> failed : Processing error
```

## `id`, `paymentCode`, and `orderCode`

| Field         | Set by                                   | Purpose                                                                                                                                                                              |
| ------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`          | Therius (returned on authorize/purchase) | **The handle for the payment.** Pass it as the `{id}` path segment of capture, refund, cancel and cancel\_or\_refund.                                                                |
| `orderCode`   | You, on the create call                  | Your own reference for the order (e.g., `ORDER-2024-001`).                                                                                                                           |
| `paymentCode` | You (optional) or Therius                | A per-attempt reference. If you support multiple attempts for one order (e.g., a retry after a decline), each attempt can carry its own `paymentCode` while sharing the `orderCode`. |

`orderCode` and `paymentCode` are reference fields only — they are echoed back on responses and webhooks. [Inquiry](/api-reference/inquiry) accepts either the `id` or the `paymentCode` in its path. But capture, refund, cancel and cancel\_or\_refund take **only** the `id`. Always store the `id` from the authorize/purchase response and use it for those calls.