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

# Payment Statuses

> How a Tabby payment moves through its lifecycle, and how API statuses map to what you see on Merchant Dashboard.

## Payment Lifecycle

The `status` field of a payment (`GET /api/v2/payments/{id}`) has five possible values: `CREATED`, `AUTHORIZED`, `CLOSED`, `REJECTED`, and `EXPIRED`.

```mermaid theme={"dark"}
flowchart LR
    CREATED -- "order placed" --> AUTHORIZED
    AUTHORIZED -- "full capture or close" --> CLOSED
    CREATED -. "Tabby declines" .-> REJECTED
    CREATED -. "cancelled or timed out" .-> EXPIRED

    classDef happy fill:#E8FBF3,stroke:#10B981,stroke-width:1.5px,color:#065F46
    classDef terminal fill:#F3F4F6,stroke:#9CA3AF,color:#6B7280
    class CREATED,AUTHORIZED,CLOSED happy
    class REJECTED,EXPIRED terminal
```

Two statuses allow repeated actions without changing: a **partial capture** keeps the payment `AUTHORIZED`, and a **refund** keeps it `CLOSED`.

| API `status` | Meaning                                                                                                  | Triggered by                                                       | Terminal?                     |
| ------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------- |
| `CREATED`    | Payment created together with the checkout session; the customer hasn't completed the Tabby checkout yet | Your Create Checkout Session request                               | No                            |
| `AUTHORIZED` | Order placed; funds are reserved but not captured yet                                                    | Customer completes the Tabby checkout                              | No                            |
| `CLOSED`     | Final state: captured in full, cancelled, or partially captured and then closed                          | Your Capture or Close request                                      | Yes — but refunds are allowed |
| `REJECTED`   | Tabby declined the order at checkout                                                                     | Tabby scoring                                                      | Yes                           |
| `EXPIRED`    | The checkout was never completed                                                                         | Customer cancelled on the Tabby checkout, or the session timed out | Yes                           |

Note that `EXPIRED` does **not** mean an authorization expired — it always refers to the checkout. Payments in `REJECTED` and `EXPIRED` require no action from your end and are not shown on Merchant Dashboard.

## Merchant Dashboard Statuses

Merchant Dashboard uses its own display statuses on top of the API ones. The mapping:

| Merchant Dashboard   | API `status` | How the payment got there                                    |
| -------------------- | ------------ | ------------------------------------------------------------ |
| `NEW`                | `AUTHORIZED` | Authorized; nothing captured yet, or captured only partially |
| `CAPTURED`           | `CLOSED`     | Captured in full, or partially captured and then closed      |
| `CANCELLED`          | `CLOSED`     | Closed without any capture                                   |
| `REFUNDED`           | `CLOSED`     | Captured, then refunded in full                              |
| `PARTIALLY REFUNDED` | `CLOSED`     | Captured, then refunded partially                            |

## Lifecycle in Detail

<Steps>
  <Step title="Payment Creation">
    When you create a checkout session, Tabby creates a payment with status `CREATED` along with it — before the customer opens the Tabby checkout page.

    *Payments in this status are not shown on Merchant Dashboard.*
  </Step>

  <Step title="Payment Authorization">
    After successful order placement the payment becomes `AUTHORIZED`: the funds are reserved on the customer's side, but not transferred yet.

    *Shown on Merchant Dashboard as `NEW`.*

    <Warning>
      Instead of `AUTHORIZED`, the payment can end up `REJECTED` (Tabby declined the order) or `EXPIRED` (the customer cancelled on the Tabby checkout, or the session timed out). Both are terminal — no action is required from your end.
    </Warning>
  </Step>

  <Step title="Payment Capture">
    Send a Capture request as soon as the payment is authorized. When the full amount is captured, the payment automatically becomes `CLOSED`.

    *Shown on Merchant Dashboard as `CAPTURED`.*

    **Partial capture** is supported: the payment stays `AUTHORIZED` (Dashboard: `NEW`) until you capture the full amount or send a Close request.

    <Tip>
      Don't leave payments in `AUTHORIZED` longer than necessary — the payout for a payment is processed only after it is closed.
    </Tip>
  </Step>

  <Step title="Close (Optional)">
    Use a Close request when part of the order won't be delivered:

    * **After a partial capture** — Close cancels and refunds everything that wasn't captured. The payment becomes `CLOSED`, shown on Merchant Dashboard as `CAPTURED`.
    * **Without any capture** — Close cancels the payment completely. The payment becomes `CLOSED`, shown on Merchant Dashboard as `CANCELLED`.
  </Step>

  <Step title="Refund">
    Only a `CLOSED` payment can be refunded, and the refund amount cannot exceed the captured amount. Full and multiple partial refunds are supported; the payment stays `CLOSED`.

    *Shown on Merchant Dashboard as `REFUNDED` or `PARTIALLY REFUNDED`.*
  </Step>
</Steps>

## Statuses in API Responses vs Webhooks

API responses return statuses in uppercase (`"AUTHORIZED"`), while webhook payloads use lowercase (`"authorized"`). Compare statuses case-insensitively.

<Note>
  To make sure any text you send in JSON is transmitted and displayed correctly in Tabby interfaces, use **UTF-8** encoding.
</Note>