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

# Payment Operations

> lite's supported payment operations and their transitions.

After a payment is authorized, you control what happens next. You can capture the funds, extend the authorization, void it, or let it expire. After capture, you can refund. This page describes each operation, when it is available, and what the customer and your balance experience at each step.

This page covers online payments. In-person payments support their own set of terminal operations and are documented separately.

## How payment status works

Every payment has a single status. The status reflects the last completed operation. Operations that are still processing do not change the status. A payment stays `authorized` while a capture is in flight and moves to `captured` only when the capture succeeds.

| Status               | Meaning                                                                                                              |
| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `pending`            | Awaiting the authorization response from the card network.                                                           |
| `authorized`         | The issuer approved the payment and reserved the funds on the customer's card. No money has moved.                   |
| `failed`             | Either due to an Issuer decline, network error or any other system failure.                                          |
| `expired`            | The authorization validity period ended before capture. The reserved funds were released to the customer.            |
| `voided`             | You cancelled the authorization before capture. The customer was never charged and the hold on the fund is released. |
| `captured`           | The full authorized amount was captured and submitted for settlement.                                                |
| `partially_captured` | You captured part of the authorized amount. The remainder is still reserved.                                         |
| `refunded`           | A refund has been issued against the captured amount.                                                                |

`failed`, `expired`, and voided\`are terminal. A payment in a terminal state accepts no further operations.

### Operation availability

| Operation | Available when the payment is                                | Resulting status                   |
| --------- | ------------------------------------------------------------ | ---------------------------------- |
| Capture   | `authorized`, `partially_captured`                           | `captured` or `partially_captured` |
| Extend    | `authorized`                                                 | `authorized`                       |
| Void      | `authorized`                                                 | `voided`                           |
| Refund    | `captured`, or `refunded` with a remaining refundable amount | `refunded`                         |

## Capture a payment

Capture claims the funds reserved by an authorization. Capture is the operation that charges the customer and starts the movement of money toward your account.

### Choose a capture mode

You decide when capture happens by setting the capture mode when you create the payment:

* **Immediate.** The payment is authorized and captured in one step. The right choice when goods or services are delivered at the moment of purchase.
* **Manual.** The payment stops at `authorized`, and you call capture when you are ready. Use this when the the fulfillment moment is not known at checkout.

### Capture the full amount or part of it

When you capture, you can claim:

* **The full authorized amount.** The payment moves to `captured`.
* **Part of the authorized amount.** The payment moves to `partially_captured`. The remaining authorized amount stays reserved.
* **Final capture:** set the final capture to true when you want to indicate that this capture is the final one, and hence the remaining amount under authorization hold shall be releazed.

You can capture a `partially_captured` payment again. When the captured total reaches the authorized amount, the payment moves to `captured`.

## Void a payment

Void cancels an authorization before capture. The reserved funds are released and the customer is never charged. The payment moves to `voided`, a terminal state. You can record a reason with the void for your own audit trail.

Use void when an order is cancelled before fulfillment. Because no money moved, there is nothing to refund. The hold on the customer's card is removed. Depending on the customer's bank, the reserved amount can take a few business days to disappear from their account view.

Void and refund are different operations:

|                 | Void                                              | Refund                                  |
| --------------- | ------------------------------------------------- | --------------------------------------- |
| When            | Before capture                                    | After capture                           |
| What it does    | Releases a hold and prevents the charge.          | Returns money that was already charged. |
| Customer impact | The pending amount disappears from their account. | A credit is returned to their card.     |

## Refund a payment

Refund returns captured funds to the customer. Refunds are available once a payment has been fully captured. You can refund the full captured amount or part of it, and you can issue additional refunds until the full captured amount has been returned. The total refunded can never exceed the total captured.

A full refund, moves the payment to \`refunded', refunding only a part of the captured amount maintains the payment state in 'captured'.

The refund travels back to the customer through the card networks. On your side, the refunded amount is deducted from your next settlement rather than debited as a separate transfer.

A fully refunded payment accepts no further captures.

## Handle authorization expiry

Every authorization has a validity period. If you neither capture, extend, nor void before the period ends, the authorization expires automatically. The payment moves to `expired` and the reserved funds are released to the customer.

An expired payment is terminal. To charge the customer after expiry, create a new payment.

To avoid unintended expiry:

* Capture as soon as you are ready to fulfill the order.
* Void promptly when an order is cancelled instead of letting the hold lapse.
* Extend the authorization when fulfillment is delayed.
