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

# Payment lifecycle

> Immediate sales, statuses, and when to void or refund.

A payment records the outcome of a charge and any subsequent voids or refunds.

## Payments are immediate sales

`POST /payments` charges the card immediately. The request field `capture` defaults to `"sale"`, and the response reports it back as `captureMode: "sale"`.

<Note>
  **Authorize now, capture later is not supported.** `capture: "auth"` and `POST /payments/{id}/capture` return `501 CAPTURE_NOT_SUPPORTED`.
</Note>

## Status reference

| Status | Meaning |
| - | - |
| `succeeded` | The card was charged |
| `failed` | The charge was declined or failed |
| `voided` | Cancelled before the batch settled |
| `partially_refunded` | Part of the payment has been refunded |
| `refunded` | The payment has been fully refunded |
| `unknown` | The gateway outcome could not be determined; check again before acting |

## State diagram

```mermaid theme={null}
stateDiagram-v2
    [*] --> succeeded: create
    [*] --> failed: create (declined)
    succeeded --> voided: void (batch open)
    succeeded --> partially_refunded: refund (partial)
    succeeded --> refunded: refund (full)
    partially_refunded --> refunded: refund (remainder)
```

## Settlement and batches

A batch is a group of transactions the payment processor submits for settlement. Settlement is the process of transferring funds for those transactions. Whether a payment has settled determines whether it can be voided or requires a refund.

## Void or refund

<Note>
  `POST /payments/{id}/void` cancels the payment before its batch settles, including the principal and any separately charged service fee. The principal is the payment amount excluding the service fee.

  If the gateway rejects the void because the batch has settled, the API returns `422 VOID_FAILED` with `details.suggestedAction: "refund"`. The void endpoint does not issue a refund automatically.

  `POST /payments/{id}/refund` reverses a payment. If the payment has not settled, the API voids it instead. The response identifies the operation in `reversalType`, which is `"void"` or `"refund"`.

  Use the void endpoint when you want cancellation to fail if a void is unavailable. Use the refund endpoint to let the API select the reversal operation.
</Note>

See [Refunds](/guides/refunds-and-line-items) for partial refunds and service-fee handling. The exact request and response schemas are in the **API Reference** tab.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.