` element with a unique selector, preferably using an `id`:
```html theme={"dark"}
```
For maximum visibility, place the container in one of the suggested places:
* **Product**: near the product price or next to the "Add to cart" button;
* **Cart**: below the total cart amount.
Include the Tabby Promo script in your page and initialize the `TabbyPromo` component after the script loads:
```html theme={"dark"}
```
Re-initialize `TabbyPromo` when the price changes (e.g. variant or quantity selectors).
If the white background of the snippet does not match your website design and you want the snippet to inherit the background color, you can use `shouldInheritBg: true`. When this parameter is set to `true`, you can also customize the text and link colors using the following CSS variables:
```css theme={"dark"}
--snippetTextColor: white;
--snippetLinkTextColor: white;
```
#### Complete Product and Cart snippet example
```html theme={"dark"}
```
### Checkout snippet
The checkout snippet uses the `TabbyCard` component to display payment information during checkout.
Create an empty `
` element where the Tabby Card will be displayed:
```html theme={"dark"}
```
Place this `div` under the Tabby payment method option. Display it when the Tabby payment method is selected.
Load and initialize `TabbyCard`:
```html theme={"dark"}
```
#### Complete Checkout snippet example
```html theme={"dark"}
```
Snippets only need your Public Key and merchant code — never expose the Secret Key in frontend code.
Make sure snippets fit mobile screen widths (320px minimum).
## Live demo
Everything below is rendered live by `tabby-promo.js` and `tabby-card.js` — exactly what your customers will see. Switch the market to preview English/AED and Arabic/SAR, and click "Learn more" to open the real pop-up.
[Tabby On-Site Messaging live demo](https://bnpl-demo.com/snippet-demo.html)
## Custom Promo Snippets
If you can't load Tabby's JavaScript (security policies, native mobile apps, full styling control), build your own message and open the Tabby "Learn more" pop-up via a direct URL:
| Description | URL |
| - | - |
| UAE pop-up, English | [**https://checkout.tabby.ai/promos/product-page/installments/en/?price=2000.00\¤cy=AED\&merchant\_code=your\_merchant\_code\&public\_key=pk\_xyz**](https://checkout.tabby.ai/promos/product-page/installments/en/?price=2000.00\¤cy=AED\&merchant_code=your_merchant_code\&public_key=pk_...) |
| KSA pop-up, Arabic | [**https://checkout.tabby.sa/promos/product-page/installments/ar/?price=2000.00\¤cy=SAR\&merchant\_code=your\_merchant\_code\&public\_key=pk\_xyz**](https://checkout.tabby.sa/promos/product-page/installments/ar/?price=2000.00\¤cy=SAR\&merchant_code=your_merchant_code\&public_key=pk_...) |
#### URL Parameters
| Parameter | Required | Description | Values |
| - | - | - | - |
| `merchant_code` | Yes | Your merchant code | Provided by Tabby |
| `public_key` | Yes | Your Tabby public key | `'pk_test_...'`, `'pk_...'` |
| `price` | Yes | Product or cart price | `'1200.00'`, `'99.99'` |
| `currency` | Yes | Currency code | `AED`, `SAR` |
| `lang` | No | Language code | `en`, `ar` |
> [!NOTE]
>
> If you implement your own custom snippet, notify your Tabby account manager so we can keep your integration in sync with upcoming changes.
For promo messaging inside native mobile apps, see [App Promo Messaging](/pay-in-4-custom-integration/mobile-apps/app-promo-messaging).
# Payment Processing
Source: https://docs.tabby.sa/pay-in-4-custom-integration/payment-processing
What to do after the customer completes the Tabby checkout: verify the payment, capture it, and process refunds when needed.
Once the customer completes the Tabby checkout, three server-side steps remain:
***
***
***
## 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](/api-reference/payments/retrieve-a-payment) with the `payment_id` you received at [session creation](/pay-in-4-custom-integration/checkout-flow#checkout-session-initiation) and check the `status` field:
| Customer redirected to | Expected payment `status` |
| - | - |
| Success URL | `AUTHORIZED` |
| Cancel URL | `EXPIRED` |
| Failure URL | `REJECTED` |
What to do next depends on the status (see [Payment Statuses](/pay-in-4-custom-integration/payment-statuses) for the full lifecycle):
| Payment `status` | Your action |
| - | - |
| `AUTHORIZED` | Process the order in your OMS, [capture the payment](/pay-in-4-custom-integration/payment-processing#payment-capture), and notify the customer that the order is confirmed (Tabby also sends its own payment confirmation) |
| `REJECTED` / `EXPIRED` | Cancel or delete the order in your OMS |
| `CREATED` | The checkout is not finished yet — keep checking until the status changes or the session expires |
### 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](/pay-in-4-custom-integration/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`.
> [!TIP]
>
> Webhooks use lowercase statuses (`"authorized"`), while the Retrieve Request returns uppercase (`"AUTHORIZED"`) — this is expected. See [Payment Statuses](/pay-in-4-custom-integration/payment-statuses#statuses-in-api-responses-vs-webhooks).
### 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](/api-reference/payments/capture-a-payment) 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.
> [!WARNING]
>
> 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](/api-reference/payments/refund-a-payment) or on Merchant Dashboard ([merchant.tabby.ai](https://merchant.tabby.ai/) / [merchant.tabby.sa](https://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.
### How a Refund Affects the Customer's Instalments
Choose the refund type by what the customer returns:
* the whole order — make a **full refund** (refunded amount = captured amount). It cancels all upcoming instalments and returns the downpayment to the customer;
* only some items — make a **partial refund** (refunded amount \< captured amount). Tabby first reduces the remaining instalments, and only if the refund is larger than them, returns part of the downpayment.
Example: a Pay in 4 purchase of 100 — downpayment 25, remaining instalments 25 + 25 + 25 = 75.
| Refund | What happens | Customer's instalments after the refund |
| - | - | - |
| Partial, 10 | Refund \< remaining instalments: only the remaining instalments are reduced | ≈ 21.67 + 21.67 + 21.67 |
| Partial, 60 | Refund \< remaining instalments: only the remaining instalments are reduced | 5 + 5 + 5 |
| Partial, 80 | Refund > remaining instalments: the remaining instalments are cancelled and 5 of the downpayment is returned | None — the customer has paid 20 in total for this payment |
| Full, 100 | All upcoming instalments are cancelled, the whole downpayment is returned | None |
You cannot refund more than has been captured.
Fees and Murabaha profit charged on the plan are refunded to the customer as well — in full with a full refund, proportionally with a partial one (see the [F.A.Q.](/introduction/faq#if-a-refund-is-requested-will-the-fees-or-murabaha-profit-be-refunded-too)).
### 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](/introduction/technical-requirements#amount)?
## 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:
```JSON theme={"dark"}
{
"reference_id": "some_key"
}
```
A retry with the same `reference_id` will not create a second capture or refund.
> [!TIP]
>
> **Derive the key from your order, not from the clock.** A `reference_id` like `capture-{your_order_id}` stays the same no matter which code path retries the capture; a timestamp-based key defeats idempotency — every retry becomes a "new" capture.
### Avoiding Duplicate Captures
In a typical integration **two code paths can try to capture the same payment**: the success-redirect handler (customer came back to your site) and the `authorized` webhook handler (fires regardless of the redirect). If both run, you get duplicate capture attempts — harmless with a shared `reference_id`, noisy `400 already closed` errors without one.
Guard the capture with both layers:
1. **Local claim** — before calling capture, atomically mark the payment as capture-in-progress in your database (e.g. an `UPDATE ... WHERE status = 'authorized'` that only one caller can win). The losing path skips the capture. If the capture API call fails, release the claim so a later retry can proceed.
2. **Shared `reference_id`** — both paths derive the same key from the order id, so even if the local guard misses, Tabby deduplicates the capture on its side.
The webhook-side check is described in [Handling Edge Cases](/pay-in-4-custom-integration/webhooks#a-capture-confirmation-is-not-a-request-to-capture): a webhook whose `captures` array is already non-empty is a confirmation, not a trigger.
# Payment Statuses
Source: https://docs.tabby.sa/pay-in-4-custom-integration/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
**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`.*
> [!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.
**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.
> [!TIP]
>
> 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.
> [!NOTE]
>
> To make sure any text you send in JSON is transmitted and displayed correctly in Tabby interfaces, use **UTF-8** encoding.
# Quick Start
Source: https://docs.tabby.sa/pay-in-4-custom-integration/quick-start
## Integration Overview
Get started with Tabby's Buy Now, Pay Later solution. This guide walks you through integrating Tabby Payments into your website or mobile app, allowing your customers to split purchases into interest-free installments.
## See It In Action
## Integration Steps
### Setup
***
***
### Development
***
***
***
***
#### Your first session, server-side
Create a checkout session from your backend (never from the browser — the request carries your Secret Key), read the HPP link from `configuration.available_products.installments[0].web_url`, and redirect the customer to it. Full payload reference: [Session payload model](/api-reference/checkout/session-payload-model).
> **Code examples: cURL · Node.js · Python · PHP · C#**
>
> ```bash cURL theme={"dark"}
> curl https://api.tabby.ai/api/v2/checkout \
> -H "Authorization: Bearer sk_test_..." \
> -H "Content-Type: application/json" \
> -d '{
> "payment": {
> "amount": "340.00",
> "currency": "AED",
> "buyer": { "name": "John Doe", "email": "otp.success@tabby.ai", "phone": "+971500000001" },
> "shipping_address": { "city": "Dubai", "address": "Sheikh Zayed Rd", "zip": "00000" },
> "order": {
> "reference_id": "order-1001",
> "items": [{ "title": "Sneakers", "quantity": 1, "unit_price": "340.00", "category": "Shoes" }]
> },
> "buyer_history": { "registered_since": "2024-03-01T00:00:00Z", "loyalty_level": 0 },
> "order_history": []
> },
> "lang": "en",
> "merchant_code": "your_merchant_code",
> "merchant_urls": {
> "success": "https://your-store.com/tabby/success",
> "cancel": "https://your-store.com/tabby/cancel",
> "failure": "https://your-store.com/tabby/failure"
> }
> }'
> ```
>
> ```javascript Node.js theme={"dark"}
> const res = await fetch('https://api.tabby.ai/api/v2/checkout', {
> method: 'POST',
> headers: {
> Authorization: `Bearer ${process.env.TABBY_SECRET_KEY}`,
> 'Content-Type': 'application/json',
> },
> body: JSON.stringify(payload), // the JSON from the cURL tab
> });
> const session = await res.json();
>
> if (session.status === 'created') {
> const webUrl = session.configuration.available_products.installments[0]?.web_url;
> if (webUrl) return redirect(webUrl); // save session.payment.id first
> }
> // status "rejected" (or missing web_url): show the rejection message, offer another method
> ```
>
> ```python Python theme={"dark"}
> import os, requests
>
> res = requests.post(
> "https://api.tabby.ai/api/v2/checkout",
> headers={"Authorization": f"Bearer {os.environ['TABBY_SECRET_KEY']}"},
> json=payload, # the JSON from the cURL tab
> )
> session = res.json()
>
> if session["status"] == "created":
> installments = session["configuration"]["available_products"].get("installments") or []
> web_url = installments[0].get("web_url") if installments else None
> if web_url:
> return redirect(web_url) # save session["payment"]["id"] first
> # status "rejected" (or missing web_url): show the rejection message
> ```
>
> ```php PHP theme={"dark"}
> $ch = curl_init('https://api.tabby.ai/api/v2/checkout');
> curl_setopt_array($ch, [
> CURLOPT_POST => true,
> CURLOPT_RETURNTRANSFER => true,
> CURLOPT_HTTPHEADER => [
> 'Authorization: Bearer ' . getenv('TABBY_SECRET_KEY'),
> 'Content-Type: application/json',
> ],
> CURLOPT_POSTFIELDS => json_encode($payload), // the JSON from the cURL tab
> ]);
> $session = json_decode(curl_exec($ch), true);
>
> $webUrl = $session['configuration']['available_products']['installments'][0]['web_url'] ?? null;
> if ($session['status'] === 'created' && $webUrl) {
> header('Location: ' . $webUrl); // save $session['payment']['id'] first
> exit;
> }
> // status "rejected" (or missing web_url): show the rejection message
> ```
>
> ```csharp C# theme={"dark"}
> using var http = new HttpClient();
> http.DefaultRequestHeaders.Authorization =
> new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("TABBY_SECRET_KEY"));
>
> var res = await http.PostAsJsonAsync("https://api.tabby.ai/api/v2/checkout", payload); // the JSON from the cURL tab
> var session = await res.Content.ReadFromJsonAsync
();
>
> var status = session.GetProperty("status").GetString();
> var installments = session.GetProperty("configuration")
> .GetProperty("available_products").TryGetProperty("installments", out var arr) ? arr : default;
> if (status == "created" && installments.ValueKind == JsonValueKind.Array && installments.GetArrayLength() > 0)
> {
> var webUrl = installments[0].GetProperty("web_url").GetString(); // save payment.id first
> return Redirect(webUrl);
> }
> // status "rejected" (or missing web_url): show the rejection message
> ```
After the customer returns, verify the payment server-side and capture it — see [Payment Processing](/pay-in-4-custom-integration/payment-processing).
### Going Live
***
***
***
#### Production cutover checklist
Test-key configuration does **not** carry over to live keys. When switching to production, verify each of these:
* [ ] Swap `sk_test_...` → live `sk_...` on the backend and `pk_test_...` → live `pk_...` in snippets — never expose any `sk_` key client-side.
* [ ] **Re-register webhooks with the live key** — webhooks registered with a test key receive test payments only (see [Webhooks](/pay-in-4-custom-integration/webhooks)).
* [ ] Confirm all calls use the base URL matching the merchant's region ([Base URLs](/api-reference/overview#base-urls)).
* [ ] Place one real live order end-to-end: session → HPP → `AUTHORIZED` → capture → `closed` webhook received.
## How It Works
Here's what happens when a customer uses Tabby:
1. **Customer chooses Tabby at checkout**\
Your site checks if the customer is eligible using Tabby's API (background check based on purchase amount and customer details).
2. **Customer completes purchase**\
If eligible, customer selects Tabby, clicks "Place order", and is redirected to Tabby's secure payment page to complete verification.
3. **You get paid, customer pays in installments**\
Tabby authorizes the payment immediately. You capture the full amount and fulfill the order. The customer pays Tabby in interest-free installments.
> [!NOTE]
>
> For detailed technical implementation, see the [Checkout Flow Guide](/pay-in-4-custom-integration/checkout-flow).
## Complete Integration Flow
This diagram shows the complete end-to-end integration flow including eligibility checks, session creation, payment processing, and all possible outcomes:
```mermaid theme={"dark"}
sequenceDiagram
autonumber
participant Customer
participant Merchant Site
participant Merchant Backend
participant Tabby Checkout
participant Tabby API
Customer ->>+ Merchant Site: Opens Checkout page
Merchant Site ->>+ Merchant Backend: Check customer eligibility with Tabby
Merchant Backend ->>+ Tabby API: POST /api/v2/checkout
{ amount, currency, buyer.phone, buyer.email, merchant_code }
Tabby API -->>- Merchant Backend: Response
{"status" of session}
alt "status" of session == "created"
Merchant Backend -->> Merchant Site: Customer is eligible
Merchant Site -->> Customer: Show Tabby on Checkout
Note right of Customer: Customer can select Tabby payment
Customer ->>+ Merchant Site: Selects Tabby & clicks Place Order
Merchant Site ->>+ Merchant Backend: Create Tabby payment session
Note over Merchant Backend,Tabby API: New session is created (not eligibility check)
Merchant Backend ->>+ Tabby API: POST /api/v2/checkout
{ all required attributes }
Tabby API -->>- Merchant Backend: Response
{"payment.id", "web_url"}
Merchant Backend ->>+ Tabby Checkout: Redirect to Tabby Checkout
loop Tabby Checkout steps
Tabby Checkout -->> Customer: Guide through payment steps
end
else "status" of session == "rejected"
Merchant Backend -->> Merchant Site: Customer is not eligible
Merchant Site -->> Customer: Hide Tabby on Checkout
end
alt Customer is redirected back to Merchant Site
Tabby Checkout ->> Merchant Site: Redirect via success/cancel/failure url
Merchant Site ->> Customer: Show success/cancel/failure screen and message
Note right of Customer: If payment is unsuccessful, customer can retry
or select a different payment method
Merchant Backend ->>+ Tabby API: GET /api/v2/payments/{payment.id}
Tabby API -->>- Merchant Backend: { "status" of the payment }
else Customer is not redirected
Note over Tabby API,Merchant Backend: Tabby sends payment status
via webhook or merchant checks it via API
Tabby API -->>+ Merchant Backend: POST webhook
{ "id" of the payment, "status" of the payment }
Merchant Backend ->>+ Tabby API: GET /api/v2/payments/{payment.id}
Tabby API -->>- Merchant Backend: { "status" of the payment }
end
Note over Merchant Backend: Always verify payment status via Tabby API
Do not rely on redirect URL or query params alone
alt payment.status == "AUTHORIZED"
Merchant Backend ->>+ Merchant Site: Create order in backend
Merchant Backend -->> Tabby API: POST /api/v2/payments/{payment.id}/captures
{ amount, reference_id}
else payment.status == "CLOSED"
Merchant Backend ->>+ Merchant Site: Create order in backend
(payment already captured — no capture call)
else payment.status == "REJECTED" or "EXPIRED"
Merchant Backend -->> Merchant Site: Payment failed/cancelled
end
```
## Next Steps
Beyond the flow covered above:
* [Payment statuses reference](/pay-in-4-custom-integration/payment-statuses)
* [Refunds and cancellations](/api-reference/payments/refund-a-payment)
* [Disputes handling](/pay-in-4-custom-integration/disputes)
* [FAQ](/introduction/faq) for common implementation questions
* [Marketing toolkit](/marketing/toolkit) with guidelines and assets for every channel
## Need Help?
**Integration support:**\
Contact your assigned Business Manager or Integrations Team via your integration email thread.
**Technical or API questions:**\
Email `partner@tabby.ai` / `partner@tabby.sa` or use Partner Support in Tabby Business App.
**Direct your customers to:**\
Customer Support in Tabby App or `help@tabby.ai` / `help@tabby.sa`.
# Payment webhooks
Source: https://docs.tabby.sa/pay-in-4-custom-integration/webhooks
Get notified about payment status changes: registration, payload, supported events, delivery order, and retries.
[Tabby Webhooks](/api-reference/webhooks) are HTTPS callbacks that notify you about payment-related and token-related events. You register a URL once, and Tabby sends a POST request to it whenever an event related to your account occurs — even when the customer never returns to your site. This makes webhooks the most reliable way to [catch authorized payments](/pay-in-4-custom-integration/payment-processing#dont-miss-authorized-payments).
## How They Work
**1. Register an endpoint**
[Register a webhook](/api-reference/webhooks/register-a-webhook) for each `merchant_code` + secret key pair — the merchant code is passed in the **`X-Merchant-Code` header** (required):
```bash theme={"dark"}
curl -X POST https://api.tabby.ai/api/v1/webhooks \
-H "Authorization: Bearer sk_test_..." \
-H "X-Merchant-Code: your_merchant_code" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-store.com/tabby/webhook",
"header": { "title": "X-Auth-Key", "value": "your_random_signing_secret" }
}'
```
The environment is determined by the key you register with: a production key (`sk_...`) registers webhooks for production payments, a test key (`sk_test_...`) — for test payments. Each pair can have up to **4 webhooks**. The optional `header` signs the requests so you can verify their authenticity.
> [!NOTE]
>
> **Webhook registration is self-service.** `POST /api/v1/webhooks` is a public endpoint — you don't need to ask Tabby to register, update or remove webhooks for you. Call `https://api.tabby.ai/api/v1/webhooks` with your secret key and the `X-Merchant-Code` header, as shown above; KSA merchants use `https://api.tabby.sa/api/v1/webhooks`. All webhook endpoints are listed in the [API reference](/api-reference/webhooks/register-a-webhook).
**2. Receive notifications**
Tabby sends a POST request to your URL whenever the [payment status changes](/pay-in-4-custom-integration/webhooks#supported-events).
**3. Acknowledge with 200**
Respond with a `200` HTTP status code to confirm the reception, and check the auth header to verify the request. Any other response (or no response) counts as a delivery error and triggers [retries](/pay-in-4-custom-integration/webhooks#retry-attempts).
## Payload
Webhooks are POST requests with a JSON body:
```JSON theme={"dark"}
{
"id": "string",
"created_at": "2021-09-14T13:08:54Z",
"expires_at": "2022-09-14T13:08:54Z",
"closed_at": "2021-09-14T13:09:45Z",
"status": "closed",
"is_test": false,
"is_expired": false,
"amount": "100",
"currency": "SAR",
"order": {
"reference_id": "string"
},
"captures": [
{
"id": "string",
"amount": "100",
"created_at": "2021-09-14T13:09:45Z",
"reference_id": "string"
}
],
"refunds": [
{
"id": "string",
"amount": "100",
"created_at": "2021-09-14T14:14:02Z",
"reference_id": "string",
"reason": "string"
}
],
"meta": {
"order_id": null,
"customer": null
},
"token": "string"
}
```
> [!TIP]
>
> Webhook payloads use lowercase statuses (`"authorized"`), while the [Retrieve Request](/api-reference/payments/retrieve-a-payment) returns uppercase (`"AUTHORIZED"`) — this is expected. See [Payment Statuses](/pay-in-4-custom-integration/payment-statuses#statuses-in-api-responses-vs-webhooks).
## Supported Events
The payload content depends on the event:
| Event | Webhook payment status | Payload update |
| - | :-: | - |
| Authorize | authorized | "status": "authorized" |
| Capture | authorized | capture info is added to captures.\[] array |
| Close | closed | "status": "closed" and "closed\_at" updated |
| Reject | rejected | "status": "rejected" |
| Expire (Optional) | expired | "status": "expired", "expired\_at" and "is\_expired" updated |
| Refund | closed | refund info is added to refunds.\[] array |
| Update | the same as before the Update Request | order.reference\_id updated |
The "expire" event is optional — ask the Tabby team to enable it for your store if you want notifications when a payment is cancelled by the customer or expires.
## A Typical Payment
For a regular successful order you will receive three notifications:
1. **Payment authorized** — the payload status is `authorized`. Check the order and process it in your OMS if it wasn't processed yet, then send the [Capture Request](/api-reference/payments/capture-a-payment).
2. **Payment captured** — the payload status is still `authorized`, with your capture added to the `captures` array. No action is required.
3. **Payment closed** — the payload status is `closed`: the payment is completed and confirmed from both sides. No action is required.
> [!NOTE]
>
> Looking for notifications about disputes raised on your payments? See [Dispute webhooks](/pay-in-4-custom-integration/dispute-webhooks) — a separate webhook family with its own endpoints under `/api/v1/dispute-webhooks`, registered with a live secret key.
## Best Practices
* **Respond fast.** Acknowledge the webhook with `200` right away and process it asynchronously, instead of holding the response until processing is done.
* **Expect disorder and duplicates.** Webhooks are asynchronous: the delivery order is not guaranteed and the same event may occasionally arrive twice — ignore a notification you have already processed, and see [Handling Edge Cases](/pay-in-4-custom-integration/webhooks#handling-edge-cases) below.
* **Filter events.** You receive notifications for all payment events — process only the ones you need.
* **Allowlist Tabby server IPs:**
```
34.166.36.90
34.166.35.211
34.166.34.222
34.166.37.207
34.93.76.191
34.166.128.182
34.166.170.3
34.166.249.7
```
To test and debug webhooks, use a tool like [Webhook.site](https://webhook.site/) to inspect the payload and headers Tabby sends to your endpoint.
## Handling Edge Cases
These three situations occur in every production integration. Handling them wrong is the most common cause of "lost" payments and duplicate captures.
### The webhook can arrive before your own order is saved
Tabby sends the `authorized` webhook as soon as the customer completes the payment — which can be **before your checkout code has committed the order to your database**. If your handler looks up the order, finds nothing, and still acknowledges with `200`, that event is gone for good and the payment sits unprocessed.
**Do this instead:** when the webhook references a payment you cannot match yet, respond with a non-`200` status (e.g. `404`). Tabby treats it as a delivery error and [retries](/pay-in-4-custom-integration/webhooks#retry-attempts) — by the next attempt your transaction has landed and the event processes normally. Acknowledge with `200` only when you either processed the event or deliberately chose to ignore it. It also pays to store the raw event before processing — an audit log of received webhooks makes every "where did the payment go" investigation trivial.
### Statuses only move forward
A `closed` event can arrive before the `authorized` one. Treat payment status as a one-way street — `authorized` → `closed` — and never downgrade: if your record already says `closed`, ignore a late `authorized` event instead of overwriting.
### A capture confirmation is not a request to capture
The second notification in [A Typical Payment](/pay-in-4-custom-integration/webhooks#a-typical-payment) — `authorized` with your capture in the `captures` array — confirms your own capture. Before triggering a capture from a webhook, check that `captures` is empty; if it isn't, the payment is already being settled and no action is needed.
## Retry Attempts
A webhook request times out after **1 minute**. If it times out or gets any response other than `200`, Tabby resends it up to **4 more times** with an exponential interval between attempts (1–4 minutes). Retries don't block other notifications — Tabby keeps sending webhooks for other payment events as they occur.
# Shopify Product Catalogue
Source: https://docs.tabby.sa/product-catalogue/shopify-product-catalogue
This page describes the installation process for Tabby Catalogue in Shopify.
* In Tabby Merchant Dashboard go to the “Marketing” tab;
* Сheck the status of your store. It should be published to start the item uploading process;
* Once the store is published, click the “Upload products” button and choose Shopify;
Shopify Product Catalogue in Dashboard
* Wait for the redirection here to the documentation and [installation link](https://apps.shopify.com/tabby-product-feed);
* In Shopify App Store click "Install" and choose a necessary store from the list of suggested stores;
* You will be redirected to your Shopify store's admin panel and requested to install the application with the following permissions:
App Permissions
* Click "Connect" and in the appearing pop-up enter the secret key of your store (you can find it in the Tabby Payment application or in the Merchant Dashboard "Integration" tab), as the app is not connected by default.
Connection Step
Key Installation
* Once you connect the application with the secret key, you will observe the "Publish" button;
Publishing Step
* After publishing, you are ready to use Tabby Catalogue, the synchronization starts immediately.
# Zid Product Catalogue
Source: https://docs.tabby.sa/product-catalogue/zid-product-catalogue
Here you will find the instruction how to install Tabby Catalogue in Zid.
* In Tabby Merchant Dashboard go to the “Marketing” tab;
* Сheck the status of your store. It should be published to start the item uploading process;
* Once the store is published, click the “Upload products” button and choose Zid;
* You are redirected here to the instructions and the Zid App Market installation links:
* **KSA market** - [Tabby Catalogue (KSA)](https://apps.zid.sa/en/application/3981);
* **UAE market** - [Tabby Catalogue (UAE/Kuwait)](https://apps.zid.sa/en/application/6343).
Merchants operating in more than one of these markets should install both apps - each app handles its own region.
* In Zid App Market install and activate the relevant Tabby Catalogue app(s);
* Upon activation you will be redirected back to the Tabby Merchant Dashboard to undergo the OAuth process. The KSA app connects to [merchant.tabby.sa](https://merchant.tabby.sa) and the UAE app connects to [merchant.tabby.ai](https://merchant.tabby.ai);
Make sure your store is published before uploading the items
Tabby Catalogue in Zid App Market
Activation Page
# Postman API Collection
Source: https://docs.tabby.sa/testing-guidelines/postman-api-collections
Download the Postman collection, import it into Postman, and set the Collection Variables:
* `base_url` — `https://api.tabby.ai` (UAE) or `https://api.tabby.sa` (KSA). See [Base URLs](/api-reference/overview#base-urls).
* `secret_key` — your Tabby Secret API Key
* `merchant_code` — your merchant code
* `currency` — `AED` or `SAR`
> Tabby API Collection
>
> [Open](/custom-api.json)
# Testing Credentials
Source: https://docs.tabby.sa/testing-guidelines/testing-credentials
* Testing is **required for every integration that receives test keys** (`sk_test_...` / `pk_test_...`).
* Other integrations are not issued test keys — they launch directly with the Live Keys, and no testing is required.
> [!NOTE]
>
> All test credentials work with **test keys only** (`sk_test_...` / `pk_test_...`) — the success flow cannot be completed on live keys. The OTP is always `8888`.
| Credentials | Email | Phone (UAE / KSA) |
| :- | :- | :- |
| **Success** | [otp.success@tabby.ai](mailto:otp.success@tabby.ai) | +971500000001 / +966500000001 |
| **Pre-scoring reject** | [otp.success@tabby.ai](mailto:otp.success@tabby.ai) | +971500000002 / +966500000002 |
| **HPP rejection** | [otp.rejected@tabby.ai](mailto:otp.rejected@tabby.ai) | +971500000001 / +966500000001 |
## 1. Payment Success
**Testing Steps:**
1. Add an item to your shopping cart and proceed to checkout.
2. Fill in all the required fields at checkout with the **Success** credentials.
3. Choose Tabby as the payment method and click "Place order."
4. Complete the payment using `OTP:8888` on Tabby HPP and redirect to the store's success page.
5. Verify that the capture of the successful payment occurred - check for status `CAPTURED` on the Merchant Dashboard or Payment status `AUTHORIZED` and `CLOSED` via Retrieve Payment API.
**Expected Results:**
1. Store checkout opens.
2. Tabby payment method is available on the checkout page (background pre-scoring passed successfully).
3. Tabby Hosted Payment Page opens.
4. The success Tabby screen appears and redirects to the `Success URL`; the store's 'Thank you' page appears.
5. Order is captured:
* Payment Status is `CLOSED`;
* captured amount is present in the `"captures":[]` array of objects.
## 2. Background Pre-scoring Reject
**Testing Steps:**
1. Add an item to your shopping cart and proceed to checkout.
2. Fill in all the required fields at checkout with the **Pre-scoring reject** credentials.
3. Attempt to choose Tabby as the payment method.
**Expected Results:**
1. Store checkout opens.
2. Tabby payment method is hidden or marked as unavailable with the message:
* English: Sorry, Tabby is unable to approve this purchase, please use an alternative payment method for your order.
* Arabic: نأسف، تابي غير قادرة على الموافقة على هذه العملية. الرجاء استخدام طريقة دفع أخرى.
3. Tabby is hidden from the payment methods list or marked as unavailable.
## 3. Payment Cancellation
**Testing Steps:**
1. Add an item to your shopping cart and proceed to checkout.
2. Fill in all the required fields at checkout with the **Success** credentials.
3. Choose Tabby as the payment method and click "Place order."
4. Click on the 'Back to Store' button (Desktop) or the left corner cross button (Mobile), and confirm cancellation.
**Expected Results:**
1. Store checkout opens.
2. Tabby payment method is available on the checkout page (background pre-scoring passed successfully).
3. Tabby Hosted Payment Page opens.
4. Redirect to the `Cancel URL` - store checkout or cart page. Verify that the cart is not emptied, and a text message with a cancellation reason is shown:
* English: You aborted the payment. Please retry or choose another payment method.
* Arabic: لقد ألغيت الدفعة. فضلاً حاول مجددًا أو اختر طريقة دفع أخرى.
## 4. Payment Failure
**Testing Steps:**
1. Add an item to your shopping cart and proceed to checkout.
2. Fill in all the required fields at checkout with the **HPP rejection** credentials.
3. Choose Tabby as the payment method and click "Place order."
4. Finish the payment using `OTP:8888` in Tabby HPP.
5. Confirm returning to the store by clicking the 'Back to store' button.
6. Verify the payment status via Retrieve Payment API.
**Expected Results:**
1. Store checkout opens.
2. Tabby payment method is available on the checkout page (background pre-scoring passed successfully).
3. Tabby Hosted Payment Page opens.
4. The rejection screen with the message 'We can’t approve this purchase' appears.
5. Redirect to the `Failure URL` - store checkout or cart page. Verify that the cart is not emptied, and a text message with a failure reason is shown:
* English: Sorry, Tabby is unable to approve this purchase, please use an alternative payment method for your order.
* Arabic: نأسف، تابي غير قادرة على الموافقة على هذه العملية. الرجاء استخدام طريقة دفع أخرى.
6. Tabby payment method is still available for selection among payment methods on Checkout.
7. No order appears in the Merchant Dashboard (unsuccessful orders are not displayed in the Dashboard), Payment Status `REJECTED`.
## 5. Corner Case
**Testing Steps:**
1. Add an item to your shopping cart and proceed to checkout.
2. Fill in all the required fields at checkout with the **Success** credentials.
3. Choose Tabby as the payment method and click "Place order."
4. Finish the payment using `OTP:8888` in Tabby HPP.
5. Once you see the Success Tabby screen (with the tick), **close the browser tab before the redirection.**
6. Verify that the **capture** of the successful payment occurred - check **order status `CAPTURED` on the Merchant Dashboard** or Payment status via Retrieve Payment API is `CLOSED`. Ensure the order is marked **successful** on your side.
**Expected Results:**
1. Store checkout opens.
2. Tabby payment method is available on the checkout page (background pre-scoring passed successfully).
3. Tabby Hosted Payment Page opens.
4. There is no redirection to the Success page as the browser tab is closed before redirection.
5. Payment Status changes to `AUTHORIZED`, then after capture is triggered, it changes to `CLOSED` with a captured amount in the `"captures":[]` array of objects, triggered by the Webhook notifications or Cron Job.\
Retrieve payment status returned status `AUTHORIZED` **before capture** and `CLOSED` **after capture**.
> [!NOTE]
>
> If you encounter any non-captured payments (with `AUTHORIZED` status on Payments API or `NEW` status on Merchant Dashboard), you can initiate a **Manual Capture** or **Cancel** on the Merchant Dashboard, or **Capture** or **Close** Payment API Request.
## 6. Payment Refund via API
If you are not using the Tabby dashboard.
**Testing Steps:**
1. Choose an order on your OMS and perform a refund.
2. Check the order on the Tabby Merchant Dashboard and Payment status via Retrieve request.
3. Retry the exact same refund request (same `reference_id`) — then perform a genuinely new refund with a **new** `reference_id`.
**Expected Results:**
1. The refund is reflected on the OMS without any API errors.
2. The order has Refunded/Partially Refunded status in the Tabby Merchant Dashboard, and the Payment status is `CLOSED` with the refunded amount in the `refunds":[]` array of objects.
3. The retry with the same `reference_id` returns the **first refund again** (idempotent replay — no second refund is created; don't mistake it for an accepted new refund). The refund with a new `reference_id` creates a second refund, and the cumulative total cannot exceed the captured amount.
## 7. Tabby Checkout Focus Change (Mobile Apps)
**Precondition:** Tabby Checkout is opened using the **Success** credentials at the OTP step.
**Testing Steps:**
1. At the OTP step on Tabby Checkout opened in the Webview/In-App browser, minimize the app by navigating to the home screen.
2. Wait a few seconds and then return to the app.
**Expected Results:**
1. The app correctly recovers the Tabby checkout screen at the same step. No crashes or hangs of the app after the return.
2. No App or Webview issues appear.