Skip to main content

​
Payment Lifecycle

The status field of a payment (GET /api/v2/payments/{id}) has five possible values: CREATED, AUTHORIZED, CLOSED, REJECTED, and EXPIRED. Two statuses allow repeated actions without changing: a partial capture keeps the payment AUTHORIZED, and a refund keeps it CLOSED. 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:

​
Lifecycle in Detail

1

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.
2

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.
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.
3

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.
Don’t leave payments in AUTHORIZED longer than necessary — the payout for a payment is processed only after it is closed.
4

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.
5

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.

​
Statuses in API Responses vs Webhooks

API responses return statuses in uppercase ("AUTHORIZED"), while webhook payloads use lowercase ("authorized"). Compare statuses case-insensitively.
To make sure any text you send in JSON is transmitted and displayed correctly in Tabby interfaces, use UTF-8 encoding.