Skip to main content
Once the customer completes the Tabby checkout, three server-side steps remain:
1
2
3

​
Payment Verification

Never rely on the redirect alone — always verify the payment server-to-server before processing the order. When the customer lands on one of your redirect URLs, call the Retrieve Request with the payment_id you received at session creation and check the status field: What to do next depends on the status (see Payment Statuses for the full lifecycle):

​
Don’t Miss Authorized Payments

A payment can become AUTHORIZED without a successful redirection — for example, the customer pays and then closes the browser page or mobile WebView before being redirected, or a network issue interrupts the redirect. Catch such payments in one of two ways:
  • Webhooks (recommended). Webhooks are sent on every status change regardless of redirection. When you receive a webhook with the authorized status: if the order is still pending, process it in your OMS and capture the payment; if the order was already processed after the redirect, no action is needed.
  • Polling (fallback). Set up a cron job calling the Retrieve Request every couple of minutes until the payment reaches AUTHORIZED, REJECTED, or EXPIRED.
Webhooks use lowercase statuses ("authorized"), while the Retrieve Request returns uppercase ("AUTHORIZED") — this is expected. See Payment Statuses.

​
Session Expiration

By default, a Tabby checkout session expires 20 minutes after creation, and the payment status changes to EXPIRED about 10 minutes after that — roughly 30 minutes since creation in total. Once the payment is EXPIRED, it is terminal: stop checking it. The session expiry timeout can be reduced on request — contact your assigned business manager in the Integrations thread.

​
Payment Capture

After you verify that the payment is AUTHORIZED, send a Capture Request from your OMS to confirm the order to Tabby. Capturing does not charge the customer anything extra — it confirms the order from your end. Only captured payments are settled to you, and customer disputes are possible only for captured payments. Capture the full payment amount — Tabby verifies that the amount in the Capture Request matches the payment amount. A successful capture returns 200 with the payment status CLOSED; if you get any other response, investigate before retrying. Partial captures are supported, but the best-practice flow is a full capture right after verification.
Only an AUTHORIZED payment can be captured. Capture attempts in CREATED, EXPIRED, CLOSED, or REJECTED return a 400 error.

​
Missing Captures

Tabby tracks non-captured payments. For the first 21 days after authorization the payment is left untouched — you can capture or cancel it at any moment. After 21 days, Tabby may capture the remaining amount in full on its side, as a missing capture is usually caused by a technical issue. Tabby also notifies merchants when we observe regular capture issues. You can find all AUTHORIZED payments on Merchant Dashboard by filtering orders by the NEW status (or by exporting payments as a CSV file) — resolve them by capturing or cancelling.

​
Payment Refund

Use a refund to return a captured amount to the customer. Refunds can be made with the Refund Request or on Merchant Dashboard (merchant.tabby.ai / merchant.tabby.sa for KSA). The request is the same for full and partial refunds — provide the payment_id and the amount:
  • Full refund returns the total captured amount and can be performed only once.
  • Partial refund returns less than the captured amount. A payment can be refunded multiple times, but the total cannot exceed the captured amount.
Refund constraints:
  • Only a CLOSED payment can be refunded.
  • Refunds are processed in the same currency as the captured payment.
  • Refunds can be initiated within 180 days from the payment creation.
  • A processed refund cannot be cancelled.

​
Refunds Troubleshooting

If your refund request didn’t respond with 200, check the following:
  • Is the payment status CLOSED?
  • Is the refund amount higher than the captured amount?
  • Has the payment already been fully refunded?
  • Does the amount format follow the requirements?

​
Idempotent Requests

Capture and Refund requests support idempotency, so you can safely retry them after a connection error without performing the same operation twice. Pass your own unique key in the reference_id parameter of the request:
A retry with the same reference_id will not create a second capture or refund.