# Create a session
Source: https://docs.tabby.ai/api-reference/checkout/create-a-session

post /api/v2/checkout
Creates a Checkout session. Creates Session and Payment, returns Pre-Scoring result (status), ids of Payment and Session.



# Session creation payload model
Source: https://docs.tabby.ai/api-reference/checkout/session-payload-model



## Request

The payload example for a session creation request with all required fields for a direct API custom integration. Fields marked `// required` are mandatory for the full checkout session — the <a href="/pay-in-4-custom-integration/checkout-flow#background-pre-scoring-check">background pre-scoring call</a> accepts a minimal subset. Fields marked `// recommended` are optional, but improve scoring accuracy and approval rates — send them whenever you have the data. The `//` comments are annotations, not part of the payload — strip them before sending.

```jsonc theme={"dark"}
{
  "payment": { // required
    "amount": "100", // required. Up to 2 decimals for UAE and KSA, e.g. 100.00
    "currency": "AED", // required. Use the ISO 4217 standard for defining currencies
    "description": "test payload",
    "buyer": { // required
      "name": "John Doe", // required. Customer's full name
      "email": "jsmith@example.com", //required. Customer's email address
      "phone": "500000001", //required. Customer's phone number
      "dob": "2000-01-20"
    },
    "shipping_address": { // required
      "city": "Dubai", // required. Name of city, municipality, or village
      "address": "Dubai", // required. Building name, apartment number
      "zip": "1111" // required. Postal code
    },
    "order": { // required
      "reference_id": "1001", // required. Merchant-assigned order number.
      "updated_at": "2023-11-07T05:31:56Z",
      "tax_amount": "0.00",
      "shipping_amount": "0.00",
      "discount_amount": "0.00",
      "items": [ // required
        {
          "reference_id": "SKU123",
          "title": "Name of the product", // required. Name of the product.
          "description": "Description of the product",
          "quantity": 1, // required. Quantity of the product ordered. Should be >= 1
          "unit_price": "0.00", // required. Price per unit of the product. Should be positive or zero.
          "discount_amount": "0.00",
          "image_url": "https://example.com/",
          "product_url": "https://example.com/",
          "gender": "Kids",
          "category": "Clothes", // required. Name of high-level category (Clothes, Electronics,etc.)
          "color": "white",
          "product_material": "cotton",
          "size_type": "EU",
          "size": "M",
          "brand": "Name of the Brand",
          "is_refundable": true,
          "barcode": "12345678",
          "ppn": "MNXT2ZM/A",
          "seller": "Name of the Seller"
        }
      ]
    },
    "buyer_history": { // required
      "registered_since": "2023-11-07T05:31:56Z", // required. Date and time the customer got registred with you
      "loyalty_level": 0, // recommended. Customer's loyalty level within your store
      "wishlist_count": 0,
      "is_social_networks_connected": true,
      "is_phone_number_verified": true,
      "is_email_verified": true
    },
    "order_history": [ // recommended. 5-10 previous orders
      {
        "purchased_at": "2023-11-07T05:31:56Z", // recommended. Date and time the order was placed
        "amount": "100", // recommended. Up to 2 decimals for UAE and KSA, e.g. 100.00
        "payment_method": "card",
        "status": "new", // recommended. Status of the order
        "buyer": { // recommended
          "name": "John Doe", // recommended. Customer's full name
          "email": "jsmith@example.com", // recommended. Customer's email address
          "phone": "500000001", // recommended. Customer's phone number
          "dob": "2000-01-20"
        },
        "shipping_address": { // recommended
          "city": "Dubai", // recommended. Name of city, municipality, or village
          "address": "Dubai", // recommended. Building name, apartment number
          "zip": "1111" // recommended. Postal code
        },
        "items": [
          {
            "reference_id": "SKU123",
            "title": "Name of the product",
            "description": "Description of the product",
            "quantity": 1,
            "unit_price": "0.00",
            "discount_amount": "0.00",
            "image_url": "https://example.com/",
            "product_url": "https://example.com/",
            "gender": "Kids",
            "category": "Clothes",
            "color": "white",
            "product_material": "cotton",
            "size_type": "EU",
            "size": "M",
            "brand": "Name of the Brand",
            "is_refundable": true,
            "barcode": "12345678",
            "ppn": "MNXT2ZM/A",
            "seller": "Name of the Seller"
          }
        ]
      }
    ],
    "meta": {
      "customer": "#customer-id",
      "order_id": "#1234"
    },
    "attachment": {
      "body": "{\"flight_reservation_details\": {\"pnr\": \"TR9088999\",\"itinerary\": [...],\"insurance\": [...],\"passengers\": [...],\"affiliate_name\": \"some affiliate\"}}",
      "content_type": "application/vnd.tabby.v1+json"
    }
  },
  "lang": "en", // required. Session language
  "merchant_code": "code provided to you from Tabby side", // required. Merchant's branch code
  "merchant_urls": {
    "success": "https://your-store/success",
    "cancel": "https://your-store/cancel",
    "failure": "https://your-store/failure"
  },
  "token": null
}
```

## Response

A successful session creation returns `200 OK` with this structure (the `payment` object echoes your request payload back, trimmed here for brevity):

```jsonc theme={"dark"}
{
  "id": "e5f9d6c8-...",                  // session id
  "status": "created",                    // "created" | "rejected" | "expired"
  "payment": {
    "id": "01a04380-64b8-8432-a20f-904a48584390",  // payment id — SAVE IT: used to verify, capture and refund
    "created_at": "2026-01-20T09:12:00Z",
    "status": "CREATED",
    "is_test": true,
    "amount": "100.00",
    "currency": "AED"
    // ...the rest of your request payload echoed back
  },
  "configuration": {
    "available_products": {
      "installments": [
        {
          "web_url": "https://checkout.tabby.ai/?sessionId=...&apiKey=pk_test_...&product=installments",
          "qr_code": "https://api.tabby.ai/api/v2/checkout/.../hpp_link_qr?product_type=installments"
        }
      ]
    },
    "products": {
      "installments": {
        "type": "installments",
        "is_available": true,
        "rejection_reason": null
      }
    }
  },
  "merchant_urls": {
    "success": "https://your-store/success",
    "cancel": "https://your-store/cancel",
    "failure": "https://your-store/failure"
  },
  "merchant": {
    "name": "Your store name"
  }
}
```

What to read from it:

* **`status`** — `created` means the customer can pay; `rejected` means hide Tabby or show the <a href="/pay-in-4-custom-integration/checkout-flow#possible-rejection_reason-values">rejection message</a>.
* **`payment.id`** — save it; all later calls (<a href="/api-reference/payments/retrieve-a-payment">verify</a>, capture, refund) address the payment by this id.
* **`configuration.available_products.installments[0].web_url`** — the Hosted Payment Page link to redirect the customer to. `installments` is an **array**: take the first element. Always validate `web_url` is present before redirecting.
* On rejection (`status: "rejected"`), the reason is in `configuration.products.installments.rejection_reason` (`null` in `created` responses), and `configuration.available_products` comes back **empty** — no `web_url` to redirect to.


# Register a dispute webhook
Source: https://docs.tabby.ai/api-reference/dispute-webhooks/register-a-dispute-webhook

post /api/v1/dispute-webhooks
Registers a dispute webhook for the merchant identified by the secret key and the
`X-Merchant-Code` header. Disputes have no test mode: authorize with a production
secret key (`sk_...`) — a request signed with a test key (`sk_test_...`) is rejected
with `403`. Each `merchant_code` can have up to 4 dispute webhooks; the limit is
separate from payment webhooks. The `url` is normalised before it is stored
(lower-case scheme and host, default port and trailing slash removed) and must be
unique per merchant. `header.value` is a secret: it is accepted in full and returned
masked in every response, including this one — `****` followed by the last 4 characters
for values longer than 8 characters, `****` alone for shorter values.


<Note>
  This is a public, self-service endpoint. Call `https://api.tabby.ai/api/v1/dispute-webhooks` (`https://api.tabby.sa/api/v1/dispute-webhooks` for KSA) with your **live** secret key and the `X-Merchant-Code` header. How dispute webhooks work, payload and statuses: <a href="/pay-in-4-custom-integration/dispute-webhooks">Dispute webhooks</a>.
</Note>


# Remove a dispute webhook
Source: https://docs.tabby.ai/api-reference/dispute-webhooks/remove-a-dispute-webhook

delete /api/v1/dispute-webhooks/{id}
Removes the specified dispute webhook.



# Retrieve a dispute webhook
Source: https://docs.tabby.ai/api-reference/dispute-webhooks/retrieve-a-dispute-webhook

get /api/v1/dispute-webhooks/{id}
Retrieves the specified dispute webhook. `header.value` is returned masked.



# Retrieve all dispute webhooks
Source: https://docs.tabby.ai/api-reference/dispute-webhooks/retrieve-all-dispute-webhooks

get /api/v1/dispute-webhooks
Retrieves all dispute webhooks registered for the merchant. Returns an empty array when none are registered.



# Update a dispute webhook
Source: https://docs.tabby.ai/api-reference/dispute-webhooks/update-a-dispute-webhook

put /api/v1/dispute-webhooks/{id}
Updates the specified dispute webhook. The request **replaces the whole object**:
send both `url` and `header`; omitting `header` removes it. The same URL rules
as on registration apply (normalised, unique per merchant).




# Approve disputes
Source: https://docs.tabby.ai/api-reference/disputes/approve-disputes

post /api/v1/disputes/approve
Approve disputes (refund money to the customer). Only 20 disputes can be approved within a single request.



# Challenge disputes
Source: https://docs.tabby.ai/api-reference/disputes/challenge-disputes

post /api/v1/disputes/challenge
Challenge disputes (request Tabby support to take a look at the case). Only 20 disputes can be challenged within a single request. Only disputes with status 'new' might be challenged.



# Get dispute by id
Source: https://docs.tabby.ai/api-reference/disputes/get-dispute-by-id

get /api/v1/disputes/{disputeId}
Returns detailed information about dispute.



# Get disputes list
Source: https://docs.tabby.ai/api-reference/disputes/get-disputes-list

get /api/v1/disputes
Returns list of 100 recently created disputes.



# Provide evidence for a dispute
Source: https://docs.tabby.ai/api-reference/disputes/provide-evidence

post /api/v1/disputes/{disputeId}/provide-evidence
Provide evidence (text and/or attachments) for a dispute. Used by the merchant to submit proof in response to an evidence request.



# Upload attachment
Source: https://docs.tabby.ai/api-reference/disputes/upload-attachment

post /api/v1/disputes/attachments/upload
Upload an attachment. Attachment must be in PNG, JPEG or PDF format and can be up to 5 megabytes in size. Files larger than 5 MB are rejected.



# API Reference Documentation
Source: https://docs.tabby.ai/api-reference/overview



In this part of the documentation all the needed API calls for Tabby Integration can be found and tested:

* Checkout - it is a whole process of customer data collection and payment authorization.
* Payments - the core of Tabby is a payments flow enabling you to handle payments at your webstore.
* Webhooks - serve to ensure a seamless payment verification flow.
* Dispute webhooks - notify you when a dispute is opened on your payment or changes its status.
* Disputes - help merchants resolve issues with customers orders more efficiently.

## Base URLs

Tabby uses region-specific domains. Choose the base URL based on the merchant's operating country:

| Region | API Base URL | Checkout / Promo | Merchant Dashboard |
| - | - | - | - |
| **UAE** | `https://api.tabby.ai` | `checkout.tabby.ai` | `merchant.tabby.ai` |
| **KSA** | `https://api.tabby.sa` | `checkout.tabby.sa` | `merchant.tabby.sa` |

All API paths and payloads are identical across both domains. Tabby identifies the environment (test or live) based on the API keys used.

<Warning>
  **Use the base URL that matches the merchant's region for every call.** Many existing integrations call `api.tabby.ai` for all regions and rely on Tabby-side request routing — but not every endpoint is routed (e.g. payments retrieval and disputes), and cross-region calls can return `404`/`403`. New integrations must pin all calls — session creation, payment retrieval, captures, refunds, webhooks, dispute webhooks, disputes — to the regional base URL.
</Warning>

| Contact | UAE | KSA |
| - | - | - |
| **Partner Support** | `partner@tabby.ai` | `partner@tabby.sa` |
| **Customer Support** | `help@tabby.ai` | `help@tabby.sa` |

## OpenAPI Specification

To access and download the raw OpenAPI specification file kindly use this: [openapi.yaml](https://docs.tabby.ai/openapi.yaml).

You can also view this API specification using [ReDoc](https://redocly.github.io/redoc/?url=https://docs.tabby.ai/openapi.yaml), the same is present below:

<iframe title="Tabby API Swagger UI" />

## Quick Links to Documentation

* [Direct API Integration Guide](/pay-in-4-custom-integration/quick-start)
* [Testing Credentials](/testing-guidelines/testing-credentials)
* [Postman API Collection](/testing-guidelines/postman-api-collections)


# Capture a payment
Source: https://docs.tabby.ai/api-reference/payments/capture-a-payment

post /api/v2/payments/{id}/captures
Send a Capture requests for Authorized payments only. If you capture the full payment amount, the payment will be automatically closed with full capture. If you capture partial amount, the payment will remain Authorized until the rest of the amount is captured or Close request sent.



# Close a payment
Source: https://docs.tabby.ai/api-reference/payments/close-a-payment

post /api/v2/payments/{id}/close
Closed is the final status of the payment. Your payment is going to be closed automatically if you capture the full amount of the payment. If an order is fully cancelled, please close the payment without capturing it - the customer will be refunded for all paid amount. If only a part of the order is delivered, please capture this part and close the payment – it will mean that another part of the order is not going to be delivered to the customer.



# List of all payments
Source: https://docs.tabby.ai/api-reference/payments/list-of-all-payments

get /api/v2/payments
Returns a list of success payments (`AUTHORIZED` or `CLOSED`) you’ve previously created. The payments are returned in sorted order, with the most recent payments appearing first. Each entry in the array is a separate payments object, including the status, any captures and any refunds. If no more payments are available, the resulting array will be empty. Payments might be filtered by creation date.



# Refund a payment
Source: https://docs.tabby.ai/api-reference/payments/refund-a-payment

post /api/v2/payments/{id}/refunds
Send a full or partial refund amount request. You can only refund the payment that has Closed status. By default refunds reflect instantly, which means Tabby initiates a refund through payment gateway.



# Retrieve a payment
Source: https://docs.tabby.ai/api-reference/payments/retrieve-a-payment

get /api/v2/payments/{id}
Retrieves the specified payment. Returns the entire payment object, including the payment Status, Captures and Refunds objects.



# Update a payment
Source: https://docs.tabby.ai/api-reference/payments/update-a-payment

put /api/v2/payments/{id}
Updates the reference_id. You can only use this endpoint to update this 1 field. If you send other fields in the request, they will simply be ignored by tabby. The payment to be updated can have a status of AUTHORIZED or CLOSED.



# API Error Codes
Source: https://docs.tabby.ai/api-reference/response-codes

Errors returned by the Tabby API — status codes, response bodies, and how to handle each one.

Check the usual errors the Tabby API returns and what to do about each.

## How errors work

When a request fails, Tabby responds with a `4xx`/`5xx` HTTP status code and a JSON error body:

```json theme={"dark"}
{ "status": "error", "errorType": "bad_data", "error": "could not decode request" }
```

For field-level validation failures the body carries an `errors` array instead of a single `error` string:

```json theme={"dark"}
{
  "status": "error",
  "errorType": "bad_data",
  "errors": [
    { "field": "$.payment.currency", "code": "invalid_value", "message": "" }
  ]
}
```

* Branch your handling on the **HTTP status code** and **`errorType`**. Possible `errorType` values: `bad_data`, `not_authorized`, `no_permission`, `not_found`, `conflict`; a `500` carries `internal`.
* `error` is a human-readable English message to aid debugging — log it, but don't parse it and never show it to customers.
* On `500` or a network failure, retry per your retry policy; for [captures](#post-apiv2paymentsidcaptures) and [refunds](#post-apiv2paymentsidrefunds) always retry with the **same idempotency key** — your own unique `reference_id` in the request body, see [Idempotent requests](/pay-in-4-custom-integration/payment-processing#idempotent-requests) — so retries can't duplicate money movement.
* Use the base URL that matches the merchant's region: `api.tabby.ai` (UAE) or `api.tabby.sa` (KSA) — see [Base URLs](/api-reference/overview#base-urls). Calling the wrong region returns `403` (see below).
* A pre-scoring **rejection is not an error**: `POST /api/v2/checkout` returns `200 OK` with `status: "rejected"`. For handling and the customer-facing rejection messages, see [Show rejection](/pay-in-4-custom-integration/checkout-flow#possible-rejection_reason-values).

## Quick reference

| HTTP status | Error code (`errorType`) |
| - | - |
| 400 Bad Request | `bad_data` |
| 401 Unauthorized | `not_authorized` |
| 403 Forbidden | `no_permission` |
| 404 Not Found | `not_found` |
| 409 Conflict | `conflict` |
| 429 Too Many Requests | — (rate limit reached, see [Rate limit](/introduction/technical-requirements#rate-limit)) |
| 500 Internal Server Error | `internal` (Tabby-side error — retry, monitor the [status page](https://www.tabby-status.com/)) |

***

## `POST /api/v2/checkout`

Creates a checkout session. Authenticate with the **Secret Key**: `Authorization: Bearer {secret_key}`.

<AccordionGroup>
  <Accordion title="400 Bad Request — could not decode request">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "could not decode request" }
    ```

    The JSON is malformed or a parameter has the wrong type. Validate the payload against the [Session payload model](/api-reference/checkout/session-payload-model).
  </Accordion>

  <Accordion title="400 Bad Request — currency / merchant_code mismatch">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "could not create payment: only '{{}}' is supported, but got '{{}}'" }
    ```

    The `currency` in the payload does not match the country assigned to your `merchant_code` (e.g. a UAE `merchant_code` used with `SAR`). Use the correct currency for the country.
  </Accordion>

  <Accordion title="400 Bad Request — field validation failed">
    ```json theme={"dark"}
    {
      "status": "error",
      "errorType": "bad_data",
      "errors": [
        { "field": "$.payment.currency", "code": "invalid_value", "message": "" }
      ]
    }
    ```

    A field value is invalid — `field` points at the offending path. The same envelope covers unsupported `currency`, wrong formats, and similar per-field issues.
  </Accordion>

  <Accordion title="400 Bad Request — payment validation failed">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "could not create payment: should be positive" }
    ```

    Other validation failures on the payment object (amounts and quantities must be positive, etc.) use the same envelope with a human-readable `error`. Read the `error` field for the specific cause.
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_authorized", "error": "merchant is null" }
    ```

    Two possible causes:

    1. The `Authorization` header is missing or wrong — it must be sent as `Authorization: Bearer {secret_key}`.
    2. The `merchant_code` in the payload doesn't match what the API key is bound to. Check the `merchant_code` you're passing and use the correct one for the environment (live vs sandbox).
  </Accordion>

  <Accordion title="403 Forbidden — no permission">
    ```json theme={"dark"}
    { "status": "error", "errorType": "no_permission" }
    ```

    Two possible causes:

    1. You are passing the `token` parameter, but it is not enabled for your integration. Remove `token` from the payload.
    2. The request hit the wrong regional base URL — the body then also carries `"error": "merchant region does not match cluster region"`. Use the base URL that matches the merchant's region: `api.tabby.ai` (UAE) or `api.tabby.sa` (KSA).
  </Accordion>

  <Accordion title="404 Not Found">
    ```
    404 page not found
    ```

    The URL path is incorrect. Verify it against the [API reference](/api-reference/checkout/create-a-session). Unsupported HTTP methods also return `404`.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    ```json theme={"dark"}
    { "status": "error", "errorType": "internal", "error": "Internal Server Error" }
    ```

    Retry the request per your retry policy. If all requests keep returning `500`, contact the Tabby Integrations team and consider hiding Tabby temporarily. Follow [tabby-status.com](https://www.tabby-status.com/) for maintenance and incident updates.
  </Accordion>
</AccordionGroup>

***

## `GET /api/v2/payments/{id}`

Retrieves the current state of a payment. Successful responses and payment statuses are covered in [Payment statuses](/pay-in-4-custom-integration/payment-statuses).

<AccordionGroup>
  <Accordion title="400 Bad Request — invalid payment id">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "invalid payment id" }
    ```

    The `payment_id` is not a valid UUID. Fix the format.
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_authorized" }
    ```

    The `Authorization` header is missing or wrong. It must be sent as `Authorization: Bearer {secret_key}`.
  </Accordion>

  <Accordion title="404 Not Found — no such payment">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_found", "error": "no such payment" }
    ```

    No payment with this `payment_id` is visible to your API key — either the id is wrong, or the payment belongs to a different store / API key. Check the `payment_id` and that you query with the same key that created the session.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    ```json theme={"dark"}
    { "status": "error", "errorType": "internal", "error": "Internal Server Error" }
    ```

    Retry per your retry policy. If `500` persists, contact the Tabby Integrations team and check [tabby-status.com](https://www.tabby-status.com/).
  </Accordion>
</AccordionGroup>

***

## `GET /api/v2/payments`

Retrieves a list of payments filtered by query parameters. Errors use the same envelopes as `GET /api/v2/payments/{id}`:

* `400 Bad Request` (`bad_data`) — an invalid query-parameter value: `"error": "failed to decode request"`.
* `401 Unauthorized` (`not_authorized`) — missing/wrong `Authorization` header.
* `500 Internal Server Error` (`internal`) — retry per your retry policy.

***

## `PUT /api/v2/payments/{id}`

Updates a payment (e.g. `reference_id`). Errors use the same envelopes as the other Payments endpoints:

* `400 Bad Request` (`bad_data`) — malformed body: `"error": "failed to decode request"`.
* `401 Unauthorized` (`not_authorized`) — missing/wrong `Authorization` header.
* `404 Not Found` (`not_found`) — `"error": "no such payment"`: wrong `payment_id`, or a payment of a different store / API key.
* `500 Internal Server Error` (`internal`) — retry per your retry policy.

***

## `POST /api/v2/payments/{id}/captures`

Captures funds from an `AUTHORIZED` payment.

<Tip>
  Always send an idempotency key — your own unique `reference_id` in the request body (see [Idempotent requests](/pay-in-4-custom-integration/payment-processing#idempotent-requests)) — so that retries after a `500` or `409` do not produce duplicate captures.
</Tip>

<AccordionGroup>
  <Accordion title="400 Bad Request — invalid amount or body">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "Errors: [invalid_value($.amount):{{}}" }
    ```

    The `amount` has a wrong value — negative, too many decimal places, etc. An empty or truncated request body returns the same envelope with `"error": "EOF"`.
  </Accordion>

  <Accordion title="400 Bad Request — amount exceeds remaining">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "could not capture: could not capture more than not captured yet: {{}}" }
    ```

    The amount is higher than the remaining uncaptured amount. Examples:

    1. Total 100, capture request 150.
    2. Total 100, one successful capture of 50, another capture for 100.
    3. Total 100, one successful capture of 100, another capture for 100.

    Case 3 is usually an unsafe retry — use an idempotency key instead of re-sending the capture.
  </Accordion>

  <Accordion title="400 Bad Request — payment not authorized">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "could not capture not authorized payments" }
    ```

    The payment status is not `AUTHORIZED`, so captures cannot be made. Check the payment status via `GET /api/v2/payments/{id}` and act accordingly.
  </Accordion>

  <Accordion title="400 Bad Request — already closed">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "already closed" }
    ```

    The payment is already in a terminal `CLOSED` state — usually a duplicate capture of an already fully-captured payment, or a capture after `close`. Check the payment status; if your first capture actually succeeded, no action is needed.
  </Accordion>

  <Accordion title="400 Bad Request — invalid payment id">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "invalid payment id" }
    ```

    The `payment_id` is not a valid UUID. Fix the format.
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_authorized" }
    ```

    The `Authorization` header is missing or wrong. It must be sent as `Authorization: Bearer {secret_key}`.
  </Accordion>

  <Accordion title="404 Not Found — no such payment">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_found", "error": "no such payment" }
    ```

    No payment with this `payment_id` is visible to your API key — wrong id, or a payment of a different store / API key.
  </Accordion>

  <Accordion title="409 Conflict — concurrent request">
    ```json theme={"dark"}
    { "status": "error", "errorType": "conflict", "error": "could not acquire lock: payment is locked" }
    ```

    Another concurrent request for this payment is being processed. Retry shortly with the same idempotency key.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    ```json theme={"dark"}
    { "status": "error", "errorType": "internal", "error": "Internal Server Error" }
    ```

    If you send an idempotency key, retry safely per your retry policy. Without one, call `GET /api/v2/payments/{id}` first and check already-applied captures before retrying. If `500` persists, contact the Tabby Integrations team and check [tabby-status.com](https://www.tabby-status.com/).
  </Accordion>
</AccordionGroup>

***

## `POST /api/v2/payments/{id}/refunds`

Refunds a captured (`CLOSED`) payment.

<Tip>
  Always send an idempotency key — your own unique `reference_id` in the request body (see [Idempotent requests](/pay-in-4-custom-integration/payment-processing#idempotent-requests)) — to make refund retries safe.
</Tip>

<AccordionGroup>
  <Accordion title="400 Bad Request — invalid amount format">
    ```json theme={"dark"}
    {
      "status": "error",
      "errorType": "bad_data",
      "errors": [
        { "field": "$.amount", "code": "invalid_value", "message": "money supports only 3 decimal places, but got: 5" }
      ]
    }
    ```

    The `amount` has a wrong value — too many decimal places for the currency, zero or negative (`"error": "refund amount is less then or equals zero"`), or not a number at all (`"error": "error decoding string 'NaN': can't convert NaN to decimal"`).
  </Accordion>

  <Accordion title="400 Bad Request — amount exceeds refundable">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "refund amount should be less or equal than billed amount" }
    ```

    The refund amount exceeds the still-refundable amount. Examples:

    1. Captured 100, refund request 150.
    2. Captured 100, one successful refund of 50, another refund for 100.
    3. Captured 100, one successful refund of 100, another refund for 100.

    Case 3 is usually an unsafe retry — use an idempotency key instead of re-sending the refund.
  </Accordion>

  <Accordion title="400 Bad Request — cannot refund payment">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "can not refund payment that has no captures and not closed" }
    ```

    The payment is not `CLOSED` or has no captures. Check the payment status and act accordingly.
  </Accordion>

  <Accordion title="400 Bad Request — already closed">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "already closed" }
    ```

    The payment is in a state that no longer accepts this refund (e.g. it was closed without captures). Check the payment status via `GET /api/v2/payments/{id}`.
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_authorized" }
    ```

    The `Authorization` header is missing or wrong. It must be sent as `Authorization: Bearer {secret_key}`.
  </Accordion>

  <Accordion title="404 Not Found — no such payment">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_found", "error": "no such payment" }
    ```

    No payment with this `payment_id` is visible to your API key — wrong id, or a payment of a different store / API key.
  </Accordion>

  <Accordion title="409 Conflict">
    ```json theme={"dark"}
    { "status": "error", "error": "payment is disputed" }
    ```

    Two possible causes:

    1. **Active dispute on the payment** — the body carries `"error": "payment is disputed"`. The refund is blocked until the dispute is resolved; see [Disputes](/pay-in-4-custom-integration/disputes).
    2. **Concurrent refunds on the same payment** — the body carries `"error": "could not acquire lock: payment is locked"`. Another request is being processed; retry shortly with the same idempotency key.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    ```json theme={"dark"}
    { "status": "error", "errorType": "internal", "error": "Internal Server Error" }
    ```

    If you send an idempotency key, retry safely per your retry policy. Without one, call `GET /api/v2/payments/{id}` first and check already-applied refunds before retrying. If `500` persists, contact the Tabby Integrations team and check [tabby-status.com](https://www.tabby-status.com/).
  </Accordion>
</AccordionGroup>

***

## `POST /api/v2/payments/{id}/close`

Closes an `AUTHORIZED` payment (e.g. when the order is cancelled before capture).

<AccordionGroup>
  <Accordion title="400 Bad Request — payment not authorized">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "only authorized payments can be closed" }
    ```

    Only `AUTHORIZED` payments can be closed. Check the payment status and act accordingly.
  </Accordion>

  <Accordion title="400 Bad Request — payment already expired">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "could not cancel payment: payment was already expired" }
    ```

    The payment was `AUTHORIZED` earlier, but the authorization expired before `close` was called. No action is needed — the customer is not charged; treat the payment as expired.
  </Accordion>

  <Accordion title="400 Bad Request — already closed">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "already closed" }
    ```

    The payment is already `CLOSED` — usually a duplicate `close` call. No action is needed.
  </Accordion>

  <Accordion title="400 Bad Request — invalid payment id">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "invalid payment id" }
    ```

    The `payment_id` is not a valid UUID. Fix the format.
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_authorized" }
    ```

    The `Authorization` header is missing or wrong. It must be sent as `Authorization: Bearer {secret_key}`.
  </Accordion>

  <Accordion title="404 Not Found — no such payment">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_found", "error": "no such payment" }
    ```

    No payment with this `payment_id` is visible to your API key — wrong id, or a payment of a different store / API key.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    ```json theme={"dark"}
    { "status": "error", "errorType": "internal", "error": "Internal Server Error" }
    ```

    Call `GET /api/v2/payments/{id}` to check the current status before retrying. If `500` persists, contact the Tabby Integrations team and check [tabby-status.com](https://www.tabby-status.com/).
  </Accordion>
</AccordionGroup>

***

## Webhooks — `/api/v1/webhooks`

Applies to `POST /api/v1/webhooks`, `GET /api/v1/webhooks`, `GET /api/v1/webhooks/{id}`, `PUT /api/v1/webhooks/{id}`, `DELETE /api/v1/webhooks/{id}`. Authenticate with the **Secret Key**.

<Note>
  On `api.tabby.ai` a missing or malformed `Authorization` header and an unknown secret key are rejected at the edge with an **empty body** (`400` for a missing header or a non-Bearer scheme, `401` for an unknown key). The JSON bodies below are returned once the request reaches the service (today every such request on `api.tabby.sa` reaches the service). Do not rely on a response body for `400`/`401` authentication errors; branch on the status code.
</Note>

<AccordionGroup>
  <Accordion title="400 Bad Request — invalid webhook url">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "create payment webhook: invalid webhook url" }
    ```

    The `url` is not a valid, publicly reachable HTTPS URL. Fix the URL.
  </Accordion>

  <Accordion title="400 Bad Request — webhook already exists">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "create payment webhook: webhook already exists" }
    ```

    A webhook with the same URL is already registered for this merchant. List the registered webhooks with `GET /api/v1/webhooks` instead of re-creating.
  </Accordion>

  <Accordion title="400 Bad Request — max number of webhooks reached">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "create payment webhook: max number of webhooks reached" }
    ```

    The merchant already has the maximum number of registered webhooks. Remove stale ones with `DELETE /api/v1/webhooks/{id}` before adding new.
  </Accordion>

  <Accordion title="400 Bad Request — malformed request">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "json decode: EOF" }
    ```

    The request body is empty or not valid JSON, or the webhook `id` in the path is not a valid UUID.
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_authorized", "error": "invalid secret key" }
    ```

    The `Authorization` header is missing or carries a wrong key (`api key not found` / `invalid secret key`). It must be sent as `Authorization: Bearer {secret_key}`.
  </Accordion>

  <Accordion title="404 Not Found — no such webhook">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_found", "error": "no such webhook" }
    ```

    No webhook with this `id` exists for your merchant. List the registered webhooks with `GET /api/v1/webhooks`.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    ```json theme={"dark"}
    { "status": "error", "errorType": "internal", "error": "Internal Server Error" }
    ```

    Retry per your retry policy. If `500` persists, contact the Tabby Integrations team and check [tabby-status.com](https://www.tabby-status.com/).
  </Accordion>
</AccordionGroup>

***

## Dispute webhooks — `/api/v1/dispute-webhooks`

Applies to `POST /api/v1/dispute-webhooks`, `GET /api/v1/dispute-webhooks`, `GET /api/v1/dispute-webhooks/{id}`, `PUT /api/v1/dispute-webhooks/{id}`, `DELETE /api/v1/dispute-webhooks/{id}`. Authenticate with the **live Secret Key**; the `X-Merchant-Code` header is required on every request. See [Dispute webhooks](/pay-in-4-custom-integration/dispute-webhooks) for how they work.

<Note>
  On `api.tabby.ai` a missing or malformed `Authorization` header and an unknown secret key are rejected at the edge with an **empty body** (`400` for a missing header or a non-Bearer scheme, `401` for an unknown key); a merchant code that does not belong to the key may also be answered at the edge. The JSON bodies below are returned once the request reaches the service (today every such request on `api.tabby.sa` reaches the service). Do not rely on a response body for `400`/`401` authentication errors; branch on the status code. Always call the base URL of your merchant's region.
</Note>

<AccordionGroup>
  <Accordion title="400 Bad Request — code is required">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "code is required" }
    ```

    The `X-Merchant-Code` header is missing. It is required on every dispute-webhook request, even when your secret key maps to a single merchant.
  </Accordion>

  <Accordion title="400 Bad Request — invalid webhook url">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "invalid webhook url" }
    ```

    The `url` points to `localhost`, to a raw IP address, or to a host name that does not resolve in DNS. Use a publicly reachable host name (HTTPS recommended).
  </Accordion>

  <Accordion title="400 Bad Request — webhook already exists">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "webhook already exists" }
    ```

    A dispute webhook with the same URL is already registered for this merchant (on `PUT`: the new URL belongs to another of your dispute webhooks). URLs are compared after normalisation (lower-case scheme and host, default port and trailing slash removed). List the registered webhooks with `GET /api/v1/dispute-webhooks` instead of re-creating.
  </Accordion>

  <Accordion title="400 Bad Request — max number of webhooks reached">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "max number of webhooks reached" }
    ```

    The merchant already has 4 dispute webhooks (the limit is separate from payment webhooks). Remove stale ones with `DELETE /api/v1/dispute-webhooks/{id}` before adding new.
  </Accordion>

  <Accordion title="400 Bad Request — malformed request">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "bad_request" }
    ```

    The request body is empty or not valid JSON, or `url` is missing, empty or not an absolute URL. Send a JSON object with a `url`, as in [Register a dispute webhook](/api-reference/dispute-webhooks/register-a-dispute-webhook).
  </Accordion>

  <Accordion title="400 Bad Request — invalid header">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "bad_request", "errors": [ { "code": "invalid_value", "field": "$.header.title", "message": "empty value" } ] }
    ```

    `header` is present but `title` or `value` is missing, empty or invalid: `title` must be a valid HTTP header name (no spaces, up to 128 characters), `value` up to 1024 characters with no control characters. The `errors` array points at the offending field. Omit `header` entirely if you do not want one.
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_authorized", "error": "no accessible merchants found" }
    ```

    The `Authorization` header is missing or wrong (`missing Authorization header`, `missing Bearer scheme`, `api key not found`, `invalid secret key` — the last one when a public `pk_` key is sent), or the `X-Merchant-Code` does not belong to the key you authorized with (`no accessible merchants found` — also returned for an unknown code). Send `Authorization: Bearer {secret_key}` together with one of the merchant codes of that key.
  </Accordion>

  <Accordion title="403 Forbidden — disputes have no test mode">
    ```json theme={"dark"}
    { "status": "error", "errorType": "no_permission", "error": "disputes have no test mode" }
    ```

    The request was authorized with a test secret key (`sk_test_...`). Dispute webhooks exist for live payments only — use the live secret key (`sk_...`).
  </Accordion>

  <Accordion title="404 Not Found — webhook not found">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_found", "error": "webhook not found" }
    ```

    No dispute webhook with this `id` exists for your merchant (including one that was already removed or belongs to another merchant), or the `id` is not a valid UUID. List the registered webhooks with `GET /api/v1/dispute-webhooks`.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    ```json theme={"dark"}
    { "status": "error", "errorType": "internal", "error": "internal" }
    ```

    Retry per your retry policy. If `500` persists, contact the Tabby Integrations team and check [tabby-status.com](https://www.tabby-status.com/).
  </Accordion>
</AccordionGroup>

***

## Disputes — `/api/v1/disputes`

Applies to `GET /api/v1/disputes`, `GET /api/v1/disputes/{disputeId}`, `POST /api/v1/disputes/{disputeId}/provide-evidence`, `POST /api/v1/disputes/approve`, `POST /api/v1/disputes/challenge`, `POST /api/v1/disputes/attachments/upload`. Authenticate with the **Secret Key**. See [Disputes](/pay-in-4-custom-integration/disputes) for the flow itself.

<AccordionGroup>
  <Accordion title="400 Bad Request">
    ```json theme={"dark"}
    { "status": "error", "errorType": "bad_data", "error": "failed to decode request" }
    ```

    The request body is malformed or a parameter is invalid (e.g. wrong `dispute_id` format, missing required fields). Read the `error` field for the specific cause.
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_authorized" }
    ```

    The `Authorization` header is missing or wrong. It must be sent as `Authorization: Bearer {secret_key}`.
  </Accordion>

  <Accordion title="404 Not Found — dispute not found">
    ```json theme={"dark"}
    { "status": "error", "errorType": "not_found", "error": "dispute not found" }
    ```

    No dispute with this `disputeId` is visible to your API key. Check the id against `GET /api/v1/disputes`.
  </Accordion>

  <Accordion title="409 Conflict (provide-evidence)">
    ```json theme={"dark"}
    { "status": "error", "errorType": "conflict" }
    ```

    The dispute is not in a state that accepts this operation — e.g. evidence was already submitted or the dispute has been resolved. Re-fetch it with `GET /api/v1/disputes/{disputeId}` and check its status.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    ```json theme={"dark"}
    { "status": "error", "errorType": "internal", "error": "Internal Server Error" }
    ```

    Retry per your retry policy. If `500` persists, contact the Tabby Integrations team and check [tabby-status.com](https://www.tabby-status.com/).
  </Accordion>
</AccordionGroup>


# Register a webhook
Source: https://docs.tabby.ai/api-reference/webhooks/register-a-webhook

post /api/v1/webhooks
Creates a new webhook. Webhooks are registered per `merchant_code` and per environment:
the environment is determined by the secret key you authorize the request with —
a production key (`sk_...`) registers webhooks for production payments, a test key
(`sk_test_...`) registers webhooks for test payments. Each `merchant_code` + key pair
can have up to 4 webhooks.


<Note>
  This is a public, self-service endpoint. Call `https://api.tabby.ai/api/v1/webhooks` (`https://api.tabby.sa/api/v1/webhooks` for KSA) with your secret key and the `X-Merchant-Code` header. How webhooks work, payload and retries: <a href="/pay-in-4-custom-integration/webhooks">Payment webhooks</a>.
</Note>


# Remove a webhook
Source: https://docs.tabby.ai/api-reference/webhooks/remove-a-webhook

delete /api/v1/webhooks/{id}
Removes the specified webhook.



# Retrieve a webhook
Source: https://docs.tabby.ai/api-reference/webhooks/retrieve-a-webhook

get /api/v1/webhooks/{id}
Retrieves the specified webhook.



# Retrieve all webhooks
Source: https://docs.tabby.ai/api-reference/webhooks/retrieve-all-webhooks

get /api/v1/webhooks
Retrieves all registred webhooks.



# Update a webhook
Source: https://docs.tabby.ai/api-reference/webhooks/update-a-webhook

put /api/v1/webhooks/{id}
Updates the specified webhook.



# Magento 2 Plugin Installation
Source: https://docs.tabby.ai/e-commerce-platforms/magento-2/magento-2-plugin-installation

Install the Tabby extension for Magento 2 with Composer, configure your API keys, and go live.

<Note>
  Tabby works on the Magento 2 platform for all supported countries.
</Note>

The Tabby extension adds Tabby as a payment method at checkout, shows Tabby promotions on your product and cart pages, and can share your product feed with the Tabby Shop.

| Requirement | Value |
| - | - |
| Magento | 2.4.x (`magento/framework ^103.0`) |
| PHP | 7.1 or newer |
| Access | Composer and command-line access to your Magento project |

## Installation Steps

<Steps>
  <Step>
    Sign up at [merchant.tabby.ai](https://merchant.tabby.ai/) (KSA: [merchant.tabby.sa](https://merchant.tabby.sa/)) and fill in all your business details. Your test API keys are then available in the Merchant Dashboard under **Business profile → Stores**.
  </Step>

  <Step>
    [Install the extension with Composer](#install-with-composer) - the recommended way to install it and to update it later.
  </Step>

  <Step>
    [Configure Tabby as a payment method](#configure-tabby-as-a-payment-method) using your test keys.
  </Step>

  <Step>
    [Place a test order and refund it](#test-your-integration) to confirm that the full flow works.
  </Step>

  <Step>
    Replace the test keys with your live keys and [deploy to production](#connect-to-the-live-tabby-environment).
  </Step>
</Steps>

<Warning>
  Install and test the extension in a staging environment first, and keep a backup of your Magento files and database so you can roll back.
</Warning>

## Install with Composer

`tabby/m2-payments` is a metapackage that pulls both Tabby modules: `tabby/m2-checkout` (payment methods, promotions, webhooks) and `tabby/m2-feed` ([product catalogue](/e-commerce-platforms/magento-2/magento-2-product-catalogue)).

```bash theme={"dark"}
composer require tabby/m2-payments
php bin/magento module:enable Tabby_Checkout Tabby_Feed
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
```

Confirm that both modules are enabled:

```bash theme={"dark"}
php bin/magento module:status Tabby_Checkout Tabby_Feed
```

### Update the extension

Run the same sequence with `composer update` to move to the latest release:

```bash theme={"dark"}
composer update tabby/m2-payments --with-dependencies
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
```

<Tip>
  We recommend opening the Tabby settings in the Magento admin after an update and clicking **Save Config**, even if you change nothing. Saving re-applies your configuration to the settings the installed version supports, and registers the webhooks for any store that is missing them.
</Tip>

<Accordion title="Composer reports a higher matching version on packagist.org">
  If Composer stops with *"Higher matching version 7.0.2 of tabby/m2-payments was found in public repository packagist.org"*, your project is pinned to an older constraint. Require the version range explicitly and run the update again:

  ```bash theme={"dark"}
  composer require tabby/m2-payments:^7.0
  ```
</Accordion>

## Other Ways to Install

Composer is the supported path. Use one of these only if Composer is not available to you.

<AccordionGroup>
  <Accordion title="Manual installation from an archive">
    1. Download the [extension archive](https://storage.googleapis.com/plgns/magento2-latest.tar.gz).

    2. Create the directory `Magento2_root/app/code/Tabby/Checkout/` if it does not exist.

    3. Unpack the archive and move all files into `Magento2_root/app/code/Tabby/Checkout/`.

    4. Verify that **Tabby\_Checkout** appears in the list of disabled modules:

       ```bash theme={"dark"}
       php bin/magento module:status
       ```

    5. Enable the module and rebuild:

       ```bash theme={"dark"}
       php bin/magento module:enable Tabby_Checkout
       php bin/magento setup:upgrade
       php bin/magento setup:di:compile
       php bin/magento setup:static-content:deploy -f
       php bin/magento cache:flush
       ```

    <Warning>
      The archive contains the checkout module only. The [product catalogue](/e-commerce-platforms/magento-2/magento-2-product-catalogue) module ships through Composer, and every future update has to be applied by hand.
    </Warning>
  </Accordion>

  <Accordion title="Adobe Commerce Marketplace">
    The extension is published as [Tabby M2 Payments](https://commercemarketplace.adobe.com/tabby-m2-payments.html). Add it to your Adobe Commerce account and install it from your Marketplace purchases. Adobe delivers the same Composer package, so the Magento commands in [Install with Composer](#install-with-composer) still apply.
  </Accordion>
</AccordionGroup>

## Configure Tabby as a Payment Method

Sign in to your Magento 2 admin portal and go to ***Stores > Configuration > Sales > Payment Methods > Tabby Payments***.

In the **Tabby Api** section:

| Setting | Value |
| - | - |
| Merchant Public Key, Merchant Secret Key | Your test keys from the Merchant Dashboard |
| Aggregate store by currency | **Yes** - the extension derives the merchant code from each store's base currency (`AE`, `SA`), which are the default codes Tabby registers for your account. Set it to **No** only if you use [your own store codes](#use-your-own-magento-store-codes). |
| Capture on | **Order placed**, unless your account manager agreed on a different moment |
| Debug | **Yes** while you are testing |

Then enable the payment method in the **Tabby Checkout - Split in 4** section and click **Save Config**. Saving validates your keys and registers your webhooks with Tabby.

<Note>
  If the changes do not take effect immediately, go to ***System > Cache Management***, click **Flush Magento Cache**, then sign out and sign back in to reset permissions.
</Note>

### Manage Tabby Product Catalogue Feature

The [product catalogue](/e-commerce-platforms/magento-2/magento-2-product-catalogue) lists your products on the Tabby Shop. Enable it in ***Stores > Configuration > Sales > Payment Methods > Tabby Payments > Tabby Feed***.

<Warning>
  The Tabby Product Catalogue feature works with **live API keys** only.
</Warning>

<img alt="Tabby Feed setting" />

## Test Your Integration

Place an order with Tabby and refund it (create a Credit Memo) to confirm that the full flow works.

When the test order and the refund go through, you can move to the live environment yourself. Tabby does not run a separate sign-off on your integration.

## Connect to the Live Tabby Environment

<Steps>
  <Step>
    Copy the live Public and Secret keys from the Merchant Dashboard under **Business profile → Stores**. If the live keys are not shown there yet, ask Tabby Partner Support at `partner@tabby.ai` (or `partner@tabby.sa` for KSA) to make them visible.
  </Step>

  <Step>
    Enter them in ***Stores > Configuration > Sales > Payment Methods > Tabby Payments*** on your production site.
  </Step>

  <Step>
    Click **Save Config**. Webhooks are registered per key pair, so this save is what creates your live webhooks - do it on production even if you copied the configuration over from staging and the keys are already in place.
  </Step>
</Steps>

## Specific Settings

### Promotions Only Mode

If your checkout runs through another provider, the plugin can serve Tabby promotions only: it enables the product and cart page snippets and hides Tabby at checkout.

Go to ***Stores > Configuration > Sales > Payment Methods > Tabby Payments***, and set ***Tabby plugin mode*** to ***Promotions only***:

<div>
  <img alt="Promotions only mode" />

  <p>Promo only mode</p>
</div>

### Use Your Own Magento Store Codes

By default there is nothing to send us: with **Aggregate store by currency** set to **Yes**, the extension derives the merchant code from the store's base currency (`AE` for AED, `SA` for SAR) and Tabby registers those codes for your account.

Use your Magento store codes instead when you need a separate Tabby merchant code per store group, for example for separate reporting or separate payment plans per brand:

<Steps>
  <Step>
    In the Magento admin, go to ***Stores > All Stores*** and copy the **Code** of every store group you sell with.

    <img alt="Store codes" />
  </Step>

  <Step>
    Ask Tabby Partner Support at `partner@tabby.ai` (or `partner@tabby.sa` for KSA) to set them up as custom merchant codes, for example `website_store_ae`. Wait for confirmation that the codes are registered on Tabby's side.
  </Step>

  <Step>
    Set **Aggregate store by currency** to **No**. The extension now sends the store group code as the merchant code.
  </Step>
</Steps>

<Warning>
  Change this setting only after Tabby confirms that your codes are registered. A code Tabby does not know breaks checkout with an authorization error.
</Warning>

### Sell in Several Currencies

If one store group sells in more than one currency, enable **Use local store currency on checkout**. The extension then charges in the currency the customer sees and appends it to the merchant code, for example `SA_SAR`. These codes have to be registered on Tabby's side too, so ask Tabby Partner Support to set them up before you turn this on.


# Magento 2 Product Catalogue
Source: https://docs.tabby.ai/e-commerce-platforms/magento-2/magento-2-product-catalogue

Enable the Magento 2 Product Catalogue feature to list your store's products on the Tabby Shop.

We've introduced an exciting new feature to the Tabby Magento 2 plugin – the **Product Catalogue Feature**, designed to help you list your store’s products seamlessly on the Tabby Shop.

The feature is enabled by default in new plugin versions starting from 5.0.11.

[Update the plugin](/e-commerce-platforms/magento-2/magento-2-plugin-installation#update-the-extension) with Composer:

```bash theme={"dark"}
composer update tabby/m2-payments --with-dependencies
php bin/magento module:enable Tabby_Checkout Tabby_Feed
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
```

Check that the setting is enabled in the Tabby API options located at:<br />
**Stores -> Configuration -> Sales -> Payment methods -> Tabby Payments -> Tabby Feed -> "Share product feed with Tabby"**

<img alt="Tabby feed parameter" />

**Key features:**

* **Automated Product Listing**: Easily list your entire Magento 2 store inventory on the Tabby Shop without manual intervention.
* **Real-Time Stock Updates**: Keep your product listings up-to-date effortlessly, as the plugin automatically syncs inventory availability and reflects out-of-stock items in real time.
* **Increased Visibility**: Showcase your products to a broader audience by making them visible to all Tabby app users.
* **Traffic Generation**: Drive interested shoppers directly to your Magento 2 store, increasing clicks and potential sales.


# Matjrah
Source: https://docs.tabby.ai/e-commerce-platforms/matjrah

Connect Tabby on the Matjrah platform by entering your API keys.

<Note>
  Tabby works on the Matjrah platform for the countries KSA and UAE.
</Note>

1. <a href="https://merchant.tabby.ai/">Register with Tabby</a> (KSA: <a href="https://merchant.tabby.sa/">merchant.tabby.sa</a>) and fill all required business details to collect Tabby API Keys.
2. Fill in the keys using the instruction below:

<img alt="Tabby & Matjrah" />

<img alt="Log in to Matjrah" />

<img alt="Step 1" />

<img alt="Step 2" />

<img alt="Step 3" />

<img alt="Steps 4 and 5" />

<img alt="Steps 6 and 7" />

<img alt="Step 8" />

<img alt="Contact information" />


# Odoo Plugin Installation
Source: https://docs.tabby.ai/e-commerce-platforms/odoo/odoo-plugin-installation

Install the Tabby module on Odoo, configure your API keys, and take the integration live.

<Note>
  Tabby works on the Odoo platform for all supported countries. Odoo versions 17, 18, and 19 are supported.
</Note>

<Warning>
  The Tabby module can be installed on self-hosted (on-premise) Odoo and Odoo.sh. Odoo Online (SaaS) does not support the installation of custom modules.
</Warning>

## Installation Steps

<Steps>
  <Step
    title={(
  <span>
    <a href="https://merchant.tabby.ai/">
      Register with Tabby
    </a>
    <span style={{ fontWeight: 'normal', fontSize: '0.9em' }}>
      &nbsp;(KSA: <a href="https://merchant.tabby.sa/">merchant.tabby.sa</a>)
    </span>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;and fill all required business details
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    Receive test API keys from your Tabby account manager
  </span>
)}
  />

  <Step
    title={(
  <span>
    <a href="/e-commerce-platforms/odoo/odoo-plugin-installation#download-the-tabby-module">
      Download the Tabby module
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;matching your Odoo version
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <a href="/e-commerce-platforms/odoo/odoo-plugin-installation#install-the-odoo-module">
      Install the module
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;and&nbsp;
    </span>
    <a href="/e-commerce-platforms/odoo/odoo-plugin-installation#configure-tabby-as-a-payment-method">
      configure Tabby as a payment method
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <a href="/e-commerce-platforms/odoo/odoo-plugin-installation#test-your-integration">
      Test your integration
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Receive live API keys and&nbsp;
    </span>
    <a href="/e-commerce-platforms/odoo/odoo-plugin-installation#connect-to-the-live-tabby-environment">
      deploy to production
    </a>
  </span>
)}
  />
</Steps>

### Download the Tabby Module

Tabby provides a separate module build for each supported Odoo version. Download the archive matching the major version of your Odoo installation:

| Odoo version | Module download |
| - | - |
| Odoo 19 | <a href="https://storage.googleapis.com/plgns/odoo19-latest.zip">odoo19-latest.zip</a> |
| Odoo 18 | <a href="https://storage.googleapis.com/plgns/odoo18-latest.zip">odoo18-latest.zip</a> |
| Odoo 17 | <a href="https://storage.googleapis.com/plgns/odoo17-latest.zip">odoo17-latest.zip</a> |

Each archive contains the `payment_tabby` module folder — this folder is the unit of installation.

### Install the Odoo Module

1. Extract the downloaded archive and locate the `payment_tabby` module folder inside it
2. Copy the `payment_tabby` folder into your Odoo addons directory — any directory listed in the `addons_path` parameter of your `odoo.conf` (commonly a `custom_addons` folder). Make sure the copied files are readable by the user running the Odoo service
3. Restart the Odoo service
4. Activate the developer mode: go to ***Settings -> General Settings***, scroll down to **Developer Tools** and click **Activate the developer mode**
5. Go to ***Apps*** and click ***Update Apps List*** in the top menu, then confirm the update
6. In the Apps search bar remove the default filters, search for **Tabby** and click **Activate** on the "Payment Provider: Tabby" module

<Note>
  **Odoo.sh:** instead of copying files to the server, add the `payment_tabby` folder to your Odoo.sh project's GitHub repository and deploy the branch — the module then appears in the Apps list after **Update Apps List**.
</Note>

#### Optional: Updating the Odoo Module

When a new version of the Tabby module is released:

1. Download the latest archive for your Odoo version and replace the existing `payment_tabby` folder in your addons directory with the new one
2. Restart the Odoo service
3. Go to ***Apps***, remove the default filters, find the **Tabby** module and click ***Upgrade*** from the module's menu

### Configure Tabby as a Payment Method

1. Go to ***Website -> Configuration -> Payment Providers*** (the same screen is also available via ***Invoicing -> Configuration -> Payment Providers*** and ***Sales -> Configuration -> Payment Providers***)
2. Open **Tabby** in the list of providers
3. In the **Credentials** tab, enter the **Tabby Public Key** and **Tabby Secret Key** you received from your account manager
4. Set the **State** to **Enabled**
5. Click **Save**

Once the provider is enabled, it is automatically published on your website and Tabby appears among the payment methods on Checkout.

<Note>
  Tabby requires the order currency to match the customer's country: UAE-AED, KSA-SAR. Make sure the currency of your website/pricelist is set accordingly — Tabby will not be displayed on Checkout for unsupported currencies.
</Note>

### Test Your Integration

After completing your integration, make an order and refund it to ensure that everything works as expected.

**Coordinate Testing with Tabby**

Before deploying Tabby integration to your production site, Tabby needs to validate the correctness of the integration. Contact your account manager to coordinate this test.

### Connect to the Live Tabby Environment

1. Get your Public and Secret keys for the live environment. Ask your account manager to share the keys
2. Set your live keys in the Odoo admin panel: go to ***Website -> Configuration -> Payment Providers -> Tabby***, open the **Credentials** tab and replace the test keys
3. **Launch to Production**<br />
   After you've connected to the live environment and we've tested your integration, you're ready to offer Tabby payment methods to your customers.

### Feedback and Support

If you face any issues during installation or testing, don't hesitate to get in touch with `partner@tabby.ai` / `partner@tabby.sa` with the store link, issue description, and screenshots or screencasts of the observed behaviour.


# OpenCart Plugin Installation
Source: https://docs.tabby.ai/e-commerce-platforms/opencart/opencart-plugin-installation

Install the Tabby plugin for OpenCart, configure your API keys, and connect to the live environment.

<Note>
  Tabby works on the OpenCart platform for all supported countries. OpenCart versions 2.x, 2.1.x, and 3.x with the Journal Theme are supported.
</Note>

## Installation Steps

<Steps>
  <Step
    title={(
  <span>
    <a href="https://merchant.tabby.ai/">
      Register with Tabby
    </a>
    <span style={{ fontWeight: 'normal', fontSize: '0.9em' }}>
      &nbsp;(KSA: <a href="https://merchant.tabby.sa/">merchant.tabby.sa</a>)
    </span>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;and fill all required business details
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    Receive test API keys from your Tabby account manager
  </span>
)}
  />

  <Step
    title={(
  <span>
    To download Tabby Plugin,&nbsp;
    <a href="https://storage.googleapis.com/plgns/opencart-latest.zip">
      click here
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <a href="/e-commerce-platforms/opencart/opencart-plugin-installation#install-the-opencart-extension">
      Install the plugin
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;and&nbsp;
    </span>
    <a href="/e-commerce-platforms/opencart/opencart-plugin-installation#configure-tabby-as-a-payment-method">
      configure Tabby as a payment method
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <a href="/e-commerce-platforms/opencart/opencart-plugin-installation#test-your-integration">
      Test your integration
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Receive live API keys and&nbsp;
    </span>
    <a href="/e-commerce-platforms/opencart/opencart-plugin-installation#connect-to-live-tabby-environment">
      deploy to production
    </a>
  </span>
)}
  />
</Steps>

### Install the OpenCart Extension

1. Go to ***Extensions -> Installer*** and install the extension.
2. Go to ***Extensions -> Modifications*** and click the refresh button under your profile (without re-loading this page in the browser).
3. Check the Tabby payment in the modification list.
4. Go to ***Extensions -> Extensions -> Modules*** in your OpenCart admin panel and activate Tabby Module.

The example of Tabby Module settings:

<img alt="Tabby settings 1" />

<img alt="Tabby settings 2" />

#### Optional: Updating the OpenCart Extension

When you want to update your current version with the new one.

1. Go to ***Extensions -> Modifications*** and delete the Tabby payment
2. Go to ***Extensions -> Installer*** and delete all files named oc3-tabby-x.x.x.ocmod.zip from install history
3. Upload and install the extension
4. Go to ***Extensions -> Modifications*** and click the refresh button under your profile (without reloading the page in the browser)
5. Check the Tabby payment in the modification list;
6. Go to ***Extensions -> Extensions -> Modules*** in your Opencart admin panel and activate Tabby Module
7. Open **Tabby Module** settings and click on Save changes button

### Configure Tabby as a Payment Method

1. Go to ***Extensions -> Extensions -> Modules*** in your OpenCart admin panel, find Tabby Module, click "Edit" and enter the **Public API Key** and **Secret API Key** for testing.
2. Go to ***Extensions -> Extensions -> Payments*** in your OpenCart admin panel and enable Tabby Installments (Split in 4).
3. Make sure the following settings are configured in any Tabby option Installments: – **Capture on – order\_placed**
4. Go to ***Design -> Layouts -> Checkout*** and add Tabby Module to Content Top

**For Journal theme only:** Go to Journal → Layouts → Checkout, choose Top+, choose OpenCart (the last one) and choose Tabby Module →Tabby Checkout → Save changes.

### Test Your Integration

After completing your integration, make an order and refund it to ensure that everything works as expected.

**Coordinate Testing with Tabby**

Before deploying Tabby integration to your production site, Tabby needs to validate the correctness of the integration. Contact your account manager to coordinate this test.

### Connect to live Tabby environment

1. Get your public and secret keys for the live environment. Ask you account manager to share the keys.
2. Set your live public and secret keys in the OpenCart admin panel, for this go to ***Extensions -> Extensions -> Modules -> Tabby Module*** in your OpenCart admin panel.
3. **Launch to Production**<br />
   After you’ve connected to the live environment and we’ve tested your integration, you’re ready to deploy to your production environment and offer Tabby payment methods to your customers.

## Specific settings

### No Price snippet

It is possible to turn on non standard Tabby snippets in ***Extensions -> Extensions -> Modules -> Tabby module (Tabby Checkout),*** parameter ***Tabby Promo theme*** should have **:non standard** specified:

<div>
  <img alt="Tabby promo theme" />

  <p>Promotions theme</p>
</div>

<img alt="No price snippet" />

<div>
  <img alt="No price pop-up" />

  <p>No price snippet</p>
</div>


# OpenCart Product Catalogue
Source: https://docs.tabby.ai/e-commerce-platforms/opencart/opencart-product-catalogue

Enable the OpenCart Product Catalogue feature to list your store's products on the Tabby Shop.

We've introduced an exciting new feature to the OpenCart plugin – the **Product Catalogue Feature**, designed to help you list your store’s products seamlessly on the Tabby Shop.

The feature is enabled by default in new plugin versions starting from 2.9.0.

Install or Update the plugin to the latest version via below link:<br />
<a href="https://storage.googleapis.com/plgns/opencart-latest.zip">[https://storage.googleapis.com/plgns/opencart-latest.zip](https://storage.googleapis.com/plgns/opencart-latest.zip)</a>

Check that the setting is enabled in the Tabby API options located at:<br />
**Extensions -> Tabby Module -> "Tabby Product Feed"**

<img alt="Tabby Product Feed" />

**Key features:**

* **Automated Product Listing**: Easily list your entire OpenCart store inventory on the Tabby Shop without manual intervention.
* **Real-Time Stock Updates**: Keep your product listings up-to-date effortlessly, as the plugin automatically syncs inventory availability and reflects out-of-stock items in real time.
* **Increased Visibility**: Showcase your products to a broader audience by making them visible to all Tabby app users.
* **Traffic Generation**: Drive interested shoppers directly to your OpenCart store, increasing clicks and potential sales.


# Salesforce
Source: https://docs.tabby.ai/e-commerce-platforms/salesforce

Install and configure the Tabby cartridge for Salesforce Commerce Cloud.

<Note>
  Tabby works on the Salesforce Commerce Cloud platform for all supported countries.
</Note>

## Installation Steps

<Steps>
  <Step
    title={(
  <span>
    <a href="https://merchant.tabby.ai/">
      Register with Tabby
    </a>
    <span style={{ fontWeight: 'normal', fontSize: '0.9em' }}>
      &nbsp;(KSA: <a href="https://merchant.tabby.sa/">merchant.tabby.sa</a>)
    </span>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;and fill all the business details
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    Receive your Testing API keys from your Tabby account manager
  </span>
)}
  />

  <Step
    title={(
  <span>
    Download and install Tabby Cartridge for your platform:<br />
    <span style={{ fontWeight: 'normal' }}>
      To download SFRA (Store Front Reference Architecture) Cartridge,&nbsp;
    </span>
    <a href="https://storage.googleapis.com/plgns/salesforce1.0.6.zip">
      click here
    </a><br />
    <span style={{ fontWeight: 'normal' }}>
      To download SiteGenesis Cartridge,&nbsp;
    </span>
    <a href="https://storage.googleapis.com/plgns/salesforcesitegenesis1.0.2.zip">
      click here
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    Test your integration and contact Tabby to have a green light for going live
  </span>
)}
  />

  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    Collect your Live API Keys, populate them for your store, make sure Live Webhooks are installed. You are ready for going live now
  </span>
)}
  />
</Steps>

Salesforce integration supposes adding the necessary cartridges into an SFCC reference application.

Tabby cartridge package contains 3 folders:

1. int\_tabby\_core – Tabby core implementations both for Sitegenesis and SFRA
2. int\_tabby\_sfra – Tabby SFRA changes/implementations
3. bm\_tabby – Tabby Business Manager module

<Warning>
  Compatibility: SFRA v6.0.0 Compatibility Mode 21.7
</Warning>

### Cartridges Installation

#### Adding Cartridges in Salesforce Commerce Cloud Studio

1. Open package.json and ensure the base path mentioned is correctly resolved (please provide the correct path to app\_storefront\_base)
2. Open the command prompt and run ‘npm install’ (assuming node.js (12.21.0 and above) is installed) to install all of the local dependencies
3. Run the “npm run compile”
4. Create the dw\.json file:

```
{
    "hostname": "your-sandbox-hostname.demandware.net",
    "username": "yourlogin",
    "password": "yourpwd",
    "code-version": "version_to_upload_to"
}
```

5. Upload this code to the environment using the command ‘npm run uploadCartridge’, that will upload the **int\_tabby\_core** , **int\_tabby\_sfra** and **bm\_tabby** cartridges to the sandbox you specified in dw\.json file

#### Activating Cartridges in Business Manager

Before Tabby functionality can become available to Reference Architecture, the cartridges need to be added to the cartridge path of the site. In order to do this, follow the following instructions:

* Log into Business Manager
* Navigate to *Administration -> Sites -> Manage Sites*
* Click on the site name
* Go to the "Settings" tab
* In the textbox cartridges add **int\_tabby\_sfra:int\_tabby\_core** before **app\_storefront\_base**

<Check>
  example: **int\_tabby\_sfra:int\_tabby\_core: app\_storefront\_base**
</Check>

* Click **Apply**
* Repeat steps 3 to 5 for each site that is to use Tabby
* To run the Jobs and have tabby BM module, Navigate to *Administration -> Sites -> Manage Sites*
* Go to the "Manage the Business Manager site” tab
* In the textbox cartridges add **int\_tabby\_core:bm\_tabby** to the start

### Configuration

#### Importing Meta Data with a single Site Import

All import files are located in the import folder (metadata) within the cartridge installation pack. To import necessary Tabby settings:

* Open the metadata folder from the repository structure (open jobs.xml) and change the references of RefArchGlobal to your site id;
* Open the metadata/sites folder from the repository structure and change the folder name from RefArchGlobal to your site id. If you have multiple sites with Tabby, then copy RefArchGlobal folder and rename it with your other site id(s).
* Open the metadata/sites/YourSiteID/preferences.xml file from the repository structure;
* Fill in **tabbyServiceCredentialPublicKey** and **tabbyServiceCredentialSecretKey** with keys provided by your account manager from Tabby;
* Fill in **tabbyWebhooksTitle** and **tabbyWebhooksValue** values;
* Compress the metadata folder from the repository structure;
* Log in to the Business Manager and navigate to *Administration -> Site Development -> Site Import & Export*, upload the zipped folder, go back and use the import button to import the file;
* After a successful import, the entire configuration requirements needed for Tabby are available according to your Tabby account data.

#### Managing Tabby Custom Site Preferences

In Business Manager, navigate to the *Site -> Merchant Tools -> Site Preferences -> Custom Preferences*. A custom site preference group "Tabby" is available. Please select it and edit the attributes according to your Tabby account data.

| | | |
| - | - | - |
| **Site Preference** | **Description** | **Values** |
| Is Tabby Enable | This field represents the enable/disable tabby implementation. | Boolean: True/FalseDefault: True |
| Tabby Environment | This field represents the type of the environment. | Enum of String: Development -> Development instancesProduction -> Production instancesDefault: Development |
| Service Credential Public Key | This field represents the tabby service credential public key (pk\_...). | String: (Mandatory) The public API key that Tabby provided to you |
| Service Credential Secret Key | This field represents the tabby service credential secret key (sk\_...). | String: (Mandatory) The secret API key that Tabby provided to you |
| Is Tabby Installments Enable | This field represents the Installments payment method is enabled. | Boolean: True/False Default: True |
| Is Tabby Credit Card Installments Enable(Deprecated) | This field represents the Credit Card Installments payment method is enabled. | Boolean: True/False Default: False |
| Is Tabby Pay Later Enable | This field represents the Pay Later payment method is enabled. | Boolean: True/False Default: False |
| Immediate Capture On Authorize | This field represents if the Immediate Capture on Authorize is enabled. If Yes -> Capture request will be triggered automatically after success Authorization. If No -> Tabby-Capture scheduled job will send the capture request. | Boolean: True/False Default: True |
| Installments Count | This field represents Installments counts. | Integer:Default: 4 |
| Tabby Merchant Code Per Country | This field represents the Merchant codes per country in a JSON format: \{ "AE": "uae","SA": "ksa","KW": "kwt"} | Text (JSON) \{ "AE": "uae","SA": "ksa","KW": "kwt"} - need to define Site countries only. |
| Card Size | This field represents the tabby card size, can be narrow or wide, depending on the width | Enum of String: Narrow/Wide Default: Narrow |
| Card Theme | This field represents the tabby card theme, can be default or black, depending on the styles | Enum of String: Default/Black Default: Default |
| Webhooks Title | This field represents the arbitrary header name to sign the request for the webhooks.Will be used to verify webhook requests that tabby system sends. | String: |
| Webhooks Value | This field represents the random string to sign the request for the webhooks.Will be used to verify webhook requests that tabby system sends. | String: |

#### Managing Tabby Payment Processor

In Business Manager select the required site from the dropdown and navigate to *Merchant Tools -> Ordering -> Payment Processors*.

#### Managing Tabby Payment Methods

In the integration package, a payment method definition is provided in the file that you have already imported

1. Navigate to *Merchant Tools -> Ordering -> Payment Methods*;
2. Enable/Disable the Payment Method under *Ordering -> Payment Methods* section that needs to be activated. Repeat these steps for all the Payment Methods that are required to be supported on the site.

#### Managing Jobs

In the integration package, a job definition is provided in the import zip (metadata.zip) file (jobs.xml). Make sure to associate the jobs with the respective merchant site.

*Tabby-CaptureShippedOrders*

It captures the payments that are authorized by Tabby. This job fetches the orders which have confirmationStatus=CONFIRMED, paymentStatus=NOTPAID, shippingStatus=SHIPPED and custom.tabbyPaymentStatus: AUTHORIZED.

<Check>
  Script file: int\_tabby\_core/cartridge/scripts/jobs/capture.js
</Check>

If the site preference “**Immediate Capture On Authorize**” is set to "True", it is not necessary to enable this job.

*Tabby-RegisterWebhooks*

It registers the Webhooks for the sites defined by merchant*codes from the "Site preference" tab. Each* merchant\_code needs to be registered separately. This job is a one time job to register the Webhooks. It is important to fill in “Webhooks Title” and “Webhooks Value” in the "Site Preferences" before running this job.

<Check>
  Script file int\_tabby\_core/cartridge/scripts/jobs/webhooks.js
</Check>

*Tabby-Feedback*

It processes the TabbyFeedback custom objects that are saved within the TabbyWebhooks-Process endpoint. Custom object details are to compare with the order payment statuses. If there is a difference between the order/payment status, the job will synchronize the order/payment statuses based on the TabbyFeedback details.

<Check>
  Script file int\_tabby\_core/cartridge/scripts/jobs/feedback.js
</Check>

#### Tabby Business Manager Module

The cartridge for Business Manager module bm\_tabby is present in the installation package. It helps processing capture and refund APIs. To enable/activate it, do the following:

1. Navigate to *Administration -> Organization -> Roles & Permissions*;
2. Click **Administrator** in the Roles;
3. Click **Business Manager Modules**;
4. Select the sites where you have Tabby;
5. Click **Apply**;
6. Scroll to *Ordering -> Tabby Orders* and check the checkbox;
7. Click **Update** at the bottom of the page;

Once it is enabled, “Tabby Orders” will be placed under *Merchant Tools > Ordering*


# Salla
Source: https://docs.tabby.ai/e-commerce-platforms/salla



<Note>
  Tabby works on the Salla platform for the KSA only with SAR as currency.
</Note>

1. <a href="https://merchant.tabby.ai/">Register with Tabby</a> (KSA: <a href="https://merchant.tabby.sa/">merchant.tabby.sa</a>) and fill all required business details to collect Tabby API Keys.
2. Fill in the keys using the instruction below:

<img alt="Tabby & Salla" />

<img alt="Step 1" />

<img alt="Step 2" />

<img alt="Step 3" />

<img alt="Step 4" />

<img alt="Step 5" />

<img alt="Contact information" />


# Shopify Plugin Installation
Source: https://docs.tabby.ai/e-commerce-platforms/shopify/shopify-plugin-installation

Install the Tabby app for Shopify, configure webhooks and settings, and go live.

<Note>
  Tabby works on the Shopify platform for all supported countries. Currency conversion may apply for multi-currency stores, check **Multi-Currency Processing and Currency Conversion** below.
</Note>

## Installation Steps

No time to read or have questions on any of the steps? Watch video guide on<br />
**How to set up Tabby on Shopify:**

<video alt="How to set up Tabby on Shopify" />

<Steps>
  <Step title="Register with Tabby">
    [Register with Tabby](https://merchant.tabby.ai/) (KSA: [merchant.tabby.sa](https://merchant.tabby.sa/)) and fill all required business details to collect Tabby Live API Keys.
  </Step>

  <Step title="Install the Tabby Payment App">
    To install Tabby Payment App, [click here](https://apps.shopify.com/tabby-payment-1). After the installation Shopify opens the Tabby payment method page.
  </Step>

  <Step title="Add your API keys">
    On the Tabby payment method page click **More actions → Manage**. Copy the **Live Public** and **Secret keys** from the [Merchant Dashboard](https://merchant.tabby.ai/business-profile/stores) (KSA: [merchant.tabby.sa](https://merchant.tabby.sa/business-profile/stores)) and paste them in the necessary fields. Leave the **Webhook Verification Code** empty, you will get it in Step 5. Click **Save**.

    Keep this page open — you come back to it in Step 5.

    <Note>
      **If you closed the Tabby page**

      Open **Settings → Payments** and in **Additional payment providers** click **Add**.

      <img alt="Additional payment providers with the Add button" />

      Stay on the **Search by payment method** tab and search for **Tabby**.

      <img alt="Add payment method page with the Search by payment method tab" />

      **More actions → Manage** opens the settings page again.

      <img alt="More actions menu on the Tabby page with Manage highlighted" />
    </Note>
  </Step>

  <Step title="Set up Shopify Webhooks">
    Tabby requires Shopify Webhooks to update the order number, fetch the phone number and order lines from Shopify, and read product details such as category and brand from your catalogue.

    Open **Settings → Notifications → Webhooks** and click **Create webhook**. Add 6 webhooks:

    | event | Callback URL | Format | API version |
    | - | - | - | - |
    | Transaction creation | `https://sfy-payment.tabby.ai/api/webhook/transaction/create` | JSON | Latest |
    | Order creation | `https://sfy-payment.tabby.ai/api/webhook/order/create` | JSON | Latest |
    | Checkout creation | `https://sfy-payment.tabby.ai/api/webhook/checkout/create` | JSON | Latest |
    | Checkout update | `https://sfy-payment.tabby.ai/api/webhook/checkout/create` | JSON | Latest |
    | Product creation | `https://sfy-payment.tabby.ai/api/webhook/product/create` | JSON | Latest |
    | Product update | `https://sfy-payment.tabby.ai/api/webhook/product/update` | JSON | Latest |

    Use only the **latest** API version on every webhook.
  </Step>

  <Step title="Add the Webhook Verification Code">
    Copy the Webhook Verification Code which is generated after the first Webhook creation.

    <div>
      <img alt="Webhook Verification Code" />

      <p>Webhook Verification Code</p>
    </div>

    Paste the code in **Settings → Payments → Additional payment providers → Tabby → More actions → Manage → Webhook Verification Code** and click **Save**.
  </Step>

  <Step title="Activate Tabby as a payment method">
    The API keys and the Webhook Verification Code are saved now, so Tabby can be switched on. On the Tabby settings page click **Back to Settings** to return to the Tabby payment method page and click **Activate**.
  </Step>

  <Step title="Check the required settings">
    1. Make sure **Test mode** is off. The toggle sits on the Tabby payment method page — **Settings → Payments → Additional payment providers → Tabby**. Tabby does NOT pay out for test / playground orders ever, even if a live customer places a real order while Test mode was on.

       <img alt="Test mode toggle on the Tabby payment method page" />

    2. Email and phone number are required for Tabby payment method. Please enable the following settings in your admin panel:

       <img alt="Customer contact method set to Email" />

       <img alt="Shipping address phone number set to Required" />
  </Step>
</Steps>

<Warning>
  If you have installed Webhooks earlier and have issues with updating order numbers - please, make sure all 6 webhooks are set up and you are using the latest available API version. Kindly refer to the
  <a href="/e-commerce-platforms/shopify/shopify-plugin-installation#webhook-api-version-update">Webhook API Version Update.</a>
</Warning>

### Webhook API Version Update

Here **Webhook Update Demonstration** can be reviewed:

<video alt="Webhook Update Demonstration" />

Shopify Webhooks are created for the particular API version. Shopify releases several versions per year, so it means your initial API version settings will inevitably expire. Tabby makes the necessary changes to support the latest updated API versions, but this also requires a manual action from the partner's end.

You need to go to Settings -<span>></span> Notifications -<span>></span> Webhooks and choose the **latest** API version from the dropdown of a particular Tabby Webhook.

## Add Tabby Snippets

<div>
  <div>
    <img alt="Tabby snippet on product page" />
  </div>

  <div>
    <img alt="Pop-up" />
  </div>
</div>

Tabby snippets let your customers know they can split their payments with Tabby in your store. Snippets appear on the product and cart pages and may help improve conversion.

To add Tabby snippets to your product and cart pages, please follow our detailed instructions and video manuals here: <a href="/e-commerce-platforms/shopify/shopify-snippets">Tabby Snippets for Shopify</a>

<Warning>
  <div>
    <span>Please note that snippets alone do not activate Tabby as a payment method in your store and don’t affect payment processing. Before adding snippets, make sure Tabby is already integrated and visible on your checkout page. </span>
  </div>
</Warning>

## Tabby is live now!

Tabby orders are captured automatically. Refunds can be initiated from Shopify admin panel and will reflect on Tabby Merchant Dashboard, Customer Portal and Settlements.

## Limitations and Known Constraints

### Language Settings

The locale for Tabby Hosted Payment Page and Payment Method will be set based on the store's language, Tabby supports English and Arabic. If the locale is not supported, English is used by default. You can configure your store's language in your Shopify admin under Settings -<span>></span> Languages.

### Order Number Update

When an order is placed in Shopify, a payment id is set in the Shopify order timeline information under the "payment was processed on tabby." section, within the "**Information from the gateway**" subsection. This payment id is set in the Tabby order's "reference\_id" (order number). Shopify does not share the <a href="https://community.shopify.com/c/shopify-apps/getting-the-order-number/td-p/1429420">Shopify order number</a> for this payment app integration and Tabby is not able to match the Shopify order number or order number in the Tabby order. The Webhooks allow to update order number or Tabby Merchant Dashboard, Customer Portal and Settlements.

<img alt="Order number" />

### Order Editing

Please note that order details editing (as order lines, customer details, etc.) will be reflected in Shopify Dashboard only and will not updated for the payment on Tabby Merchant Dashboard, Customer Portal and Settlements.

### Order Lines

Shopify doesn't share order data via the Payment App and Shopify does not share any order line data for non-product order lines, e.g. VAT/taxes, discounts, surcharges, tip, etc. Tabby orders will have necessary Order Lines data after Webhook installation.

### Order Tagging

Tabby Payment App cannot currently set tags on a Shopify order. You can use the <a href="https://apps.shopify.com/flow">Shopify Flow app</a> (free and <a href="https://help.shopify.com/en/manual/shopify-flow">available on all Shopify plans</a>) which can set order tags within a flow for Tabby orders.

### Payment Method Presentation

The Tabby payment method name is provided with English and Arabic translations out of the box.

To reorder or hide payment methods in Shopify checkout, use Shopify's <a href="https://help.shopify.com/en/manual/checkout-settings/checkout-customization">checkout customizations</a> powered by <a href="https://shopify.dev/docs/api/functions/latest/payment-customization">Payment Customization Functions</a> — either via a Functions-powered app from the Shopify App Store, or via Checkout Blocks (Shopify Plus). The legacy checkout scripts (Script Editor) <a href="https://shopify.dev/changelog/shopify-scripts-will-be-deprecated-on-june-30-2026">stopped executing on June 30, 2026</a> and can no longer be used for payment method customization.

Customizations of the Tabby payment method presentation (logo, footer text) are currently supported only for Shopify Plus merchants. If you implement your own custom snippet, notify your Tabby account manager so we can keep your integration in sync with upcoming changes.

### Domain Filtering

Payment App uses a different hosted payment page URL: `checkout.tabby.ai` (UAE) or `checkout.tabby.sa` (KSA).
Merchants that filter this domain in Google Analytics will need to update their GA configurations accordingly.

### Market Limitation

Tabby Payment App accept orders only for the billing addresses in the markets of KSA and UAE. Customers for non-supported regions based on the order's currency are shown an error message on page load that the Tabby order cannot be processed.

We recommend limiting Tabby's visibility at checkout to the countries where your store works with Tabby — has a signed contract and an active integration. You can hide Tabby for other countries using Shopify's <a href="https://help.shopify.com/en/manual/checkout-settings/checkout-customization">checkout customizations</a> (available on all Shopify plans), so customers from non-supported regions don't see the error message.

### Multi-Currency Processing and Currency Conversion

Tabby processes payments in the following currencies: SAR (SR) and AED (Dhs), which must correspond to the customer's billing address. Tabby Payment App is compatible with all Shopify stores, regardless of their base currency.

If the store’s base currency differs from the customer’s billing currency, currency conversion will be applied, and the converted amount will be displayed at Tabby checkout. Customer transactions and merchant settlements will be processed in the customer’s billing currency.

Currency conversion is also applied between supported currencies if the store’s base currency differs from the customer’s billing currency.

Please note that to enable conversion, the “Enable Multi-Currency Processing” option must be selected in the Tabby settings.

### Inventory Lock Limitation and Inventory Stock Check

When a customer places an order with an alternative payment integration, such as Tabby Payment App, Shopify redirects to the payment method but does not lock the order's product inventory and thus stock inventory cannot be guaranteed.

However, Tabby can check inventory immediately after payment is completed but before the order is created in Shopify. If an item goes out of stock during the payment process, the funds will be refunded to the customer, and the Shopify order will not be created.

To enable this functionality, please turn on the **Check Inventory Stock** feature in Tabby settings in your Shopify admin panel.
Note that this feature only works when the following settings are applied to your products in Shopify settings:

* **Inventory tracking** is enabled
* **Continue selling when out of stock** setting is disabled

### Additional Request of the Phone Number

Shopify may not share the customer's phone number with payment integrations at checkout (for example, when email is required instead of phone). Tabby fetches the phone number via the Shopify Webhooks set up during the <a href="/e-commerce-platforms/shopify/shopify-plugin-installation#installation-steps">Installation Steps</a>. If the webhooks are not set up, Tabby will ask the customer to enter the phone number again within our Hosted Payment Page.

### Checkout Error Limitation

*"There was an issue processing your payment. Try again or use a different payment method." –* this message can happen for tech/authorization reasons only. The most common reason (for new integrations) is that the API keys haven't been populated fully. You can check the API credentials at <a href="https://merchant.tabby.ai/">merchant.tabby.ai</a> (KSA: <a href="https://merchant.tabby.sa/">merchant.tabby.sa</a>). Also, this message appears if country in shipping or billing address is different from country (countries) that your Tabby account is signed for. It can also appear if your integration hasn't been set up on the Tabby side yet — in this case contact Tabby partner support at `partner@tabby.ai` / `partner@tabby.sa`.

<img alt="Checkout error limitation" />

### Redirection for Background Pre-Scoring Rejection

Tabby now redirects the customers to our internal rejection screens where we explain the reason and advise how to avoid this rejection if possible. Customers may see the general rejection explanation (can't be avoided), too high cart total and too low cart total rejections (can be skipped by adjusting the cart total).

### The Amount Paid by the Customer to Tabby Doesn't Match the Shopify Order Total

If customers update a related, but different Shopify session separately from the Shopify session used to place the Tabby order, the order totals between the Shopify and Tabby orders may not match, but the amount "Paid by customer" for the Shopify order should always match the Tabby order total. While not ideal, this is working as expected and designed. Care should be taken to only fulfill order line items paid for by the customer.

### Feedback and Support

If additional support is needed, email `partner@tabby.ai` / `partner@tabby.sa` (please include your Shopify store name and add your Account Manager in CC) for specific Tabby support.

Customer Tabby Support available at `help@tabby.ai` / `help@tabby.sa`

<a href="https://community.shopify.com">[https://community.shopify.com](https://community.shopify.com)</a> is a good place for Shopify questions, support, and feedback, in addition to <a href="https://help.shopify.com/">[https://help.shopify.com/](https://help.shopify.com/)</a>


# Shopify Snippets
Source: https://docs.tabby.ai/e-commerce-platforms/shopify/shopify-snippets

Add Tabby promotional snippets to your Shopify product and cart pages.

Tabby snippets let your customers know they can split their payments with Tabby in your store. Snippets appear on the product and cart pages and may help improve conversion.

<Warning>
  <div>
    <span>Please note that snippets alone do not activate Tabby as a payment method in your store and don’t affect payment processing. Before adding snippets, make sure Tabby is already integrated and visible on your checkout page. </span>
  </div>
</Warning>

## Adding Tabby Snippets on Product Pages

Here you may see a video on **How to add Tabby snippet to product pages on Shopify**:

<video alt="How to add Tabby snippet to product pages on Shopify" />

1. In your Shopify admin, go to **Online Store → Themes**.
2. Click the **Customize** button on your current theme.
3. At the top of the screen, click **Home page**, then choose **Products → Default product**.
4. In the left-side menu, add a block, click **Apps** and choose **Tabby Installments**.

<Warning>
  <div>
    <span>If your theme doesn’t allow adding a block, please navigate to </span>
    <a href="#manual-snippet-installation">Manual Snippet Installation</a>
  </div>
</Warning>

5. Drag the **Tabby Installments** block to a desirable position — ideally just below the price.
6. Click **Save** and check your storefront to make sure the snippet appear properly.

If the installments don’t display correctly, your theme may not be fully compatible with default Tabby snippets. In that case, we recommend using “No-price” snippets, which don’t show installment amounts.

To activate “No-Price” snippets, please click on the **Tabby Installments** block and switch the **Enable “No-price” Snippet** toggle to the **on** position. Don't forget to save the changes.

## Adding Tabby Snippets on Cart Page

Here you may see a video on **How to add Tabby snippet to cart page on Shopify**:

<video alt="How to add Tabby snippet to cart page on Shopify" />

1. In your Shopify admin, go to **Online Store → Themes**.
2. Click the **Customize** button on your current theme.
3. At the top of the screen, click **Home page**, then choose **Products → Cart**.
4. In the left-side menu, add a block, click **Apps** and choose **Tabby Cart Page**.

<Warning>
  <div>
    <span>If your theme doesn’t allow adding a block, please navigate to </span>
    <a href="#manual-snippet-installation">Manual Snippet Installation</a>
  </div>
</Warning>

5. Drag the **Tabby Cart Page** block into a suitable spot.
6. Click **Save** and verify that the snippets appear correctly on the storefront.

If installments are incorrect, you can switch to a simplified "No-price" version of the snippet.

To activate "No-price" snippets, please click on the **Tabby Cart** block and switch the **Enable “No-price” Snippet** toggle to the **on** position. Don't forget to save the changes.

This is how the snippets look on the storefront:

<div>
  <div>
    <h4>Default snippet</h4>

    <img alt="Tabby snippet on product page" />

    <img alt="Tabby snippet on cart page" />
  </div>

  <div>
    <h4>"No-price" snippet</h4>

    <img alt="Tabby no-price snippet on product page" />

    <img alt="Tabby no-price snippet on cart page" />
  </div>
</div>

## Manual Snippet Installation

Some Shopify themes may not support adding blocks on product pages. In such cases, the Tabby snippets need to be added manually. For this, you should create a file with the snippet code in your theme and render it on your product page.

### Step 1. Create a file

1. In the Shopify Admin panel, click **Online Store** → **Themes**
2. On the Themes page, click the **“…”** → **Edit code**
3. In the navigation menu on your left, click the **Snippets** folder and click the symbol of adding a new file
4. Name it **tabby-installments.liquid**

### Step 2. Add code

1. Copy one of the following codes and paste it into the file you've created.

   We offer two variants of snippets: **default snippets** with installments and **"No-price" snippets**. The "No-price" code should be used if the default snippets don't work properly, which may be the case for some themes. Please try the "default" code first.

<span />

**Default Snippet Code**

```HTML theme={"dark"}
{%- assign lang = localization.language.iso_code -%}
{%- assign currency = cart.currency.iso_code -%}
<div id="TabbyPromo"></div>
<script>
  (function () {
    const productData = {{ product | json }};
    const currency = '{{ currency }}';
    const lang = '{{ lang }}';
    const publicKey = 'YourAPIkey';

    // "default" for AED, "ksa" for SAR. If Tabby gave your store its own
    // merchant code, put it here instead of the currency map.
    function getMerchantCode() {
      return (currency === 'AED') ? 'default' :
             (currency === 'SAR') ? 'ksa' : undefined;
    }

    // TabbyPromo expects the price with 2 decimals
    function formatPrice(value) {
      return Number(value).toFixed(2);
    }

    function getSelectedVariantPrice() {
      const variantId = document.querySelector('[name="id"]')?.value;
      if (!variantId) return null;
      const variant = productData.variants.find(v => v.id == variantId);
      if (!variant) return null;
      return variant.price / 100.0;
    }

    function refreshTabby() {
      const price = getSelectedVariantPrice();
      if (price === null || price === undefined) return;

      // Re-create the container on every refresh. Clearing the existing one and
      // re-initialising TabbyPromo into it leaves the snippet empty after the
      // first variant change.
      const oldPromo = document.getElementById('TabbyPromo');
      if (!oldPromo) return;
      const freshPromo = document.createElement('div');
      freshPromo.id = 'TabbyPromo';
      oldPromo.replaceWith(freshPromo);

      const merchantCode = getMerchantCode();
      const config = {
        selector: '#TabbyPromo',
        currency,
        price: formatPrice(price),
        lang,
        source: 'product',
        publicKey
      };
      if (merchantCode) config.merchantCode = merchantCode;
      new TabbyPromo(config);
    }

    const script = document.createElement('script');
    script.src = 'https://checkout.tabby.ai/tabby-promo.js';
    script.async = true;
    script.onload = () => {
      refreshTabby();
      const variantSelector = document.querySelector('form[action*="/cart/add"] select');
      if (variantSelector) {
        variantSelector.addEventListener('change', refreshTabby);
      }
      const variantInput = document.querySelector('input[name="id"]');
      if (variantInput) {
        variantInput.addEventListener('change', refreshTabby);
        const observer = new MutationObserver(() => {
          refreshTabby();
        });
        observer.observe(variantInput, { attributes: true, attributeFilter: ['value'] });
      }
    };
    document.body.appendChild(script);
  })();
</script>
```

<span />

**No-price Snippet Code**

```HTML theme={"dark"}
{%- liquid
  assign lang = localization.language.iso_code
-%}
<div id="TabbyPromo"></div>
<script>
  (function() {
    const script = document.createElement('script');
    script.src = 'https://checkout.tabby.ai/tabby-promo.js';
    script.async = true;
    script.onload = () => {
      const lang = '{{ lang }}';

      new TabbyPromo({
        selector: '#TabbyPromo',
        lang,
        source: 'product',
        publicKey: 'yourApiKey', // specify your apiKey, it should be a string
        merchantCode: 'yourMerchantCode', // "default" for AED, "ksa" for SAR
      }); 
    };
    document.body.appendChild(script);
  })();
</script>
<style>
  #TabbyPromo div:empty, #TabbyDialogContainer div:empty {
    display: block;
  }
</style>
```

2. Check the variables in the code:
   *For default snippet*: Put your **Public API Key** in the line 9 replacing **YourAPIkey** text.
   *For No-price snippet*: Put your **Public API Key** in the line 17. In the line 18, put your **merchant code** based on your store currency, instead of the text **yourMerchantCode**.
   Please note that you can find your Public API key in the Tabby Dashboard or in the initial email from your Tabby manager.

3. Save the changes.

### Step 3. Render the Snippet

1. First, find the file in your theme that is responsible for the page layout.
   The exact file name may vary depending on the theme, but it's typically located in the **Sections** folder.
   For product page, the most common file names are *product.liquid*, *main-product.liquid*, *price.liquid*, etc.
   For cart page, it may be *cart.liquid* or one of the files included in *templates/cart.json* (e.g., *main-cart-items.liquid*, *cart-footer.liquid*)
2. Once you find appropriate file in your theme, place the following command near the price element:

```
{% render 'tabby-installments'%}
```

3. Click Save and check if the snippets appear correctly in the desired place on the storefront.

If you notice any issues with the content of the default snippet, go back to <a href="#step-2-add-code">Step 2</a> and replace the code in the **tabby-installments.liquid** file with the “No-price” option. After saving the changes, the "No-price" snippets should appear on the storefront.


# WooCommerce Plugin Installation
Source: https://docs.tabby.ai/e-commerce-platforms/woocommerce/woocommerce-plugin-installation

Install the Tabby plugin for WooCommerce, configure your API keys, and go live.

<Note>
  Tabby works on the WooCommerce platform for all supported countries.
</Note>

## Installation Steps

<Steps>
  <Step
    title={(
  <span>
    <a href="https://merchant.tabby.ai/">
      Register with Tabby
    </a>
    <span style={{ fontWeight: 'normal', fontSize: '0.9em' }}>
      &nbsp;(KSA: <a href="https://merchant.tabby.sa/">merchant.tabby.sa</a>)
    </span>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;and fill all required business details to collect Tabby API Keys
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Install Tabby directly from the&nbsp;
    </span>
    <a href="https://wordpress.org/plugins/tabby-checkout/">
      WordPress Store
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;or download the&nbsp;
    </span>
    <a href="https://storage.googleapis.com/plgns/woo-latest.zip">
      plugin archive
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;and&nbsp;
    </span>
    <a href="/e-commerce-platforms/woocommerce/woocommerce-plugin-installation#manual-plugin-installation">
      install manually
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <a href="/e-commerce-platforms/woocommerce/woocommerce-plugin-installation#configure-tabby-as-a-payment-method">
      Configure Tabby
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;as a payment method and&nbsp;
    </span>
    <a href="/e-commerce-platforms/woocommerce/woocommerce-plugin-installation#enable-autoupdates">
      enable autoupdates
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Copy the Live Public and Secret keys from the&nbsp;
    </span>
    <a href="https://merchant.tabby.ai/business-profile/stores">
      Merchant Dashboard
    </a>
    <span style={{ fontWeight: 'normal', fontSize: '0.9em' }}>
      &nbsp;(KSA: <a href="https://merchant.tabby.sa/business-profile/stores">merchant.tabby.sa</a>)
    </span>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;and paste them into the necessary fields
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <a href="/e-commerce-platforms/woocommerce/woocommerce-plugin-installation#test-your-integration">
      Test your integration
    </a>
  </span>
)}
  />
</Steps>

### Manual Plugin Installation

1. Go to “Plugins” in your WooCommerce admin panel
2. Click “Add new” -> “Upload plugin”
3. Choose the downloaded archive in zip format
4. Click “Install now” and click “Activate plugin”

### Configure Tabby as a Payment Method

1. Go to ***WooCommerce -> Settings -> Tabby API*** and enter the **Public API Key** and **Secret API Key**
2. Save plugin changes
3. Enable Tabby as a Payment method in ***WooCommerce -> Settings -> Payments***, parameter "**Pay later with Tabby**"

Find below the example of Tabby API settings:

<img alt="Tabby API settings 1" />

<img alt="Tabby API settings 2" />

<img alt="Tabby API settings 3" />

### Enable Autoupdates

1. Find Tabby in the list of installed plugins
2. Click “Enable auto updates”

### Test Your Integration

<Warning>
  This testing is performed on Production keys -> it means you will not be able to complete testing payment using testing credentials. If you want to get Testing keys - kindly request `partner@tabby.ai` / `partner@tabby.sa` to provide you with them.
</Warning>

Follow the steps to verify the integration is set up properly:

1. Add any product to a cart
2. Go to your checkout page
3. Enter Tabby <a href="/testing-guidelines/testing-credentials">Test Credentials</a> based on the country on the checkout page (**important** to use email and phone number for **positive flow** which are provided in Tabby documentation)
4. Make sure that you've been redirected to Tabby HPP
5. You can't proceed with the payment using the test credential - it is an expected result since you already use the Production keys
6. Click on **Back to Store** button, confirm cancellation and make sure that you've been successfully redirected back to the checkout page.

If all steps are passed successfully - you are live and customers can pay with Tabby!

#### Tabby is not Present on Checkout

In case Tabby is not present on Checkout - kindly review the following possible options:

* needed countries are enabled in ***WooCommerce -> Settings -> Tabby API***, parameter "**Allowed Countries**"
* Tabby payment method is enabled in ***WooCommerce -> Settings -> Payments***, parameter "**Pay later with Tabby**"
* country-currency pair is specified correctly (UAE-AED, KSA-SAR, etc.). If not - install any currency switcher available on the WordPress store to ensure multi-currency support (it is a <a href="/e-commerce-platforms/woocommerce/woocommerce-plugin-installation#multi-currency-support">known constraint</a>)
* option "**Payment gateway**" is selected in ***WooCommerce -> Settings -> Tabby API***, parameter "**Plugin mode**"

If these parameters are set up accordingly and Tabby still does not appear on Checkout - kindly email `partner@tabby.ai` / `partner@tabby.sa` (please, include your WooCommerce store name and add your Account Manager in CC) for specific Tabby support.

## Specific Settings

### No Price snippet

It is possible to turn on non standard Tabby snippets in ***WooCommerce -> Settings -> Tabby API***, parameter ***Tabby promotions theme*** should have **:non standard** specified:

<div>
  <img alt="Tabby promotions theme" />

  <p>Tabby promotions theme</p>
</div>

<img alt="No price snippet" />

<div>
  <img alt="No price pop-up" />

  <p>No price snippet</p>
</div>

### Promotions Only Mode

It is possible to set Tabby plugin for promotion purposes only: PDP / Cart snippets will be displayed, but Tabby will not be present among payment methods on Checkout.

For this setup go to ***WooCommerce -> Settings -> Tabby API***, parameter ***Plugin mode*** and select ***Promo only*** there:

<div>
  <img alt="Promo only mode" />

  <p>Promo only mode</p>
</div>

## Limitations and Known Constraints

### Multi-Currency support

In case you integrate Tabby in different countries - please, make sure that you use an automated currency converter on the checkout as Tabby requires currency to match the customer’s country depending on the shipping country.

You can use any currency switcher plugin available on the WordPress store.

<Note>
  Tabby currently operates in KSA and UAE.
</Note>

If you use a currency switcher plugin, make sure to add Tabby payment method for every supported currency. To do that, go to ***Admin → Multi currency → Checkout → Checkout currency*** and add Tabby payment method next to each supported currency.

<div>
  <img alt="WooCommerce Multi-Currency checkout currency settings" />

  <p>Multi currency → Checkout → Checkout currency</p>
</div>

### Logo size Issue

The issue is relevant for WordPress sites with WooCommerce. It is connected with the different page templates and themes using.

Because the Tabby plugin can't control the specific theme usage at partners' sites, you may need to modify the CSS file to have the following parameters:

`max-width: 50px;`<br />
`max-height: 30px;`

### Feedback and Support

If you face any issues during testing, don't hesitate to get in touch with `partner@tabby.ai` / `partner@tabby.sa` with the store link, issue description, and screenshots or screencasts of the observed behaviour.


# WooCommerce Product Catalogue
Source: https://docs.tabby.ai/e-commerce-platforms/woocommerce/woocommerce-product-catalogue

Enable the WooCommerce Product Catalogue feature to list your store's products on the Tabby Shop.

We've introduced an exciting new feature to the Tabby WooCommerce plugin – the **Product Catalogue Feature**, designed to help you list your store’s products seamlessly on the Tabby Shop.

The feature is enabled by default in new plugin versions starting from 5.0.8.

Update the plugin or download the latest version from the WordPress store: <a href="https://wordpress.org/plugins/tabby-checkout">[https://wordpress.org/plugins/tabby-checkout](https://wordpress.org/plugins/tabby-checkout)</a> or by enabling auto-updates on **Plugins section**.

<img alt="Plugins section" />

Check that the setting is enabled in the Tabby API options located at:<br />
**WooCommerce -> Settings -> Tabby API -> "Share product feed with Tabby."**

<img alt="Product feed parameter" />

**Key features:**

* **Automated Product Listing**: Easily list your entire WooCommerce store inventory on the Tabby Shop without manual intervention.
* **Real-Time Stock Updates**: Keep your product listings up-to-date effortlessly, as the plugin automatically syncs inventory availability and reflects out-of-stock items in real time.
* **Increased Visibility**: Showcase your products to a broader audience by making them visible to all Tabby app users.
* **Traffic Generation**: Drive interested shoppers directly to your WooCommerce store, increasing clicks and potential sales.


# Zid
Source: https://docs.tabby.ai/e-commerce-platforms/zid



<Note>
  Tabby works on the Zid platform for the countries KSA and UAE.
</Note>

1. <a href="https://merchant.tabby.ai/">Register with Tabby</a> (KSA: <a href="https://merchant.tabby.sa/">merchant.tabby.sa</a>) and fill all required business details to collect Tabby API Keys.
2. Fill in the keys using the instruction below:

<img alt="Tabby & Zid" />

<img alt="Step 1" />

<img alt="Step 2" />

<img alt="Step 3" />

<img alt="Step 4" />

<img alt="Contact information" />


# Tabby docs for AI & LLMs
Source: https://docs.tabby.ai/introduction/ai-tools

Use the Tabby documentation with ChatGPT, Claude, Cursor and other AI tools — via llms.txt, per-page Markdown, and the hosted MCP server.

These docs are built to be read by AI assistants and coding agents, not just people. Every page is available as plain Markdown, the whole site is exposed as `llms.txt`, and there is a hosted MCP server you can connect your AI tool to.

## Read any page as Markdown

Use the **Copy page** / **Open in ChatGPT** / **Open in Claude** menu at the top of any page, or append `.md` to a docs URL to get the raw Markdown:

```
https://docs.tabby.ai/pay-in-4-custom-integration/quick-start.md
```

## llms.txt

We publish the [llms.txt standard](https://llmstxt.org) so an LLM can discover and ingest the documentation in one pass:

* **[llms.txt](https://docs.tabby.ai/llms.txt)** — an index of every page with titles and descriptions.
* **[llms-full.txt](https://docs.tabby.ai/llms-full.txt)** — the full content of the documentation in a single file.

Paste either link into your AI tool when you want it to reason over the whole integration guide.

## MCP server

Tabby's documentation is also available as a [Model Context Protocol](https://modelcontextprotocol.io) server, so AI tools can search and read the docs directly:

```
https://docs.tabby.ai/mcp
```

The server exposes a documentation search tool and a read-only filesystem of every page and the OpenAPI spec — your assistant can look up endpoints, payloads and integration steps on demand.

<CodeGroup>
  ```json Cursor theme={"dark"}
  {
    "mcpServers": {
      "tabby-docs": {
        "url": "https://docs.tabby.ai/mcp"
      }
    }
  }
  ```

  ```bash Claude Code theme={"dark"}
  claude mcp add --transport http tabby-docs https://docs.tabby.ai/mcp
  ```
</CodeGroup>

<Note>
  This MCP server covers the **documentation** only. It does not call the Tabby API or move money —
  use the [API Playground](/api-reference/overview) and your secret key for live requests.
</Note>


# F.A.Q.
Source: https://docs.tabby.ai/introduction/faq



<div>
  <p>
    This page gives you answers to the most common questions about Tabby operating.
  </p>
</div>

## Where can I find credentials to use Tabby?

### Live Credentials

Live API keys can be obtained:

* from Tabby Merchant Dashboard for **Self-Hosted plugin** integration listed in the Quick Start section.
* by contacting Tabby account manager after QA testing carried out by Tabby team is completed for **Custom API** integration. Also refer to <a href="/introduction/faq#test-credentials">Test Credentials</a>.

If the credentials are missing or wrong, Tabby will respond with <code>401 Not authorized</code>. Error codes for a session creation request can be found here: <a href="/api-reference/response-codes">API Error Codes</a>.

In this case kindly contact Tabby Partner Support at `partner@tabby.ai` (or `partner@tabby.sa` for KSA) or reach out to your assigned Business Manager. When doing so, kindly include:

1. your store name as registered with Tabby;
2. your integration details:
   * website URL or app name (for online integrations);
   * description of offline integration, if applicable.

### Test Credentials

To test your custom integration with Tabby you need to use the following:

* your testing keys, starting with <code>pk\_test / sk\_test</code>;
* download the Postman API Collection from here: <a href="https://docs.tabby.ai/testing-guidelines/postman-api-collections">Postman API Collection</a>;
* or use Tabby endpoints provided here: <a href="https://docs.tabby.ai/api-reference/">API Playground</a>;

<Note>
  Tabby identifies live or test environment based on the keys used. The endpoints for test are the same as for live.
</Note>

* review the <a href="https://docs.tabby.ai/pay-in-4-custom-integration/full-testing-checklist">Full Testing Checklist</a>;
* check the Testing Scenarios based on your type of integration:
  * Online Custom integration: <a href="https://docs.tabby.ai/testing-guidelines/testing-credentials">Testing Scenarios for Online Custom Integration</a>
  * Offline Integrations -> POS: <a href="https://docs.tabby.ai/offline-payment-methods/pos-integration#testing-scenarios">Testing Scenarios for POS</a>
  * Offline Integrations -> Custom Payment Links: <a href="https://docs.tabby.ai/offline-payment-methods/custom-payment-links#testing-scenarios">Testing Scenarios for Custom Payment Links</a>

## Does Tabby provide any sandbox environment for testing?

Tabby provides a single environment for both integration and live launch. Use <code>api.tabby.ai</code> for UAE, or <code>api.tabby.sa</code> for KSA (see <a href="/api-reference/overview#base-urls">Base URLs</a>). Payments can be created:

* in test mode using **Test API keys** from merchants' DEV and Stage environments;
* in live mode using **Live API keys**. Live keys are shared after development is completed and QA by Tabby team is done and confirmed.

<Note>
  Checkout, Payments and Payment webhooks are available for both test and live payments, while Disputes and Dispute webhooks are supported for live payments only.
</Note>

## What should I do if my platform is not present in the list of supported platforms?

In such case the integration is considered an <a href="https://docs.tabby.ai/pay-in-4-custom-integration/quick-start">Online Custom Integration</a> - kindly follow its integration guidelines.

## What is the difference between Close and Capture API calls?

The main difference between these API calls is that when the **CLOSE** API call is used - you cancel the payment from your side, and Tabby will not release funds to you.

However, when you use **CAPTURE** API call - you confirm all is good with the order from your side, Tabby will release funds to you.

* Close API call cancels the payment without capturing it. The downpayment is returned to the customer, the payment gets status <code>CANCELLED</code> on Tabby Merchant Dashboard: [https://docs.tabby.ai/api-reference/payments/close-a-payment](https://docs.tabby.ai/api-reference/payments/close-a-payment)
* Capture API call captures the payment, the payment gets status <code>CAPTURED</code> on Tabby Merchant Dashboard: [https://docs.tabby.ai/api-reference/payments/capture-a-payment](https://docs.tabby.ai/api-reference/payments/capture-a-payment)

## How can I verify Payments via Webhooks?

Main article: <a href="https://docs.tabby.ai/pay-in-4-custom-integration/webhooks">Webhooks</a>.

There are 3 ways to secure the Webhook notifications:

* allow these IP-addresses for Webhooks:

```
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
```

* add static <code>AUTH HEADER</code> during webhook registration: [https://docs.tabby.ai/api-reference/webhooks/register-a-webhook](https://docs.tabby.ai/api-reference/webhooks/register-a-webhook)
* webhooks should be treated as notifications only. To verify the payment status, use the <code>payment\_id</code> from the webhook and call the getPayment API: [https://docs.tabby.ai/api-reference/payments/retrieve-a-payment](https://docs.tabby.ai/api-reference/payments/retrieve-a-payment)

## What should I do if Payments remain in status NEW in Tabby Merchant Dashboard?

Associated articles:

* <a href="https://docs.tabby.ai/pay-in-4-custom-integration/payment-statuses">Payment Statuses</a>;
* <a href="https://docs.tabby.ai/pay-in-4-custom-integration/payment-processing">Payment Processing</a>.

### Self-Hosted Platforms

Self-Hosted Platforms are: **WooCommerce, Shopify, Magento 2, OpenCart**.

These payments are likely lost (not linked to any created order). Merchants should select one of the options:

* either cancel them (i.e., refund the customer): [https://docs.tabby.ai/api-reference/payments/close-a-payment](https://docs.tabby.ai/api-reference/payments/close-a-payment)
* or manually create an order for such payments, as they are authorized by Tabby, and capture payments: [https://docs.tabby.ai/api-reference/payments/capture-a-payment](https://docs.tabby.ai/api-reference/payments/capture-a-payment)
* or just capture them if the orders exist.

Additionally, merchants should update the plugin to the latest version (following Tabby documentation) and check the plugin settings to prevent similar cases in the future.

### Zid and Salla Platforms

By default, everything is expected to be working successfully when live keys are saved. If you suspect an issue or have lost orders, kindly re-save the keys and contact your platform's support team to verify the situation or register webhooks to prevent such issues.

### Custom (Direct API) Integrations

Merchants may have immediate or delayed captures, meaning <code>NEW</code> statuses may simply be waiting for merchant action. However, in many cases, these payments are also lost.

Merchants should select one of the options:

* either cancel them (i.e., refund the customer): [https://docs.tabby.ai/api-reference/payments/close-a-payment](https://docs.tabby.ai/api-reference/payments/close-a-payment)
* or manually create an order for such payments, as they are authorized by Tabby, and capture payments: [https://docs.tabby.ai/api-reference/payments/capture-a-payment](https://docs.tabby.ai/api-reference/payments/capture-a-payment)
* or just capture them if the orders exist.

Merchants should also check payment logs and investigate integration issues to determine why the payment wasn't acknowledged or captured in time (following Tabby documentation).

The Integrations team can assist with investigating API calls and webhooks - kindly contact them via the integrations thread or an assigned business manager.

### Tabby Card and Payment Links

These are always expected to be Auto-Captured. If they are not - kindly provide your store name with Tabby to Tabby Partner Support `partner@tabby.ai` / `partner@tabby.sa` or to your assigned business manager.

## What is Eligibility check?

Associated articles:

* <a href="https://docs.tabby.ai/pay-in-4-custom-integration/checkout-flow#background-pre-scoring-check">Background Pre-scoring Check</a>;
* <a href="https://docs.tabby.ai/pay-in-4-custom-integration/quick-start">Integration overview</a>.

### How can I know that a customer is not eligible to use Tabby?

In the Tabby Session creation response, you can receive a status like this if a customer is not eligible to use Tabby:

```
"status": "rejected",
"configuration"."products"."installments"."rejection_reason": "not_available"
```

You need to hide Tabby payment option or show it with the General Rejection message or specific reason message depending on the <code>"rejection\_reason"</code> value:

| Reason | English | Arabic |
| - | - | - |
| General Rejection (`not_available`) | Sorry, Tabby is unable to approve this purchase. Please use an alternative payment method for your order. | نأسف، تابي غير قادرة على الموافقة على هذه العملية. الرجاء استخدام طريقة دفع أخرى. |
| `order_amount_too_high` | This purchase is above your current spending limit with Tabby, try a smaller cart or use another payment method | قيمة الطلب تفوق الحد الأقصى المسموح به حاليًا مع تابي. يُرجى تخفيض قيمة السلة أو استخدام وسيلة دفع أخرى. |
| `order_amount_too_low` | The purchase amount is below the minimum amount required to use Tabby, try adding more items or use another payment method | قيمة الطلب أقل من الحد الأدنى المطلوب لاستخدام خدمة تابي. يُرجى زيادة قيمة الطلب أو استخدام وسيلة دفع أخرى. |

For detailed implementation guide check here: <a href="/pay-in-4-custom-integration/checkout-flow#background-pre-scoring-check">Background Pre-scoring Check</a>

### What is the difference between eligibility check and checkout session creation?

Tabby's Checkout API serves two distinct purposes. Here's a side by side comparison:

| Aspect | Eligibility Check | Checkout Session Creation |
| - | - | - |
| **Purpose** | Determine if customer can use Tabby | Create payment session for actual checkout |
| **Timing** | Before showing Tabby payment method | When customer clicks "Place order" |
| **Payload** | Minimal (amount, currency, buyer) | Complete (all order details, items, shipping, merchant URLs) |
| **Response** | Status (`created` or `rejected`) + rejection reason | Status + `web_url` for redirect + `payment.id` |
| **Next Step** | Show or hide / mark unavailable Tabby payment method based on the response | Redirect to Tabby Hosted Payment Page |

### Example of a minimal payload for eligibility check

```json theme={"dark"}
{
  "payment": {
    "amount": "340.00",
    "currency": "SAR",
    "buyer": {
      "email": "otp.success@tabby.ai",
      "phone": "+966500000001"
    }
  },
  "merchant_code": "your_merchant_code"
}
```

**Key principle**: Use the same endpoint (`POST /api/v2/checkout`) but with different payload sizes for different purposes. The minimal payload is accepted **for the background pre-scoring call only** — the session you create when the customer clicks "Place order" must carry the <a href="/api-reference/checkout/session-payload-model">full payload</a> with all required fields.

### When should I perform eligibility check?

Perform the eligibility check **once per checkout session** before displaying payment methods to customer, when you have the basic order details (amount, currency, buyer.phone, buyer.email).

**Best practices:**

* **Payload**: Include as much data as possible (not just minimal payload) for better approval rates and conversion
* **Timing**: Check eligibility when customer enters checkout page with all main data available
* **Error handling**: If API times out or returns error, default to showing Tabby option (fail-safe approach) - never block checkout
* **Two separate calls**: Eligibility check (minimal/recommended data) ≠ Session creation (complete order details when customer clicks "Place order")

## How should I validate checkout session response?

Always validate the checkout session response before redirecting the customer. Here are the critical validation steps:

**Critical Validation Steps**:

1. **Check `status` field** - must be `"created"`. If `"rejected"`, show rejection message and don't redirect;
2. **Validate `web_url` presence** - never redirect without it. Show rejection message if missing;
3. **Store `payment.id`** - required for subsequent capture/refund operations.

For complete validation logic and edge cases check here: <a href="/pay-in-4-custom-integration/checkout-flow#response-and-validation">Checkout Flow - Response Validation</a>.

## Is it possible to know the rejection reason for payments?

Unfortunately, due to compliance and regulatory restrictions, Tabby is not permitted to disclose the specific rejection reasons to merchants. Customers, however, typically see a rejection message on the Tabby-hosted payment page at the time of the transaction.

If you suspect a technical issue that may be causing multiple or all transactions to be rejected - please, contact Tabby Partner Support at `partner@tabby.ai` (or `partner@tabby.sa` for KSA) or reach out to your assigned Business Manager. When doing so, kindly include:

1. your store name as registered with Tabby;
2. your integration details:
   * website URL or app name (for online integrations);
   * description of offline integration, if applicable.

## Are there any transaction limits set for my store from Tabby side?

Tabby applies transaction limits based on a combination of factors, including your industry and associated risk levels. Additionally, customer-level limits are dynamically determined based on their historical transaction behaviour with your store and with other merchants using Tabby.

For this reason, we recommend **not setting hardcoded limits** for Tabby transactions on your end, as these may conflict with Tabby's dynamic risk and approval models.

## What should I do if a customer is not redirected back to the website?

When customers finish the Tabby session, they are redirected back to your site from the Tabby Payment Page via one of the three <code>merchant\_urls</code>, with the <code>payment\_id</code> after the separator, e.g. <code>[https://your-store/success?payment\_id=string](https://your-store/success?payment_id=string)</code>:

```
"merchant_urls": {
  "success": "https://your-store/success",
  "cancel": "https://your-store/cancel",
  "failure": "https://your-store/failure"
}
```

The <code>merchant\_urls</code> should be included in a <a href="https://docs.tabby.ai/api-reference/checkout/create-a-session#body-merchant-urls">Session Creation request</a> sent to Tabby from your side.

## What should I do if I do not receive fields in a response from Tabby API?

If some fields do not return in the response:

* check the endpoint used for the request;
* check the fields format in the request - they should match those specified in the <a href="https://docs.tabby.ai/api-reference/overview">API Reference Documentation</a>;
* check responses in the <a href="https://docs.tabby.ai/api-reference/overview">API Reference Documentation</a> and that these fields are expected to be returned.

## Where can I see if Tabby is working normally?

Status Page Recommendations. Associated article: <a href="https://docs.tabby.ai/introduction/technical-requirements#status-page">Technical Requirements -> Status Page</a>.

Recommendations for status page maintenance and incidents:

* Tabby sends alerts through [https://www.tabby-status.com/](https://www.tabby-status.com/). Please, subscribe using your preferred channel for updates.
* Tabby posts alerts manually in real-time within 5-10 minutes of identifying and confirming an issue. The alerts provide details about the affected systems.
  * If Checkout or Payments APIs are affected for all countries, we recommend disabling Tabby until the next message confirms the resolution.
  * If only one country is affected, you can disable Tabby for that specific country.
  * If non-real-time systems are affected, no action is required (incident details will still be posted).
  * If you see a Scheduled Technical Maintenance notification, you can plan disabling Tabby for that duration of the maintenance window or mute monitors if the expected timeframe is less than 10 minutes, as it will recover automatically.
* If you suspect an issue with any flow, you can contact Tabby Partner Support `partner@tabby.ai` / `partner@tabby.sa` for more details. However, if you observe that Tabby APIs are not working (e.g., consistently returning 5xx or 4xx errors), please contact the Tabby Integrations Team via the integration thread or via your assigned business manager immediately to investigate and resolve the issue. In the meantime, disable Tabby until the issue is resolved.

## How does Tabby work for shoppers?

Shoppers choose Tabby at checkout — no account is needed beforehand. If they don't have one yet, it is created automatically during their first purchase.

At checkout, the shopper enters their mobile number, verifies it with an SMS code, then reviews and confirms their payment plan before the order goes through.

## Who is eligible to use Tabby?

To be eligible to use Tabby, a shopper must:

* be at least 18 years of age;
* have a valid National ID;
* have a valid debit or credit card to cover payments.

Each purchase is also approved individually — see <a href="/introduction/faq#what-is-eligibility-check">What is Eligibility check?</a>.

## If a refund is requested, will the fees or Murabaha profit be refunded too?

Yes:

* a **full refund** from the merchant returns the purchase amount plus any fee or Murabaha profit charged on that plan;
* a **partial refund** returns that fee or profit proportionally.

Murabaha profit applies in KSA only.

How a refund changes the customer's downpayment and remaining instalments: <a href="/pay-in-4-custom-integration/payment-processing#how-a-refund-affects-the-customers-instalments">Payment Processing → How a Refund Affects the Customer's Instalments</a>.

## General information

For additional support and information, you may also find helpful resources here: <a href="https://support.tabby.ai/l/en">Tabby Support Center</a>.


# Quick Start
Source: https://docs.tabby.ai/introduction/quick-start



Choose your integration type below. Use pre-built plugins for popular platforms or implement custom integration via Tabby API.

## E-Commerce Platforms

<CardGroup>
  <Card href="/e-commerce-platforms/salla" title="Salla">
    <Frame>
      <img alt="Salla" />
    </Frame>
  </Card>

  <Card href="/e-commerce-platforms/shopify" title="Shopify">
    <Frame>
      <img alt="Shopify" />
    </Frame>
  </Card>

  <Card href="/e-commerce-platforms/zid" title="Zid">
    <Frame>
      <img alt="Zid" />
    </Frame>
  </Card>

  <Card href="/e-commerce-platforms/woocommerce" title="WooCommerce">
    <Frame>
      <img alt="WooCommerce" />
    </Frame>
  </Card>

  <Card href="/e-commerce-platforms/magento-2" title="Magento 2">
    <Frame>
      <img alt="Magento 2" />
    </Frame>
  </Card>

  <Card href="/e-commerce-platforms/opencart" title="OpenCart">
    <Frame>
      <img alt="OpenCart" />
    </Frame>
  </Card>

  <Card href="/e-commerce-platforms/matjrah" title="Matjrah">
    <Frame>
      <img alt="Matjrah" />
    </Frame>
  </Card>

  <Card href="/e-commerce-platforms/odoo/odoo-plugin-installation" title="Odoo">
    <Frame>
      <img alt="Odoo" />
    </Frame>
  </Card>

  <Card href="/e-commerce-platforms/salesforce" title="Salesforce">
    <Frame>
      <img alt="Salesforce" />
    </Frame>
  </Card>
</CardGroup>

## Custom Integrations

<CardGroup>
  <Card href="/pay-in-4-custom-integration/quick-start" title="Online Custom Integration">
    <Frame>
      <img alt="Online Custom Integration" />

      <img alt="Online Custom Integration" />
    </Frame>
  </Card>

  <Card href="/offline-payment-methods/pos-integration" title="Offline: POS Integration">
    <Frame>
      <img alt="Offline: POS Integration" />

      <img alt="Offline: POS Integration" />
    </Frame>
  </Card>

  <Card href="/offline-payment-methods/custom-payment-links" title="Offline: Custom Payment Links">
    <Frame>
      <img alt="Offline: Custom Payment Links" />

      <img alt="Offline: Custom Payment Links" />
    </Frame>
  </Card>

  <Card href="/testing-guidelines/testing-credentials" title="Testing Guidelines">
    <Frame>
      <img alt="Testing Guidelines" />

      <img alt="Testing Guidelines" />
    </Frame>
  </Card>
</CardGroup>


# Technical Requirements
Source: https://docs.tabby.ai/introduction/technical-requirements



<div>
  <p>
    This page gives you the common knowledge about Tabby operating.
  </p>
</div>

## Status Page

<a href="https://www.tabby-status.com/">Tabby Status Page</a> offers live status, maintenance alerts and incident history reports for Tabby Services. Please subscribe to our Status Page to stay informed about all changes and maintenance works and be able to manage your sales according to it.

## Security Protocol

**TLS** is an industry-standard protocol for encrypting network communications and establishing the identity of websites over the Internet. Tabby API supports TLS version 1.2 and higher. Additionally, we rely on **HTTPS** to ensure all data is transmitted securely.

Strongly restricted cipher suites for compliance with the Payment Card Industry Data Security Standard. Enhances payment card data security:

```
TLSv1.3:
TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256

TLSv1.2:
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
```

## Allowlist

Tabby uses several IP addresses when sending webhook requests and new IPs may be utilized as our systems scale and new resources are brought online. Please allow this list of IP addresses to prevent webhook calls from failing:

```
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
```

## Data Format

Request and response data are formatted as **JSON**. The following data formats are used across all Tabby APIs:

### Currency

We use the
<a href="https://en.wikipedia.org/wiki/ISO%5F4217">ISO 4217</a> standard for defining currencies.

```JSON theme={"dark"}
{
  "currency": "AED"
}
```

### Amount

Amounts are **decimal strings in major currency units** — e.g. one hundred dirhams is `"100.00"`, not `10000`. Currency codes follow the
<a href="https://en.wikipedia.org/wiki/ISO%5F4217">ISO 4217</a> standard.

Tabby allows to send:

* up to **2 decimals** for *AED* and *SAR*.

```JSON theme={"dark"}
{
  "amount": "100.00"
}
```

**Keep the totals consistent.** `payment.amount` must equal the sum of your order lines: `Σ (item.unit_price × quantity − item.discount_amount) + tax_amount + shipping_amount − order.discount_amount`. The classic mistake is rounding twice — compute each line, round it **once** to the currency's decimals, then sum the already-rounded values to produce `amount`. Deriving `amount` independently from the cart (or rounding the grand total differently than the lines) produces off-by-a-fils mismatches that fail validation and QA.

### Phone

The following mobile phone formats are accepted, using the UAE +971 mask and phone number as an example:

```JSON theme={"dark"}
{
  "phone": "+971500000001" // OR "971500000001", "500000001", "0500000001"
}
```

### Merchant Code

Merchant code is a unique store identifier under one brand and should be sent as a string value. Usually <code>merchant\_code</code> represents a merchant country or a specific store within the country.

### Dates

The
<a href="https://en.wikipedia.org/wiki/ISO%5F8601">ISO 8601</a> standard with combined Date and Time in UTC for all API dates. The exceptions to this are <code>dob</code> fields where we accept values in the **YYYY-MM-DD** format.

```JSON theme={"dark"}
{
  "registered_since": "2019-08-24T14:15:22Z",
  "dob": "2019-08-24"
}
```

### Locale

Operating in the GCC region, Tabby supports the English and Arabic languages and refers to the
<a href="https://en.wikipedia.org/wiki/IETF%5Flanguage%5Ftag#List%5Fof%5Fcommon%5Fprimary%5Flanguage%5Fsubtags">RFC 1766</a> standard.

```JSON theme={"dark"}
{
  "lang": "en"
}
```

### String Length Validation

We are processing a maximum of 255 symbols in the **"string"** field.

### Allowed characters in redirect URLs ("success", "cancel", "failure")

1. Latin letters (a-z, A-Z)
2. Arabic letters (ء-ي)
3. Digits (0-9)
4. Special characters - \ | / : ;., + \{}? & @ = # %

## Rate limit

API rate limiting is implemented to maintain stable operations for Tabby services. If an excessive number of requests are sent in a short time, rate limiting may be applied to your requests.

The response will include an HTTP status code <code>429 error</code> when rate limiting is triggered.

Rate limits are enforced per API Key and are measured on a per-operation basis. Operations are categorized into **Create Session** and **Payment** operations.

* **Live API Keys**: The rate limit is 200 Create Session operations per 10 seconds, while other operations are limited to 100 requests per second.
* **Testing API Keys**: The rate limit is 10 requests per 10 seconds for Create Session operations and 50 requests per second for other operations.

  <Note>
    Tabby doesn't allow any Performance testing with the Production APIs involved. Kindly exclude Tabby method from checkout when executing load or stress testing.

    These Keys and IP addresses might be automatically limited by a firewall. Also such Test or Live API keys payments might be limited manually upon detection.
  </Note>

## Authentication

To authenticate with Tabby you will use your API credentials and HTTP basic auth.

These credentials consist of two elements:

* **Secret Key**: Associated with your merchant account, this key is used to authorize requests to Tabby’s Checkout and Payments APIs. Send it as a **Bearer token** in the `Authorization` header with every request:

```bash theme={"dark"}
curl https://api.tabby.ai/api/v2/checkout \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

* **Public Key**: Associated with your merchant account, this key is used for promo snippets, plans, and customization support.

Live API keys can be obtained:

* from Tabby Merchant Dashboard for **Self-Hosted plugin** integration;
* by contacting Tabby account manager after QA testing carried out by Tabby team is completed for **Custom API** integration.

If the `Authorization` header is missing, doesn't use the `Bearer` scheme, or carries a wrong key, Tabby responds with <code>401 Not authorized</code> — see <a href="/api-reference/response-codes">API Error Codes</a>.

## Errors

Tabby APIs use HTTP status codes alongside error objects to handle errors. When an API call fails, Tabby responds with a <code>4xx</code>/<code>5xx</code> status code and a JSON body containing <code>status: "error"</code>, an <code>errorType</code> value, and either a single <code>error</code> message or an <code>errors</code> array for field-level validation failures.

The <code>error</code> value is a human-readable English message to aid in debugging. It is not meant to be displayable to end-users, nor to be machine-readable — log it to assist in debugging, but never parse it. Branch your handling on the HTTP status code and <code>errorType</code> instead.

The full list of errors per endpoint, with example bodies and remediation, lives on the <a href="/api-reference/response-codes">API Error Codes</a> page.

## Supported Browsers & Devices

<Check>
  We support all common-spread desktop and mobile browsers and mobile devices.
</Check>

As part of our development process, we test among all major browsers and across different versions of browsers. However, we do not support browsers that no longer receive security updates. Please, contact us if you have an issue with Tabby Checkout on a specific browser so we can improve its support.

### Browsers & Versions

Chrome, Firefox, Safari and Microsoft Edge are supported on all platforms for three years from the version release. We also test across different mobile platforms: iOS 12 and above and Android 7 and above.


# What is Tabby?
Source: https://docs.tabby.ai/introduction/what-is-tabby



Tabby is MENA's biggest Buy Now Pay Later, operating in KSA and UAE. Tabby lets merchants grow their business by offering their shoppers flexible payments, and is constantly growing its product offering.

* Pay in Installments - Split your purchase into several payments
  * Online - easily through nearly any e-commerce platform
  * In-Store - with the Tabby Card, through paylinks or with a QR code
* Pay next month - Pay for groceries, food, rides at the end of the month

<img alt="Tabby payment method on Checkout" />


# Drive more sales with Tabby
Source: https://docs.tabby.ai/marketing/toolkit



Customers who know you offer Tabby spend more and come back more often. The Marketing Toolkit has everything you need to spread the word: on your site, in your store and everywhere in between.

Approved messaging, brand guidance, logos and ready-to-use assets for your website, app, email, social and store, now in one deck.

<a href="https://www.figma.com/deck/kNKIJEr2U4DsEcQQWOBw73/Tabby-%E2%80%94-Merchant-guidelines_EN?node-id=7-1460&scaling=min-zoom&content-scaling=fixed&page-id=0%3A1">Explore the marketing toolkit</a>


# Custom Payment Links Integration
Source: https://docs.tabby.ai/offline-payment-methods/custom-payment-links



## Integration Overview

This integration allows customers to pay using Tabby by receiving a payment link via SMS/Push. The flow involves:

1. Creating a payment session
2. Sending payment link to customer
3. Customer completes payment on their device
4. Merchant receiving payment confirmation

<Note>
  To implement sending payment link via SMS/Push from Tabby side to a customer a POST request to an API endpoint `/api/v2/checkout/{id of session}/send_hpp_link` should be triggered from your side first. Instructions on how and when to implement it can be found below.
</Note>

## Quick Reference

| **API Endpoint** | **Purpose** | **Method** |
| - | - | - |
| `/api/v2/checkout` | Create session and payment | POST |
| `/api/v2/checkout/{id of session}/send_hpp_link` | Send payment link via SMS/Push | POST |
| `/api/v2/payments/{payment.id}` | Retrieve payment status | GET |
| `/api/v2/checkout/{id of session}/cancel` | Cancel session | POST |

| **Key Status Codes** | **Description** |
| - | - |
| `CREATED` | Payment initiated, waiting for completion |
| `AUTHORIZED` | Payment approved, not yet captured |
| `CLOSED` with "captures" object | Payment approved and captured successfully |
| `REJECTED` | Payment declined |
| `EXPIRED` | Session/payment expired or cancelled |

## Steps to Integrate Tabby using Custom Payment Links

<Steps>
  <Step
    title={(
  <span>
    <a href="https://merchant.tabby.ai/">
      Register with Tabby
    </a>
    <span style={{ fontWeight: 'normal', fontSize: '0.9em' }}>
      &nbsp;(KSA: <a href="https://merchant.tabby.sa/">merchant.tabby.sa</a>)
    </span>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;and finish the application
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    Collect the Test API Keys and Merchant codes from Tabby Merchant Dashboard or your Tabby Account manager
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Set up the&nbsp;
    </span>
    <a href="/offline-payment-methods/custom-payment-links#create-session-and-payment-using-checkout-api">
      Tabby session creation from your terminal
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Make sure a payment link is successfully&nbsp;
    </span>
    <a href="/offline-payment-methods/custom-payment-links#customer-payment-options">
      sent as an SMS to the customer
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Set up&nbsp;
    </span>
    <a href="/offline-payment-methods/custom-payment-links#payment-processing">
      Payment Processing
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;on your Backend
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Once the payment is complete -&nbsp;
    </span>
    <a href="/offline-payment-methods/custom-payment-links#print-a-receipt">
      print the receipt for the customer
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <a href="/offline-payment-methods/custom-payment-links#testing-scenarios">
      Test your Integration,
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;contact Tabby Integrations Team in the Integration email thread to complete the testing process
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    After successful testing passed receive the Live API keys and deploy to production
  </span>
)}
  />
</Steps>

## Integration Flow

```mermaid theme={"dark"}
sequenceDiagram
    autonumber
    participant Customer
    participant POS as POS Terminal
    participant Provider as POS Backend
    participant Checkout as Tabby Checkout
    participant TabbyAPI as Tabby API

    Customer ->>+ POS: Request to pay with Tabby
    POS ->>+ Provider: Initiate payment
    Provider ->>+ TabbyAPI: POST /api/v2/checkout<br/>{ amount, buyer.phone, ... }
    TabbyAPI -->>- Provider: Response<br/>{ id of session, status of session, payment.id, web_url }

    alt "status" of session == "created"
        Provider ->>+ TabbyAPI: POST /api/v2/checkout/{id of session}/send_hpp_link
        TabbyAPI -->>- Customer: Send checkout link via SMS/Push
        Provider -->> POS: Display "Waiting<br/>for customer payment"
        Note right of Customer: Customer receives<br/>and opens the link
    else "status" of session == "rejected"
        Provider -->> POS: Return "Payment rejected"
        POS -->> Customer: Show failure screen
        Note right of Customer: A different payment method <br />should be selected
    end

    Customer ->>+ Checkout: Open Tabby Checkout and go through payment steps
    loop Tabby checkout steps
    Checkout -->> Customer: Guide through required steps
    end

    opt
        alt Cashier cancels
          POS -->> Provider: Cancel request
          Provider -->> TabbyAPI: POST /api/v2/checkout/{id of session}/cancel
        else Customer cancels
          Customer -->> Checkout: Clicks 'Cancel' button on Tabby Checkout Page
        end
    end

    Provider ->>+ TabbyAPI: Check payment status<br/>(GET /api/v2/payments/{payment.id})
    TabbyAPI -->>- Provider: { payment.status: <br />AUTHORIZED | CLOSED | REJECTED | EXPIRED }
    Note over Provider,TabbyAPI: Or receive webhook with the same status

    alt payment.status == <br />"AUTHORIZED" OR "CLOSED"
        Provider -->> POS: Payment successful
        POS -->> Customer: Show success screen, Print receipt
    else payment.status == <br />"REJECTED" or "EXPIRED"
        Provider -->> POS: Payment failed
        POS -->> Customer: Show failure screen
    end
```

## Create Session and Payment Using Checkout API

Call the <a href="https://docs.tabby.ai/api-reference/checkout/create-a-session">Create a session API</a>. The required payload parameters for the session:

```JSON theme={"dark"}
{
  "payment": {
    "amount": "string", // Up to 2 decimals for AED and SAR, e.g. 100.00
    "currency": "string", // Use the ISO 4217 standard for defining currencies: AED, SAR
    "buyer": {
      "phone": "string" // Required for sending Payment link
    },
    "order": {
      "reference_id": "string", // Merchant's Order Number to match the order with the payment.id
      "items": [
        {                    
          "title": "string", // Name of the product.
          "quantity": 1, // Quantity of the product ordered. Should be >= 1
          "unit_price": "0.00", // Price per unit of the product. Should be positive or zero.
          "category": "string" // Required as name of high-level category (Clothes, Electronics,etc.)
        }
      ]
    },
    "attachment": {
            "body": "{\"latitude\": latitude of the terminal as float,\"longitude\": longitude of the terminal as float,\"timestamp\": \"timestamp of the purchase in UTC, displayed in ISO 8601 datetime format\"}", // Example: "\"latitude\":24.4763,\"longitude\":54.3209,\"timestamp\": \"2026-02-27T14:35:10.123Z\""
            "content_type": "application/vnd.tabby.v1+json"
        },
  },
  "merchant_code": "string" // Merchant's branch code or MID
}
```

Even though other parameters are technically optional for offline integration, we highly recommend sharing other data marked as <code>required</code> in the <a href="https://docs.tabby.ai/api-reference/checkout/create-a-session">API Docs</a>, as additional data allows Tabby to increase the AOVs and conversion approval rates.

### Eligibility Check

As a response you receive one of the two session statuses - <code>"created"</code> or <code>"rejected"</code>:

* if the session status is <code>"created"</code> - save the **id of the session** (will be required for cancellation step) and **payment.id** (will be required for payment status check and refund steps) received in the response:

```
"status": "created"
"id": "string" // ID of the session
"payment"."id":"string" // ID of the payment
```

* if the session status is <code>"rejected"</code> - show the Payment failure screen and offer the customer an alternative payment method.

<Note>
  Please, do not proceed with any further steps with Tabby. The rejection might be related to order amount being too high, disabled branch code, or other reasons.
</Note>

The response payload will contain the following:

```
"status": "rejected",
"configuration"."products"."installments"."rejection_reason": "string" // reason for rejection
```

The <code>"rejection\_reason"</code> field can take the following values, you may optionally add human readable messages for cashier:

| Reason | English | Arabic |
| - | - | - |
| `not_available` | Sorry, Tabby is unable to approve this purchase. Please use an alternative payment method for your order. | نأسف، تابي غير قادرة على الموافقة على هذه العملية. الرجاء استخدام طريقة دفع أخرى. |
| `order_amount_too_high` | This purchase is above your current spending limit with Tabby, try a smaller cart or use another payment method | قيمة الطلب تفوق الحد الأقصى المسموح به حاليًا مع تابي. يُرجى تخفيض قيمة السلة أو استخدام وسيلة دفع أخرى. |
| `order_amount_too_low` | The purchase amount is below the minimum amount required to use Tabby, try adding more items or use another payment method | قيمة الطلب أقل من الحد الأدنى المطلوب لاستخدام خدمة تابي. يُرجى زيادة قيمة الطلب أو استخدام وسيلة دفع أخرى. |

## Customer payment options

* **First option: Send the Payment Link** to the customer via SMS using **send\_hpp\_link API** (provided in a Postman Collection). You can use this method only if you receive a <code>"created"</code> status in the response to the previous request.
* **Second option: use the <a href="/offline-payment-methods/pos-integration">POS QR Code integration</a>** as a fallback option.

## Payment Processing

Verify the payment status using:

* <a href="/pay-in-4-custom-integration/webhooks">Webhooks</a>
* or <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Payment API call</a>

### Webhooks

* Tabby sends you a notification payment status update. The initial payment status is <code>CREATED</code>.
* If the Webhook with the <code>authorized</code> or <code>closed</code> status is received - mark the order as successful in your OMS. You can ignore other Webhooks received for this <code>payment.id</code>.
* If the Webhook returns a <code>rejected</code> status - mark the payment as unsuccessful and ask the customer to pay with another payment method.
* If no status is received - the cashier should have an option to cancel the payment.<br />
  **Optional**: You can also add a cancel button using the <a href="/offline-payment-methods/custom-payment-links#cancel-a-payment">Cancel Session API</a> (provided in a Postman Collection) when you want to expire the Tabby session if a customer asks to pay with another payment method or start a new Tabby session.

### Retrieve Request

An alternative way to verify a payment status is by polling status with the <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Payment API call</a>. You can call Retrieve Request by cron or by cashier's action (add button **Check status** to the POS). The following statuses can be received:

* <code>CREATED</code> - the payment has not been completed yet, wait for it to change to one of the terminal statuses.
* <code>AUTHORIZED</code> or <code>CLOSED</code> - a payment was placed successfully, mark orders as successful and proceed with the order on your POS/OMS.
* <code>REJECTED</code> or <code>EXPIRED</code> - a payment is not successful. Ask the customer to pay with a different payment method.

<Note>
  **You can use both** <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Payment API call</a> and <a href="/pay-in-4-custom-integration/webhooks">Webhooks</a> methods for speed and reliability.
</Note>

<Tip>
  It is an expected behaviour that webhooks return payment status in lower case - e.g., <code>authorized</code>, while <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Request</a> - in upper case: <code>AUTHORIZED</code>.
</Tip>

### Cancel a Payment

A request to cancel a payment is available in the Postman collection. The payment can only be canceled if its status is <code>CREATED</code>. Once canceled - the status will change to <code>EXPIRED</code>.

If the payment has already been authorized, attempting to cancel it will return the following error: <code>400 Bad Request</code>

```JSON theme={"dark"}
{
  "status": "error",
  "errorType": "bad_data",
  "error": "session is finalized"
}
```

In this case check the payment status via the <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Payment API call</a> and verify the status is <code>AUTHORIZED</code> or <code>CLOSED</code>. Then show a success screen, print a receipt and proceed with the order.

<Note>
  The Cancel API does not refund payments and can only be used to expire not finalised sessions. Once the payment receives one of the terminal statuses - <code>AUTHORIZED</code>, <code>CLOSED</code>, <code>REJECTED</code> or <code>EXPIRED</code> - the session cannot be cancelled.
</Note>

### Refund a Payment

You can process <a href="/pay-in-4-custom-integration/payment-processing#payment-refund">a Full or Partial Refund</a>. Call <a href="https://docs.tabby.ai/api-reference/payments/refund-a-payment">Refund API</a> for a specific payment.id with the desired amount. You can find the <code>payment.id</code> by matched <code>payment.order.reference\_id</code> in your OMS.

You can also process a refund from the Tabby Merchant Dashboard.

<Note>
  Only payment in status <code>CLOSED</code> with a captured amount present in the <code>"captures":\[]</code> array of objects can be refunded.<br />
  *On Merchant Dashboard such payment will have status <code>CAPTURED</code>.*
</Note>

<Warning>
  Use a **new `reference_id` for every refund**. Refunds are idempotent: repeating a request with an already-used `reference_id` returns the *first* refund's result again instead of creating a new one — in a second-return scenario this looks like an accepted refund while no money moved. See <a href="/pay-in-4-custom-integration/payment-processing#idempotent-requests">Idempotent Requests</a>.
</Warning>

## Print a Receipt

Show a success screen and print a receipt. The receipt data can be used to identify the order and payment, and (optionally) initiate a refund if your POS system provides this functionality.

| Receipt data template |
| - |
| Merchant Order / Transaction ID |
| Date and Time |
| Tabby logo |
| Tabby Payment ID (optional) |
| Merchant name (optional) |

## Testing Scenarios

Kindly verify that your integration can handle all listed below scenarios.

### 1. Payment Success

**Testing Steps:**

1. From a Cashier's POS choose Tabby.
2. Enter payment amount and a real phone number to receive the real payment link.

<Note>
  If your phone number is not eligible for Tabby and the session is rejected, use another phone number or contact Tabby Integrations Team.
</Note>

3. Open received payment link.
4. On Tabby Checkout page enter credentials:

```
Positive flow:
UAE: otp.success@tabby.ai, phone: +971500000001
KSA: otp.success@tabby.ai, phone: +966500000001
```

5. Complete the payment using <code>OTP:8888</code> on Tabby Checkout Page.
6. Verify that the successful payment status is received.

**Expected Results:**

1. Session creation response has status <code>"created"</code> - the customer is eligible to use Tabby.
2. A payment link is successfully sent as an SMS to the customer and Tabby Checkout Page opened.
3. Credentials are entered.
4. The success Tabby screen appears.
5. Payment is successful and captured:
   * on Merchant Dashboard payment status is <code>CAPTURED</code>
   * via a <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Payment API call</a> response Payment status is <code>CLOSED</code>, captured amount is present in the <code>"captures":\[]</code> array of objects.

<Warning>
  If a payment status remains <code>NEW</code> on the Merchant Dashboard or <code>AUTHORIZED</code> via Retrieve Payment API call - kindly contact your Tabby Account manager or `partner@tabby.ai` / `partner@tabby.sa` to update auto-capture settings.
</Warning>

### 2. Eligibility Check Reject

**Testing Steps:**

1. From a Cashier's POS choose Tabby.
2. The session should be created with the following phone number:

```
Eligibility Check Reject flow:
UAE: +971500000002
KSA: +966500000002
```

**Expected Results:**

1. Session creation response has status <code>"rejected"</code> - the customer is **not** eligible to use Tabby.
   * **Optionally**: one of the rejection reasons can be shown to cashier.

### 3. Payment Cancellation

**Testing Steps:**

1. From a Cashier's POS choose Tabby.
2. Enter payment amount and a real phone number to receive the real payment link.

<Note>
  If your phone number is not eligible for Tabby and the session is rejected, use another phone number or contact Tabby Integrations Team.
</Note>

3. Open received payment link.
4. Click 'Cancel' button on Tabby Checkout Page or cancel the payment from a Cashier's POS.
5. Verify the payment status via Retrieve Payment API.

**Expected Results:**

1. Session creation response has status <code>"created"</code> - the customer is eligible to use Tabby.
2. A payment link is successfully sent as an SMS to the customer, Tabby Checkout Page opens.
3. A session is cancelled.
4. On checking Payment Status via <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Payment API call</a> it should be <code>EXPIRED</code>.

<Note>
  By default, Tabby session expires after **20 minutes** since creation and customer is not able to continue the session. This **session expiry timeout** can be reduced by the request from the Merchant side to your assigned business manager in the Integrations thread.

  A payment status may change to <code>"EXPIRED"</code> after **session expiry timeout + 5 minutes** (20 + 5 by default). After that the payment will remain in status <code>"EXPIRED"</code>, no need to check it further.
</Note>

### 4. Payment Failure

**Testing Steps:**

1. From a Cashier's POS choose Tabby.
2. Enter payment amount and a real phone number to receive the real payment link.

<Note>
  If your phone number is not eligible for Tabby and the session is rejected, use another phone number or contact Tabby Integrations Team.
</Note>

3. Open received payment link.
4. On Tabby Checkout page enter credentials:

```
Negative flow:
UAE: otp.rejected@tabby.ai, phone: +971500000001
KSA: otp.rejected@tabby.ai, phone: +966500000001
```

5. Finish the payment using <code>OTP:8888</code> on Tabby Checkout Page.
6. Verify the payment status via Retrieve Payment API.

**Expected Results:**

1. Session creation response has status <code>"created"</code> - the customer is eligible to use Tabby.
2. A payment link is successfully sent as an SMS to the customer.
3. Tabby Checkout Page opens, credentials are entered.
4. The rejection screen with the message 'We can't approve this purchase' appears.
5. On checking Payment Status via <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Payment API call</a> it should be <code>REJECTED</code>.

## Postman Collection

1. Download the JSON file and import it into Postman.
2. Set your <code>base\_url</code>, <code>secret\_key</code>, <code>merchant\_code</code>, and <code>currency</code> in Collection Variables. See <a href="/api-reference/overview#base-urls">Base URLs</a> for regional domains.

<Card href="/custom-pl-pos.json" icon="file-arrow-down">
  <span>
    Payment Links / POS Collection
  </span>
</Card>

<Note>
  This API collection is used for both POS Integration and Custom Payment Links integration and includes all the integration steps.
</Note>


# POS Integration
Source: https://docs.tabby.ai/offline-payment-methods/pos-integration



## Integration Overview

This integration allows customers to pay using Tabby by scanning a QR code displayed on the POS terminal. The flow involves:

1. Creating a payment session
2. Displaying QR code on POS screen
3. Customer scans QR code and completes payment
4. Merchant receives payment confirmation

## Quick Reference

| **API Endpoint** | **Purpose** | **Method** |
| - | - | - |
| `/api/v2/checkout` | Create session and payment | POST |
| `/api/v2/checkout/{id of session}/hpp_link_qr` | Get QR code image (PNG) | GET |
| `/api/v2/payments/{payment.id}` | Retrieve payment status | GET |
| `/api/v2/checkout/{id of session}/cancel` | Cancel session | POST |

| **Key Status Codes** | **Description** |
| - | - |
| `CREATED` | Payment initiated, waiting for completion |
| `AUTHORIZED` | Payment approved, not yet captured |
| `CLOSED` with "captures" object | Payment approved and captured successfully |
| `REJECTED` | Payment declined |
| `EXPIRED` | Session/payment expired or cancelled |

## Steps to Integrate Tabby with your POS

<Steps>
  <Step
    title={(
  <span>
    <a href="https://merchant.tabby.ai/">
      Register with Tabby
    </a>
    <span style={{ fontWeight: 'normal', fontSize: '0.9em' }}>
      &nbsp;(KSA: <a href="https://merchant.tabby.sa/">merchant.tabby.sa</a>)
    </span>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;and finish the application
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    Collect the Test API Keys and Merchant codes from Tabby Merchant Dashboard or your Account Manager
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Set up the&nbsp;
    </span>
    <a href="/offline-payment-methods/pos-integration#create-session-and-payment-using-checkout-api">
      Tabby session creation from your terminal
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Show a&nbsp;
    </span>
    <a href="/offline-payment-methods/pos-integration#show-qr-code">
      QR code on the POS screen
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Set up&nbsp;
    </span>
    <a href="/offline-payment-methods/pos-integration#payment-processing">
      Payment status check
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;on your Backend. This can be done automatically by checking until the payment is completed or manually from the POS
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Once the payment is complete -&nbsp;
    </span>
    <a href="/offline-payment-methods/pos-integration#print-a-receipt">
      print the receipt for the customer
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <a href="/offline-payment-methods/pos-integration#testing-scenarios">
      Test your Integration,
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;contact Tabby Integrations Team in the Integration email thread to complete the testing process
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    After successful testing, receive the Live API keys and deploy to production
  </span>
)}
  />
</Steps>

## Integration Flow

```mermaid theme={"dark"}
sequenceDiagram
    autonumber
    participant Customer
    participant POS as POS Terminal
    participant Provider as POS Backend
    participant Checkout as Tabby Checkout
    participant TabbyAPI as Tabby API

    Customer ->> POS: Request to pay with Tabby
    POS ->> Provider: Initiate payment
    Provider ->> TabbyAPI: POST /api/v2/checkout {amount, ...}
    TabbyAPI -->> Provider: Response {id of the session, status of the session,<br/> payment.id, web_url, qr_code}

    alt "status" of session == "created"
        Provider -->> POS: Return QR Code
        POS -->> Customer: Show QR Code
    else "status" of session == "rejected"
        Provider -->> POS: Return "Payment rejected"
        POS -->> Customer: Show failure screen
    end

    Customer ->> Checkout: Scans QR Code and go through payment steps
    loop Tabby checkout steps
    Checkout -->> Customer: Guide through required steps
    end

    opt Cashier cancels or timeout (300 seconds)
        POS -->> Provider: Cancel or timeout
        Provider -->> TabbyAPI: POST /api/v2/checkout/{id of session}/cancel
    end

    Provider ->> TabbyAPI: Check payment status<br/> (GET /api/v2/payments/{payment.id})
    TabbyAPI -->> Provider: {payment.status:<br/> AUTHORIZED | CLOSED | REJECTED | EXPIRED}
    Note over Provider,TabbyAPI: Or receive webhook with the same status

    alt payment.status ==<br/> "AUTHORIZED" or "CLOSED"
        Provider -->> POS: Payment successful
        POS -->> Customer: Show success screen, Print receipt
    else payment.status ==<br /> "REJECTED" or "EXPIRED"
        Provider -->> POS: Payment failed
        POS -->> Customer: Show failure screen
    end
```

## Create Session and Payment Using Checkout API

Call the <a href="https://docs.tabby.ai/api-reference/checkout/create-a-session">Create a session API</a>. The required payload parameters for the POS session:

```JSON theme={"dark"}
{
  "payment": {
    "amount": "string", // Up to 2 decimals for AED and SAR, e.g. 100.00
    "currency": "string", // Use the ISO 4217 standard for defining currencies: AED, SAR
    "order": {
      "reference_id": "string" // Merchant's Order or Transaction ID to match with the Tabby Payment ID
    },
    "description": "string", // Unique terminal id
    "attachment": {
            "body": "{\"latitude\": latitude of the terminal as float,\"longitude\": longitude of the terminal as float,\"timestamp\": \"timestamp of the purchase in UTC, displayed in ISO 8601 datetime format\"}", // Example: "\"latitude\":24.4763,\"longitude\":54.3209,\"timestamp\": \"2026-02-27T14:35:10.123Z\""
            "content_type": "application/vnd.tabby.v1+json"
        },
  },
  "merchant_code": "string" // Merchant's branch code or MID
}
```

### Eligibility Check

As a response you receive one of the two session statuses - <code>"created"</code> or <code>"rejected"</code>:

* if the session status is <code>"created"</code> - save the **id of the session** (will be required for cancellation step) and **payment.id** (will be required for payment status check and refund steps) received in the response:

```
"status": "created"
"id": "string" // ID of the session
"payment"."id":"string" // ID of the payment
"configuration"."available_products.installments[0].qr_code": "string" // QR code link which you can use to get the image of the QR code and show it on the POS screen
"configuration"."available_products.installments[0].web_url": "string" // Session link, if you want to use it to generate your own QR code
```

* if the session status is <code>"rejected"</code> - show the Payment failure screen and offer the customer an alternative payment method. Please, do not proceed with any further steps with Tabby. The rejection might be related to order amount being too high, disabled branch code, or other reasons. The response payload will contain the following:

```
"status": "rejected"
```

## Show QR Code

When the session has status <code>"created"</code> you will receive two links in the response. Use either of them to show the QR Code on the POS screen:

| **Response field** | **What it returns** | **When to use** |
| - | - | - |
| `configuration.available_products.installments[0].qr_code` | A link to a **ready-to-display QR code image** (PNG, 200×200 px) | **Recommended.** Fetch the image with a plain HTTP GET and render it directly on the POS screen — no QR generation library is required |
| `configuration.available_products.installments[0].web_url` | The Tabby Checkout session link | Generate your own QR code from this link if you need a custom size or design |

### Using the Ready-Made QR Image

The <code>qr\_code</code> link points to the <code>GET /api/v2/checkout/\{id of session}/hpp\_link\_qr</code> endpoint, which responds with a black-and-white PNG image (<code>Content-Type: image/png</code>, 200×200 px, under 1 KB):

* Use the link **exactly as returned** in the session response — do not construct or modify it manually, all required query parameters are already included.
* The request requires **no authentication headers**, so the POS application can fetch the image directly, without proxying it through your backend.
* Render the PNG in a native image component (for example, an <code>ImageView</code> on Android-based POS terminals) — no WebView or browser is needed.

### QR Code Display Recommendations

* **Size.** Display the QR code at least **3×3 cm** on the physical screen. When upscaling the 200×200 px image, use integer scale factors with nearest-neighbor (non-smoothing) scaling so the QR modules stay sharp. If your framework only supports smooth scaling, generate your own QR code from <code>web\_url</code> at the native resolution instead.
* **One code per payment.** The QR code is unique for each payment session. Never cache or reuse the image between payments — fetch a fresh one for every new session.
* **Fallback.** If the image fails to load (for example, due to a network error), create a new payment session and show the QR code from the <code>qr\_code</code> link of the new response.

## Payment Processing

Once QR Code is shown, check the payment status using the <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Payment API call</a>. We recommend calling the Retrieve API **every 5 seconds** until a terminal status is received. Alternatively, you can add a **“Check status”** button on the POS terminal to manually check this.

The following statuses can be received:

* <code>CREATED</code> - the payment has not been completed yet, wait for it to change to one of the terminal statuses.
* <code>AUTHORIZED</code> or <code>CLOSED</code> - the payment is successful, mark order as successful, print a receipt.
* <code>REJECTED</code> or <code>EXPIRED</code> - the payment is not successful. Ask the customer to pay with a different payment method.

### Cancel a Payment

A request to cancel a payment is available in the Postman collection.

You can cancel a payment in two cases:

1. The cashier presses the “Cancel” button on the POS.
2. Automatically, after a timeout. The **recommended** period is **300 seconds**, but the timeout should **never be less than 180 seconds**.

The payment can only be canceled if its status is <code>CREATED</code>. Once canceled - the status will change to <code>EXPIRED</code>.

If the payment has already been successful, attempting to cancel it will return the following error: <code>400 Bad Request</code>

```JSON theme={"dark"}
{
  "status": "error",
  "errorType": "bad_data",
  "error": "session is finalized"
}
```

In this case check the payment status via the <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Payment API call</a> and verify the status is <code>AUTHORIZED</code> or <code>CLOSED</code>. Then show a success screen, print a receipt and proceed with the order.

<Note>
  The Cancel API does not refund payments and can only be used to expire not finalised sessions. Once the payment receives one of the terminal statuses - <code>AUTHORIZED</code>, <code>CLOSED</code>, <code>REJECTED</code> or <code>EXPIRED</code> - the session cannot be cancelled.
</Note>

### Refund a Payment

You can process <a href="/pay-in-4-custom-integration/payment-processing#payment-refund">a Full or Partial Refund</a>. Call <a href="https://docs.tabby.ai/api-reference/payments/refund-a-payment">Refund API</a> for a specific payment.id with the desired amount. You can find the <code>payment.id</code> by matched <code>payment.order.reference\_id</code> in your OMS.

You can also process a refund from the Tabby Merchant Dashboard.

<Note>
  Only payment in status <code>CLOSED</code> with a captured amount present in the <code>"captures":\[]</code> array of objects can be refunded.<br />
  *On Merchant Dashboard such payment will have status <code>CAPTURED</code>.*
</Note>

<Warning>
  Use a **new `reference_id` for every refund**. Refunds are idempotent: repeating a request with an already-used `reference_id` returns the *first* refund's result again instead of creating a new one — in a second-return scenario this looks like an accepted refund while no money moved. See <a href="/pay-in-4-custom-integration/payment-processing#idempotent-requests">Idempotent Requests</a>.
</Warning>

## Print a Receipt

Show a success screen and print a receipt. The receipt data can be used to identify the order and payment, and (optionally) initiate a refund if your POS system provides this functionality.

| Receipt data template |
| - |
| Merchant Order / Transaction ID |
| Date and Time |
| Tabby logo |
| Tabby Payment ID (optional) |
| Merchant name (optional) |

## Recommended Designs

<div>
  <img alt="Native Screen POS Journey" />

  <p>Native Screen POS Journey</p>
</div>

## Testing Scenarios

Kindly verify that your integration can handle all listed below scenarios.

### 1. Payment Success

**Testing Steps:**

1. Choose Tabby on the POS terminal and enter the payment amount, press Enter.
2. Show the QR code on the POS terminal for the customer to scan.
3. On Tabby Checkout Page enter credentials:

```
Positive flow:
UAE: otp.success@tabby.ai, phone: +971500000001
KSA: otp.success@tabby.ai, phone: +966500000001
```

4. Complete the payment using <code>OTP:8888</code> on Tabby Checkout page.
5. Verify that the successful status is received.

**Expected Results:**

1. Session creation response has status <code>"created"</code>, and a QR code is shown successfully on the POS screen.
2. Tabby Checkout Page opens from the QR code.
3. Credentials are entered.
4. The success Tabby screen appears.
5. Payment is successful and captured:
   * on Merchant Dashboard payment status is <code>CAPTURED</code>
   * via a <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Payment API call</a> response Payment status is <code>CLOSED</code>, captured amount is present in the <code>"captures":\[]</code> array of objects.

<Warning>
  If a payment status remains <code>NEW</code> on the Merchant Dashboard or <code>AUTHORIZED</code> via Retrieve Payment API call - kindly contact your Tabby Account manager or `partner@tabby.ai` / `partner@tabby.sa` to update auto-capture settings.
</Warning>

### 2. Tabby Unavailable / API Error Handling

**Testing Steps:**

1. Choose Tabby on the POS terminal and enter a payment amount.
2. Simulate one of the following failure scenarios on the <a href="https://docs.tabby.ai/api-reference/checkout/create-a-session">Create a session API</a> call:
   * **No response from Tabby** - network timeout or loss of connectivity.
   * **Error response from Tabby** - any <code>4xx</code> or <code>5xx</code> status code.
   * **Incomplete response** - session is received but <code>configuration.available\_products.installments\[0].qr\_code</code> and <code>web\_url</code> are not present.
3. Observe POS behavior while the terminal attempts to create the session and display a QR code.
4. Select an alternative payment method on the POS terminal to complete the order.

**Expected Results:**

1. Tabby is present among payment methods on the POS terminal.
2. Session creation does not complete successfully - the POS receives no response, an error status, or an incomplete payload.
3. No QR code is shown; a failure screen or error message is displayed to the cashier, prompting to retry or select an alternative payment method. No payment is created in Tabby.
4. The order can be completed via another payment method on the POS terminal.

### 3. Payment Cancellation

**Testing Steps:**

1. Choose Tabby on the POS terminal and enter the payment amount.
2. Show the QR code on the POS terminal for the customer to scan.
3. Click cancel (Cross icon) on Tabby Checkout page (you may also cancel the session from your POS terminal).

**Expected Results:**

1. Tabby is present among payment methods on POS terminal.
2. Session creation response has status <code>"created"</code>, and a QR code is shown successfully on the POS screen.
3. Tabby Checkout Page opens, a session is cancelled. On checking Payment Status via <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Payment API call</a> it should be <code>EXPIRED</code> status. A new session can be created from POS terminal.

<Note>
  By default, Tabby session expires after **20 minutes** since creation and customer is not able to continue the session. This **session expiry timeout** can be reduced by the request from the Merchant side to your assigned business manager in the Integrations thread.
</Note>

### 4. Payment Failure

**Testing Steps:**

1. Choose Tabby on the POS terminal and enter the payment amount.
2. Show the QR code on the POS terminal for the customer to scan.
3. On Tabby Checkout Page enter credentials:

```
Negative flow:
UAE: otp.rejected@tabby.ai, phone: +971500000001
KSA: otp.rejected@tabby.ai, phone: +966500000001
```

4. Finish the payment using <code>OTP:8888</code> on Tabby Checkout page.
5. Verify the payment status via Retrieve Payment API.

**Expected Results:**

1. Tabby is present among payment methods on POS terminal.
2. Session creation response has status <code>"created"</code>, and a QR code is shown successfully on the POS screen.
3. Tabby Checkout Page opens, credentials are entered.
4. The rejection screen with the message 'We can’t approve this purchase' appears.
5. On checking Payment Status via <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">Retrieve Payment API call</a> it should be <code>REJECTED</code>.

## Postman Collection

1. Download the JSON file and import it into Postman.
2. Set your <code>base\_url</code>, <code>secret\_key</code>, <code>merchant\_code</code>, and <code>currency</code> in Collection Variables. See <a href="/api-reference/overview#base-urls">Base URLs</a> for regional domains.

<Card href="/custom-pl-pos.json" icon="file-arrow-down">
  <span>
    Payment Links / POS Collection
  </span>
</Card>

<Note>
  This API collection is used for both POS Integration and Custom Payment Links integration and includes all the POS steps.
</Note>


# Checkout Flow
Source: https://docs.tabby.ai/pay-in-4-custom-integration/checkout-flow



Tabby's Buy Now, Pay Later solution allows your customers to split the purchase price into several payments with the downpayment and monthly repayments.

<Steps>
  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Enable&nbsp;
    </span>
    <a href="/pay-in-4-custom-integration/checkout-flow#background-pre-scoring-check">
      Background Pre-scoring
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Create&nbsp;
    </span>
    <a href="/pay-in-4-custom-integration/checkout-flow#checkout-session-initiation">
      Checkout Session
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;and redirect a customer to the Tabby Payment Page
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Redirect the customer&nbsp;
    </span>
    <a href="/pay-in-4-custom-integration/checkout-flow#redirection-to-the-store">
      back to your store
    </a>
  </span>
)}
  />
</Steps>

## Tabby on Checkout

Use the standard Tabby naming and Logo to present Tabby method at your checkout:

| | English | Arabic |
| - | - | - |
| **Payment Method Name** | Pay later with Tabby | ادفع لاحقًا مع تابي |

### Recommended: Checkout Snippet

Display the <a href="/pay-in-4-custom-integration/on-site-messaging#checkout-snippet">Checkout snippet</a> under the Tabby payment method when it is selected. The snippet shows the actual cost breakdown for the order amount and the key benefits, and keeps this information always up to date:

<img alt="Tabby payment method with the Checkout snippet" />

### Alternative: Payment Method Description

If the Checkout snippet cannot be embedded (e.g., due to checkout platform constraints), add a static description under the payment method name showing the cost breakdown:

| | English | Arabic |
| - | - | - |
| **Payment Method Description** | 4 payments of XX.XX/mo or up to 12 months. Learn more | 4 دفعات بقيمة XX.XX شهريًا أو حتى 12 شهرًا. اعرف المزيد |

* **XX.XX** is the monthly payment amount with your store currency: order total × 1.015 / 4
* **Learn more** should open the Tabby <a href="/pay-in-4-custom-integration/on-site-messaging#custom-promo-snippets">pop-up</a> with the payment schedule

## Background Pre-scoring Check

Background pre-scoring (also known as eligibility check) determines whether a customer is eligible to use Tabby before displaying it as a payment option. This check takes place at your checkout when the total amount and customer contact details are known.

<Note>
  For detailed implementation including when to perform checks, error handling, caching strategies, rejection messages, and complete code examples, see: <a href="/introduction/faq#when-should-i-perform-eligibility-check%3F">FAQ - Eligibility Check Best Practices</a>
</Note>

### Quick Implementation

Call `POST /api/v2/checkout` endpoint with minimal required data (but more is better): **amount**, **currency**, **buyer.email**, **buyer.phone**, and **merchant\_code**:

```json theme={"dark"}
{
  "payment": {
    "amount": "340.00",
    "currency": "SAR",
    "buyer": {
      "email": "otp.success@tabby.ai",
      "phone": "+966500000001"
    }
  },
  "merchant_code": "your_merchant_code"
}
```

<Note>
  This minimal payload is accepted **for the background pre-scoring call only**. The session you create when the customer clicks "Place order" must carry the [full payload](/api-reference/checkout/session-payload-model) with all required fields.
</Note>

<Note>
  Use the base URL for your region: `api.tabby.ai` (UAE) or `api.tabby.sa` (KSA). See <a href="/api-reference/overview#base-urls">Base URLs</a>.
</Note>

Providing additional details like **order.items**, **shipping\_address**, and customer information - **buyer\_history**, **order\_history**, etc. - helps improve scoring accuracy and increases approval rates.

### Response handling

Check the `status` field to determine eligibility:

* `status: "created"` → customer is eligible, show Tabby;
* `status: "rejected"` → customer is not eligible, hide Tabby or show rejection message.

You can extract the rejection reason from: `configuration.products.installments.rejection_reason` (it is `null` in `created` responses). In `rejected` responses `configuration.available_products` comes back **empty** — which is also why there is no `web_url` to redirect to.

### Possible rejection\_reason values

Here are possible `"rejection_reason"` values and corresponding messages to show to customers:

| Reason | English | Arabic |
| - | - | - |
| General Rejection (`not_available`) | Sorry, Tabby is unable to approve this purchase. Please use an alternative payment method for your order. | نأسف، تابي غير قادرة على الموافقة على هذه العملية. الرجاء استخدام طريقة دفع أخرى. |
| `order_amount_too_high` | This purchase is above your current spending limit with Tabby, try a smaller cart or use another payment method | قيمة الطلب تفوق الحد الأقصى المسموح به حاليًا مع تابي. يُرجى تخفيض قيمة السلة أو استخدام وسيلة دفع أخرى. |
| `order_amount_too_low` | The purchase amount is below the minimum amount required to use Tabby, try adding more items or use another payment method | قيمة الطلب أقل من الحد الأدنى المطلوب لاستخدام خدمة تابي. يُرجى زيادة قيمة الطلب أو استخدام وسيلة دفع أخرى. |

### Best Practices

**Key principles**:

* **Fail-safe approach** - always default to showing Tabby on API errors or timeouts
* **Loading states** - show appropriate UI feedback during checks
* **Background checks** - perform eligibility checks when customer enters checkout or cart amount changes
* **Rejection handling** - hide Tabby (recommended) or show rejection message.

<div>
  <img alt="Background pre-scoring rejection message" />

  <p>Show rejection message for ineligible customers</p>
</div>

### Eligibility Check vs Session Creation

Tabby's Checkout API serves two distinct purposes. Here's a side by side comparison:

| Aspect | Eligibility Check | Checkout Session Creation |
| - | - | - |
| **Purpose** | Determine if customer can use Tabby | Create payment session for actual checkout |
| **Timing** | Before showing Tabby payment method | When customer clicks "Place order" |
| **Payload** | Minimal (amount, currency, buyer) | Complete (all order details, items, shipping, merchant URLs) |
| **Response** | Status (`created` or `rejected`) + rejection reason | Status + `web_url` for redirect + `payment.id` |
| **Next Step** | Show or hide / mark unavailable Tabby payment method based on the response | Redirect to Tabby Hosted Payment Page |

## Checkout Session Initiation

When the customer who passed eligibility check clicks "Place order" with Tabby selected, call <a href="/api-reference/checkout/create-a-session">Checkout API</a> with the **full payload** including all order details, items, shipping address, and merchant URLs.

**This is different from the eligibility check** - you must now provide complete order information. The full request example with all required fields, and the response you get back, are in the <a href="/api-reference/checkout/session-payload-model">Session payload model</a>.

**Key principle**: Use the same endpoint (`POST /api/v2/checkout`) but with different payload sizes for different purposes.

### Response and Validation

In a successful response you will receive `status`, `payment.id`, and the HPP link to redirect the customer to. The link lives at:

```text theme={"dark"}
configuration.available_products.installments[0].web_url
```

Note that `installments` is an **array** — take the first element. See the [full response example](/api-reference/checkout/session-payload-model#response).

<Warning>
  **Always validate that `web_url` is present** in the response before redirecting. If `web_url` is missing or `status` is "rejected", show the rejection message instead of redirecting.
</Warning>

This validation handles edge cases where:

* Cart amount or customer details changed between eligibility check and session creation;
* Customer was blacklisted between checks;
* Eligibility check timed out (fail-safe showed Tabby as available).

<Warning>
  Save <code>"payment"."id"</code> **from the response** - it will be used to verify, capture and refund the payment on the next steps.
</Warning>

### At Tabby Hosted Payment Page

At Tabby Checkout your customers will be asked:

* To verify the phone number by OTP (each transaction);
* To link Apple Pay or regular card (only for new Tabby customers);
* Additional data may be asked during customer's flow for some customers.

## Redirection to the Store

When customers finish Tabby session, they are redirected to one of three URLs you provide in the session creation request, with `payment_id` appended as a query parameter:

| Redirect URL | Use Case | Payment Status | Next Steps |
| - | - | - | - |
| `success` | Customer completed payment verification | `AUTHORIZED` or `CLOSED` | Show "Thank you" page, verify status on backend, proceed to <a href="/pay-in-4-custom-integration/payment-processing">Payment Processing</a> |
| `cancel` | Customer cancelled the payment willingly | `EXPIRED` | Return to checkout or cart, allow retry |
| `failure` | Payment was rejected by Tabby | `REJECTED` | Show rejection message, offer alternative payment methods |

### Handling redirects

* Redirect the customer immediately to avoid delays - do not block with payment status checks
* The redirect is a frontend navigation signal only. Verify payment status asynchronously on your backend via webhooks or `getPayment` API
* Show "Confirming payment..." on Thank you page if status is pending, update once backend confirms final status

<Warning>
  Always verify payment status via your backend. Never rely on redirect URLs or query parameters alone as the source of truth.
</Warning>

### Approved messages for redirects

The following messages can be used to show to customers after a redirect:

| Reason | English message | Arabic message |
| - | - | - |
| `Cancellation` | You aborted the payment. Please retry or choose another payment method. | لقد ألغيت الدفعة. فضلاً حاول مجددًا أو اختر طريقة دفع أخرى. |
| `Failure` | Sorry, Tabby is unable to approve this purchase. Please use an alternative payment method for your order | نأسف، تابي غير قادرة على الموافقة على هذه العملية. الرجاء استخدام طريقة دفع أخرى. |

### Allowed characters in redirect URLs ("success", "cancel", "failure")

1. Latin letters (a-z, A-Z)
2. Arabic letters (ء-ي)
3. Digits (0-9)
4. Special characters - \ | / : ;., + \{}? & @ = # %


# Dispute webhooks
Source: https://docs.tabby.ai/pay-in-4-custom-integration/dispute-webhooks

Get notified when a dispute is opened on your payment and when its status changes: registration, payload, statuses, and delivery.

Dispute webhooks notify your endpoint about <a href="/pay-in-4-custom-integration/disputes">disputes</a> raised on your payments — when a customer opens a dispute, when you challenge it, and when it is resolved. This lets you react to disputes without polling the <a href="/api-reference/disputes/get-disputes-list">Disputes API</a>.

<Note>
  Disputes have **no test mode**: dispute webhooks are registered with a **live** secret key and are sent for live payments only (the same as the Disputes API).
</Note>

## How They Work

<Steps>
  <Step title="Register an endpoint">
    <a href="/api-reference/dispute-webhooks/register-a-dispute-webhook">Register a dispute webhook</a> for each `merchant_code` — the merchant code is passed in the **`X-Merchant-Code` header**, which is required on every dispute-webhook request:

    ```bash theme={"dark"}
    curl -X POST https://api.tabby.ai/api/v1/dispute-webhooks \
      -H "Authorization: Bearer sk_..." \
      -H "X-Merchant-Code: your_merchant_code" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://your-store.com/tabby/dispute-webhook",
        "header": { "title": "X-Auth-Key", "value": "your_random_signing_secret" }
      }'
    ```

    KSA merchants call `https://api.tabby.sa/api/v1/dispute-webhooks`. Each `merchant_code` can have up to **4 dispute webhooks** — the limit is separate from payment webhooks. The optional `header` is added to every notification so you can verify its origin.

    <Note>
      **Registration is self-service.** The same operations as for payment webhooks — register, list, retrieve, update and remove — are available under `/api/v1/dispute-webhooks`, see the <a href="/api-reference/dispute-webhooks/register-a-dispute-webhook">API reference</a>. A dispute webhook receives **all** dispute events of the merchant; there is no event filter.
    </Note>
  </Step>

  <Step title="Receive notifications">
    Tabby sends a POST request to your URL whenever a dispute is opened on one of your payments or its <a href="/pay-in-4-custom-integration/dispute-webhooks#dispute-statuses">status changes</a>.
  </Step>

  <Step title="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 <a href="/pay-in-4-custom-integration/webhooks#retry-attempts">retries</a>.
  </Step>
</Steps>

### Differences From Payment Webhooks

| | <a href="/pay-in-4-custom-integration/webhooks">Payment webhooks</a> | Dispute webhooks |
| - | - | - |
| Endpoints | `/api/v1/webhooks` | `/api/v1/dispute-webhooks` |
| Secret key | `sk_...` or `sk_test_...` — the key sets the environment | live `sk_...` only — a test key gets `403 disputes have no test mode` |
| `X-Merchant-Code` | required (omission is tolerated for a key that maps to a single merchant) | required on every request, single-merchant keys included — otherwise `400 code is required` |
| Limit | 4 per `merchant_code` + key pair | 4 per `merchant_code`, counted separately |
| `header.value` in responses | returned as registered | masked: `****` followed by the last 4 characters (`****` alone for values of 8 characters or fewer) |
| Events | payment status changes | all dispute events, no filter |

A few rules to keep in mind when managing dispute webhooks:

* **URLs must be publicly reachable.** `localhost`, raw IP addresses and host names that do not resolve are rejected with `400 invalid webhook url`. Use HTTPS — the secret in `header` travels with every notification.
* **URLs are normalised and unique per merchant.** The scheme and host are lower-cased, a default port and a trailing slash are dropped before the URL is stored — `https://Store.com/hook/` and `https://store.com/hook` are the same webhook, and registering it twice returns `400 webhook already exists`. The path itself is case-sensitive.
* **`PUT` replaces the whole object.** Send both `url` and `header` when updating; a request without `header` removes the header.
* **The header value is a secret.** Tabby stores it in full but returns it masked in every response — keep your own copy of the value your endpoint validates against.

## Payload

A dispute webhook is a POST request with a JSON body that links the dispute to the affected payment:

```JSON theme={"dark"}
{
  "status": "pending",
  "dispute_id": "string",
  "payment_id": "string",
  "currency": "SAR",
  "created_at": "2026-06-15T13:08:54Z"
}
```

| Field | Description |
| - | - |
| `status` | The dispute event — see [Dispute statuses](#dispute-statuses) below. |
| `dispute_id` | ID of the dispute. Use it with the <a href="/api-reference/disputes/get-dispute-by-id">Get dispute by ID</a> endpoint to fetch full details. |
| `payment_id` | ID of the payment the dispute was raised against. Use it to correlate the dispute with the order in your system. |
| `currency` | ISO currency code of the payment (`SAR`, `AED`). The disputed amount is not part of the payload — fetch it with <a href="/api-reference/disputes/get-dispute-by-id">Get dispute by ID</a>. |
| `created_at` | When the dispute was created, in UTC, ISO 8601 datetime format. |

## Dispute statuses

The `status` field tells you what happened to the dispute:

| `status` | Meaning |
| - | - |
| `pending` | The customer opened a dispute on your payment. |
| `arbitration` | You challenged the dispute (for example, the amount is wrong) or provided the requested evidence, and it moved to arbitration. |
| `evidence_merchant` | Tabby support requested supporting evidence from you. |
| `approved` | The dispute was approved and the amount was refunded to the customer. |
| `declined` | The dispute was declined by Tabby support. |
| `cancelled` | The dispute was cancelled by the customer. |

## Delivery

Dispute webhooks are delivered to the URLs you registered under `/api/v1/dispute-webhooks` (separate from your payment webhooks), using the **same delivery mechanism as payment webhooks** — optional authentication header, retry policy, and server IPs. In particular:

* Acknowledge each delivery with `200` and process it asynchronously — see <a href="/pay-in-4-custom-integration/webhooks#best-practices">Best Practices</a>.
* Delivery order is not guaranteed and a notification may occasionally be delivered twice — deduplicate by `dispute_id` + `status`.
* Failed deliveries are retried — see <a href="/pay-in-4-custom-integration/webhooks#retry-attempts">Retry Attempts</a>.


# Disputes
Source: https://docs.tabby.ai/pay-in-4-custom-integration/disputes

Handle customer disputes programmatically with the Disputes API.

The Disputes API simplifies handling disputes and helps you resolve issues with customers' orders more efficiently. Use it to:

* retrieve a list of disputes;
* view details about a specific dispute;
* approve or challenge disputes (one challenge per dispute);
* upload attachments (up to 5 per dispute).

The API mirrors the functionality available on Tabby Merchant Dashboard. It operates exclusively with **live payments** and live credentials — including testing.

<Warning>
  A secret key is required for using the Disputes API.
</Warning>

<Note>
  Want to react to disputes in real time instead of polling? Register a <a href="/pay-in-4-custom-integration/dispute-webhooks">dispute webhook</a> and Tabby will push a notification to your endpoint when a dispute is opened, challenged, or resolved — self-service via the <a href="/api-reference/dispute-webhooks/register-a-dispute-webhook">Dispute webhooks API</a>.
</Note>

API documentation: <a href="/api-reference/disputes/get-disputes-list">Disputes API</a>.


# Full Testing Checklist
Source: https://docs.tabby.ai/pay-in-4-custom-integration/full-testing-checklist



After the integration is completed from your side - the QA will be performed by the Tabby team. To make sure that all the requirements are covered - kindly review the below checklist which contains the points assessed by our side.

If any of the points cannot be applied to your website/application architecture - please, notify us about that in an email thread and this point will be discussed separately.

This page covers **Website (desktop and mobile), iOS and Android** custom (direct API) integrations. When integrating Tabby on the <a href="/introduction/quick-start">E-commerce Platform from the list</a> this section is not applicable.

## API Keys and Environment

* **No secret key client-side**: search your rendered page source and all browser network traffic for `sk_` — the Secret Key must never appear in the frontend. Snippets and the HPP use only the Public Key (`pk_...`) and merchant code
* **Secret Key for all backend calls**: every server-side request (session creation, payments, captures, refunds, webhooks) is authorized with the Secret Key — the Public Key belongs to the frontend snippets only
* All calls use the **base URL matching the merchant's region** — see <a href="/api-reference/overview#base-urls">Base URLs</a>
* Capture, refund and close use the **`/api/v2/` endpoints** (v1 is deprecated)

## On-Site Messaging

* **Product and Cart snippets and pop-ups** are present in accordance with the:
  * <a href="/pay-in-4-custom-integration/on-site-messaging#add-the-snippets">custom integration documentation</a>
  * or the <a href="/pay-in-4-custom-integration/mobile-apps/app-promo-messaging">SDK documentation</a> used
* **Product snippets** are shown for all products, there is no amount limitation on displaying snippets
* **Cart snippet** is shown for all amounts, there is no amount limitation on displaying snippets
* **Cart snippet** amount is updated successfully when changes are performed with the items in the Cart: addition / removal / deletion of the items
* If the store has both **Arabic and English languages** - snippets should be displayed correctly for both of them
* **Website:** snippets should fit the width of a Mobile Web screen and have suitable width for a Desktop Web as well
* *In case your store has several countries*: **Tabby snippets** should be displayed only for countries you have already registered with Tabby
* *If our code is not compatible with yours or you have a non-standard plan*: kindly use one of the <a href="/pay-in-4-custom-integration/on-site-messaging#custom-promo-snippets">following custom snippets</a> after the confirmation from your assigned business manager is received

## Tabby as a Payment Method

* **Payment method name** is present in accordance with the <a href="/pay-in-4-custom-integration/checkout-flow#tabby-on-checkout">documentation</a>
* **Tabby logo** is present near the payment method name
* **Checkout snippet** is displayed under the selected Tabby payment method (recommended), or the **payment method description** matches the approved copy — see <a href="/pay-in-4-custom-integration/checkout-flow#tabby-on-checkout">Tabby on Checkout</a>
* There should be no restrictions on displaying Tabby payment method from your side - this behaviour should be handled by background pre-scoring process
* If the store has both **Arabic and English languages** - Payment method should be displayed correctly for both of them
* *In case your store has several countries*: **Tabby payment method** should be displayed only for countries you have already registered with Tabby

## Checkout

* <a href="/testing-guidelines/testing-credentials#2-background-pre-scoring-reject">Background Pre-scoring</a> check is present and working in accordance with the <a href="/pay-in-4-custom-integration/checkout-flow#background-pre-scoring-check">documentation</a>
* **Website:** when a customer decides to place an order with Tabby - Tabby Checkout is opened in the same browser window
* **Mobile apps:** no control buttons (e.g., X, close, back, etc.) from your app are present on Tabby Checkout
* **Total amount** on Checkout = amount shown on Tabby Checkout
* If the store has both **Arabic and English languages** - language marker is sent correctly in a session creation request: object <code>"lang"</code>, enum <code>"ar"</code> / <code>"en"</code>
* **Session creation request** contains all the required parameters from <a href="https://docs.tabby.ai/api-reference/checkout/create-a-session">Tabby API</a>
* **Session is created only when the customer clicks "Place order"** — check your backend logs: the full-payload `/api/v2/checkout` call is triggered by the Place-order action only, not by opening the checkout page (the background pre-scoring call is separate), and one click produces exactly **one** session
* **Sessions are disposable**: a fresh session is created for every payment attempt — the HPP URL is never cached or reused, and your own checkout timeout is shorter than the HPP session lifetime
* **Price parity**: the order total with Tabby selected equals the total with any other payment method — no Tabby-specific surcharges or reduced discounts
* A `rejected` session is a **business outcome, not an error** — don't log it as a failure or fire alerts. On a pre-scoring reject, hide Tabby or mark it unavailable with the rejection message (per <a href="/pay-in-4-custom-integration/checkout-flow#background-pre-scoring-check">Background pre-scoring</a>); on a reject at session creation, show the rejection message instead of redirecting (there is no `web_url` to redirect to)
* **Cart behaviour**: the cart is kept after cancellation/failure and **cleared after a successful payment**
* If the store has both **Arabic and English languages** — your own redirect/result pages (success, cancel, failure messages) are localized too, not only the snippets
* **Payload data quality**: place a second order with the same registered account and confirm `buyer_history` / `order_history` carry real values (actual registration date, real past orders, ISO-8601 dates) — omit optional fields instead of sending empty strings or placeholders
* <a href="/testing-guidelines/testing-credentials#1-payment-success">Success scenario</a> is working
* <a href="/testing-guidelines/testing-credentials#3-payment-cancellation">Cancellation scenario</a> is working
* <a href="/testing-guidelines/testing-credentials#4-payment-failure">Failure scenario</a> is working
* <a href="/testing-guidelines/testing-credentials#5-corner-case">Corner case</a> is supported — complete the OTP, close the tab before the redirect, and verify the payment is still captured via the webhook path

## Payment Verification and Processing

* <a href="/api-reference/webhooks/register-a-webhook">Webhooks are registered</a> for each `merchant_code` + secret key pair (up to 4 webhooks per pair). To receive webhooks for test payments, register them with your test key (`sk_test_...`)
* After a payment is placed successfully with Tabby you receive a webhook to your registered url with status <code>"authorized"</code>
* On receiving it you should **trigger a** <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">getPayment</a> request to verify the status of the payment
* If a status is <code>"AUTHORIZED"</code> - a <a href="https://docs.tabby.ai/api-reference/payments/capture-a-payment">capture request</a> should be triggered from your side
  * It is an expected behaviour that webhooks return <code>"authorized"</code> in lower case while <a href="https://docs.tabby.ai/api-reference/payments/retrieve-a-payment">getPayment</a> - in upper case: <code>"AUTHORIZED"</code>.
* A **full amount** must be captured
* **Your webhook endpoint answers `200` fast and tolerates duplicates** — the same event can be delivered twice, and delivery order is not guaranteed (see <a href="/pay-in-4-custom-integration/webhooks#handling-edge-cases">Handling Edge Cases</a>)
* For a test payment you observe the **full webhook sequence**: `authorized` → `authorized` with your capture in `captures[]` → `closed`
* **A capture timeout is not a failure**: if the Capture Request times out, your system retrieves the payment and retries the capture with the **same `reference_id`** — verify no duplicate capture is created and no order is left uncaptured
* Every capture and refund carries a **unique `reference_id`** derived from your order (see <a href="/pay-in-4-custom-integration/payment-processing#idempotent-requests">Idempotent Requests</a>)

## Refunds and Cancellations

* **Refunds validate against the captured amount**, not the authorized one — a refund on an uncaptured payment fails. To release an uncaptured amount use <a href="/api-reference/payments/close-a-payment">Close</a> instead, including the leftover after a partial capture (it is **not** auto-closed)
* **Reusing a `reference_id` replays the first refund** instead of creating a new one — a second, genuine refund needs a new `reference_id`, and the cumulative refunded total cannot exceed the captured amount (see <a href="/testing-guidelines/testing-credentials#6-payment-refund-via-api">refund test scenario</a>)
* Your code reads `captures[]` and `refunds[]` entries **by `created_at`**, never by array position — the order is not guaranteed

If you have any questions considering this Checklist - feel free to contact us in the Integrations thread.


# App Promo Messaging
Source: https://docs.tabby.ai/pay-in-4-custom-integration/mobile-apps/app-promo-messaging

Promo messaging in mobile apps: SDK snippet components, or custom snippets with the standard copy and Tabby pop-up URLs.

Tabby <a href="/pay-in-4-custom-integration/mobile-apps/sdk-all">SDKs</a> contain ready-made snippet components for the Product, Cart, and Checkout pages of your app — use them whenever possible.

If you build your own promo components instead, use the standard Tabby copy below and open the Tabby "Learn more" pop-up in a webview.

### Promo Text

Use the same copy as the <a href="/pay-in-4-custom-integration/checkout-flow#alternative-payment-method-description">Payment Method Description</a> on the web:

| | English | Arabic |
| - | - | - |
| **Payment Method Description** | 4 payments of XX.XX/mo or up to 12 months. Learn more | 4 دفعات بقيمة XX.XX شهريًا أو حتى 12 شهرًا. اعرف المزيد |

* **XX.XX** is the monthly payment amount with your store currency: order total × 1.015 / 4
* **Learn more** should open the Tabby pop-up with the payment schedule in a webview

### Pop-up URLs and live examples

The pop-up URL pattern, parameters, screenshots and a live demo all live on the main <a href="/pay-in-4-custom-integration/on-site-messaging#custom-promo-snippets">On‑Site Messaging → Custom Promo Snippets</a> page — nothing app-specific there, use it as-is with a webview.


# Integration without SDK (WebView)
Source: https://docs.tabby.ai/pay-in-4-custom-integration/mobile-apps/integration-without-sdk

Open the Tabby checkout in your mobile app without our SDK: how to render it, read the payment status correctly, and recover from corner cases.

If our SDK solutions do not meet your requirements, you can open the Tabby Hosted Payment Page in your own mobile app — in a WebView or the system browser — using backend API calls.

## Choose how to render the checkout

There are two ways to open the checkout. The **payment-status and recovery rules on this page apply to both** — only the rendering and the permissions differ.

<Info>
  **Recommended — the system browser + deep links.** Open the Hosted Payment Page in a **Chrome Custom Tab** (Android) or **`SFSafariViewController` / `ASWebAuthenticationSession`** (iOS), and pass your `merchant_urls` as **deep links** back into your app. This is the most resilient option: the browser session survives even if the OS reclaims your app while the customer confirms the payment, and you avoid managing in-app camera permissions.
</Info>

An **embedded WebView** is also supported, and many merchants use one — but then you own more of the flow: the camera/gallery [permissions](#webview-permissions) for ID upload, and state recovery when your app is reclaimed. WebView-specific guidance below is marked as such; everything else applies to both.

## Checkout flow

The Checkout session request, payment method display, and code snippets are integrated the same way as in the <a href="/pay-in-4-custom-integration/checkout-flow">Online Custom Integration</a>. The mobile-specific part is what happens **after** you open the page:

<Steps>
  <Step title="Open the checkout">
    Create the session on your backend and open the returned URL in your WebView (or a Custom Tab /
    `ASWebAuthenticationSession`).
  </Step>

  <Step title="The customer may leave your app">
    To confirm the payment, the customer can be handed off to the **Tabby app** or their **banking
    app**, then returned to your app.
  </Step>

  <Step title="Read the result from your backend, not the UI">
    On return, confirm the payment status server-side — see [Handling the payment
    status](#handling-the-payment-status) below. The returning navigation is a trigger to
    **verify**, not proof of the outcome.
  </Step>
</Steps>

When the customer finishes, read the outcome from your `merchant_urls` (as deep links with the browser approach, or redirect URLs inside a WebView) together with your backend webhooks — always confirming server-side, as described below. The example below shows in-WebView event handling for iOS (Swift), and applies only if you embed a WebView:

<Card href="https://3345738593-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX4TmIyMsX35rbmwHL104%2Fuploads%2FsInrT6TorM3MkCfUUnAQ%2Ftabby-ios-manual-integration.md?alt=media&token=68596cff-0c83-4d71-8aac-cdb0f3d709c8" icon="file-arrow-down">
  <span>
    tabby-ios-manual-integration.md
  </span>
</Card>

## Handling the payment status

This is the most important part of an in-app integration. Getting it wrong is the single biggest source of corner cases — customers who paid successfully but are shown a failure or a reset checkout.

<Warning>
  **The client is never proof of payment — the status lives on Tabby's backend.**

  Closing the WebView, backing out of the checkout, or returning from the Tabby or banking app is a **navigation event, not a payment result**. The customer may also never reach your success page at all — they can pay and then lose connection, or the OS can kill your app first.

  So never map a checkout close, back‑press, or app return to reject/cancel. Always follow the same chain: **event trigger → retrieve the payment (`getPayment`) → decide**. Treat webhooks as notifications only, and confirm the status with <a href="/api-reference/payments/retrieve-a-payment">getPayment</a> (see the <a href="/introduction/faq">FAQ</a>).
</Warning>

There are two separate channels — don't conflate them:

| Channel | Purpose | Trust |
| - | - | - |
| `merchant_urls` (success / cancel / failure) | Client-side UX signal — where to send the customer next | A trigger to verify, **not** the outcome |
| Webhook → `getPayment` | Server-side notification + retrieval | **Source of truth** for the final status |

### Confirm the status from Tabby

Make confirmed-by-backend status the thing that drives your UI, and re-fetch at the moments where customers are most likely to think the flow "ended":

<Steps>
  <Step title="Poll getPayment (default)">
    Your backend receives Tabby webhooks and keeps the latest status by calling
    <a href="/api-reference/payments/retrieve-a-payment">getPayment</a> (which needs your secret key,
    so call it server-side — never from the app). Your app polls **your backend** for the active
    `payment_id`. Use a capped, backed-off interval and show a
    "Confirming your payment…" state rather than a hard success/failure screen.
  </Step>

  <Step title="Re-fetch when the app returns to the foreground">
    On `onResume` (Android) / `sceneDidBecomeActive` / `applicationDidBecomeActive` (iOS), re-fetch
    the status. This single addition resolves the large majority of false "rejections" caused by the
    customer returning from a banking app.
  </Step>

  <Step title="Re-fetch when the WebView closes">
    Treat WebView close as "go ask the backend", not as a result. Fetch the status once more before
    you decide what to show.
  </Step>
</Steps>

**A pending status is not a failure.** Right after the checkout closes, the payment is often still `CREATED` — the customer has not been authorized yet — and can move to `AUTHORIZED` moments later. Never finalize on a non-terminal status: keep polling until Tabby returns a terminal status (`AUTHORIZED`, `CLOSED`, `REJECTED`, or `EXPIRED`), and let your backend reconcile late transitions from the webhook — it receives the `AUTHORIZED` webhook even if the customer never returned to your app. See [Payment Statuses](/pay-in-4-custom-integration/payment-statuses).

**Silent push (optional accelerator).** If you already deliver push notifications, a data-only / `content-available` push can wake the app to fetch the status sooner. Delivery is **not guaranteed** (throttled in the background, dropped under Low Power Mode, disabled Background Refresh, poor network, or after force-quit), so always keep the polling above as the fallback. A real-time channel you already operate (WebSocket / gRPC) is also a valid transport, but is not worth building solely for checkout.

## Recovering from corner cases

While the customer is in an external app (the Tabby app, their banking app, or a browser handling the confirmation), the OS may terminate your app's process in the background to free memory. This is normal OS behaviour, not an error. When the customer returns, the system recreates your screen — and, if you embed a WebView, it is recreated too, reloading its **initial URL** instead of resuming the in-progress checkout. Heavy apps (such as banking apps) make this far more likely, because launching them pushes your app deep into the background.

**The one rule that prevents lost checkouts:** persist the `payment_id` to durable storage **as soon as the checkout session is created** — before the customer can leave your app. Then, even after a full process restart, your return handler can re-query `getPayment` and restore the correct outcome, regardless of whether the WebView survived.

<AccordionGroup>
  <Accordion title="iOS — state restoration and external redirects">
    **Persist first.** Store the active `payment_id` immediately, and re-verify on `sceneDidBecomeActive` / `applicationDidBecomeActive`.

    **Restore the screen.** Use UIKit/SwiftUI state restoration (`stateRestorationActivity` on the scene, or `restorationIdentifier` + `encodeRestorableState`) so the hosting screen is rebuilt instead of reset.

    **Redirect via the system browser.** For any external confirmation redirect, prefer [`ASWebAuthenticationSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) (or `SFSafariViewController`) over an external Safari launch — it keeps your app foregrounded for the round-trip and delivers the callback URL back to you, which markedly reduces the chance of the OS reclaiming your app.

    `WKWebView` does not persist in-page JavaScript state across a process restart, so the persisted `payment_id` is what guarantees continuity.
  </Accordion>

  <Accordion title="Android — state restoration and external redirects">
    **Save and restore state.** Implement `onSaveInstanceState()` / `onRestoreInstanceState()` on the Activity/Fragment hosting the WebView, using `webView.saveState()` and `webView.restoreState()` to keep navigation history. Back durable state with a `ViewModel` + `SavedStateHandle` so it survives [system-initiated process death](https://developer.android.com/topic/libraries/architecture/saving-states).

    **Redirect via a Custom Tab.** For any external confirmation redirect, use [Chrome Custom Tabs](https://developer.android.com/develop/ui/views/layout/webapps/overview-of-android-custom-tabs) with a warmed-up session (bind to `CustomTabsService`, call `warmup()` early, reuse a single `CustomTabsSession`, reconnect on `onServiceDisconnected()`). Custom Tabs keep your process at foreground priority for the redirect, far better than a plain `Intent.ACTION_VIEW` browser launch.

    `WebView.saveState()` restores navigation history but **not** arbitrary in-page JavaScript state, so the persisted `payment_id` is still required for full continuity.
  </Accordion>
</AccordionGroup>

If the confirmation happens in a **separate banking app** (via deep link / App Link) rather than a browser, neither WebView state nor Custom Tabs / `ASWebAuthenticationSession` can prevent your process from being reclaimed — control has passed to another app entirely. In that case the persisted `payment_id` + backend re-verify is the **only** reliable solution.

### Most robust pattern: browser + deep links

This is the **recommended approach** from the top of the page — here is why it holds up. Because the checkout runs in the **system browser** (or a Custom Tab / `SFSafariViewController`) rather than your WebView, the session survives even if your app is evicted from memory: the browser recovers the Tabby confirmation screen, the payment completes, and your `merchant_urls.success` deep link re-opens your app to show the result — while your backend confirms the final status in parallel.

<Accordion title="Deep-link return setup">
  To make the return leg reliable, register your return URLs as app links before you start:

  **Register the URLs.** Set up a custom URL scheme plus Universal Links (iOS) / App Links (Android) for your success / cancel / failure URLs.

  **Wire the platform hooks.** Add the matching intent-filter (Android) / associated-domains entitlement (iOS).

  **Avoid duplicate tasks.** Launch your return activity with `launchMode="singleTask"` (or `singleTop`) so the deep link re-enters your existing task instead of spawning a duplicate.
</Accordion>

### Best-practice checklist

* **Persist `payment_id`** to durable storage at session creation, so recovery works even after a full process restart.
* **Treat webhooks as notifications only**, and **dedupe by `payment_id`** — a webhook, a push, and your polling can all fire for the same payment, and a webhook can be delayed or delivered more than once.
* **Never map a checkout close, back-press, or external-app return to reject/cancel** — always confirm with `getPayment` first.
* **Wait for a terminal status** — a `CREATED`/pending payment can still turn `AUTHORIZED` after the checkout closes; never finalize on a non-terminal status, and let your backend reconcile the late webhook.
* **Always provide `merchant_urls`** (success, cancel, failure) so a deep-link recovery path exists regardless of WebView survival.
* **Don't tear down the WebView** the instant a `merchant_url` loads — confirm the status first.
* **Show a "Confirming your payment…" state** with capped, backed-off polling instead of an immediate success/failure screen.

## WebView permissions

**Only needed if you embed a WebView** — the browser approach handles this natively. Your WebView must be able to **access the camera and pick images from the gallery** on both iOS and Android — required so new customers can capture and upload their national ID during checkout. Without them, a new customer who needs to verify their ID can't complete the purchase. The platform-specific setup is below.

<Tabs>
  <Tab title="iOS">
    <Accordion title="Camera and gallery (Info.plist)">
      Declare the usage descriptions below in your `Info.plist`. `WKWebView` uses the native camera and photo picker once these keys are present — no extra runtime-permission plumbing is required. Adapt the description copy to your app:

      ```xml theme={"dark"}
      <key>NSCameraUsageDescription</key>
      <string>This allows Tabby to take a photo</string>
      <key>NSPhotoLibraryUsageDescription</key>
      <string>This allows Tabby to select a photo</string>
      <key>NSMicrophoneUsageDescription</key>
      <string>For secure verification on the checkout step</string>
      ```

      Our web app accepts **images only** — other file types (e.g. PDF) are not supported by the picker.
    </Accordion>
  </Tab>

  <Tab title="Android">
    On Android you have to relay the WebView's permission and file-chooser requests to the OS yourself.

    <Accordion title="Camera and microphone (onPermissionRequest)">
      When a web page requests the camera or microphone, the WebView calls `onPermissionRequest` on your `WebChromeClient` with a `PermissionRequest` listing the requested resources. The simplest possible handler grants everything immediately — fine for testing, but **not recommended for production**, where you should request the matching Android runtime permission from the user first.

      **1. Map the WebView resource to an Android permission**

      ```kotlin theme={"dark"}
      // PermissionRequest.RESOURCE_VIDEO_CAPTURE -> Manifest.permission.CAMERA
      // PermissionRequest.RESOURCE_AUDIO_CAPTURE -> Manifest.permission.RECORD_AUDIO
      ```

      **2. Declare the permissions and features in `AndroidManifest.xml`**

      ```xml theme={"dark"}
      <uses-feature
          android:name="android.hardware.camera"
          android:required="false" />

      <uses-permission android:name="android.permission.CAMERA"/>
      <uses-permission android:name="android.permission.RECORD_AUDIO" />
      <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
      ```

      `android:required="false"` declares that the camera hardware is not mandatory for the app to run.

      **3. Request the "dangerous" permissions at runtime, then grant them to the WebView**

      `CAMERA` and `RECORD_AUDIO` are classified as dangerous and must be requested at runtime. Grant the WebView request only after the user approves:

      <CodeGroup>
        ```kotlin Kotlin theme={"dark"}
        class MainActivity : ComponentActivity() {

            private val permissionRequester: PermissionRequester = PermissionRequester()

            private val permissionLauncher = registerForActivityResult(
                ActivityResultContracts.RequestPermission(),
                permissionRequester
            )

            override fun onCreate(savedInstanceState: Bundle?) {
                super.onCreate(savedInstanceState)
                enableEdgeToEdge()
                permissionRequester.activityResultLauncher = permissionLauncher
                setContent {
                    TabbyLiveCodingTheme {
                        Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
                            CheckoutWebScreen(
                                modifier = Modifier.padding(innerPadding),
                                url = "https://url.to.web-app.net",
                                webChromeClient = object : WebChromeClient() {
                                    override fun onPermissionRequest(request: PermissionRequest) {
                                        lifecycleScope.launch {
                                            val result = permissionRequester.requestPermissions(
                                                request.resources.mapNotNull {
                                                    WebViewPermissions.byPermission(it)
                                                }
                                            )
                                            val granted = result.filter { it.isGranted == true }

                                            if (granted.isNotEmpty()) {
                                                request.grant(granted.map { it.permission.permission }
                                                    .toTypedArray())
                                            } else {
                                                request.deny()
                                            }
                                        }
                                    }
                                },
                            )
                        }
                    }
                }
            }
        }

        class PermissionRequester : ActivityResultCallback<Boolean> {

            lateinit var activityResultLauncher: ActivityResultLauncher<String>

            private var currentRequest: CompletableDeferred<Boolean>? = null

            private var inProgress: Boolean = false

            suspend fun requestPermissions(permissions: List<WebViewPermissions>): List<PermissionsCheck> {
                if (inProgress) {
                    return permissions.map { PermissionsCheck(it, false) }
                }

                inProgress = true

                val result = permissions.map {
                    currentRequest = CompletableDeferred()
                    activityResultLauncher.launch(it.androidPermission())
                    val result = currentRequest?.await()
                    currentRequest = null
                    PermissionsCheck(it, result)
                }

                inProgress = false

                return result
            }

            override fun onActivityResult(result: Boolean) {
                currentRequest?.complete(result)
            }
        }

        data class PermissionsCheck(
            val permission: WebViewPermissions,
            var isGranted: Boolean? = null,
        )

        enum class WebViewPermissions(val permission: String) {
            VideoCapture(PermissionRequest.RESOURCE_VIDEO_CAPTURE),
            AudioCapture(PermissionRequest.RESOURCE_AUDIO_CAPTURE);

            companion object {
                fun byPermission(permission: String): WebViewPermissions? {
                    return entries.find { it.permission == permission }
                }
            }
        }

        fun WebViewPermissions.androidPermission(): String = when (this) {
            WebViewPermissions.VideoCapture -> Manifest.permission.CAMERA
            WebViewPermissions.AudioCapture -> Manifest.permission.RECORD_AUDIO
        }
        ```

        ```java Java theme={"dark"}
        import android.webkit.PermissionRequest;
        import android.webkit.WebChromeClient;

        import androidx.activity.result.ActivityResultCallback;
        import androidx.activity.result.ActivityResultLauncher;

        import java.util.ArrayList;
        import java.util.List;
        import java.util.Map;

        public class PermissionRequester implements ActivityResultCallback<Map<String, Boolean>> {
            private PermissionRequest permissionRequest;

            public ActivityResultLauncher<String[]> multiplePermissionLauncher;

            public PermissionRequester() {}

            public WebChromeClient getWebChromeClient() {
                return new WebChromeClient() {
                    @Override
                    public void onPermissionRequest(PermissionRequest request) {
                        permissionRequest = request;
                        List<String> permissions = getRuntimePermissions(request.getResources());
                        if (permissions.isEmpty()) {
                            request.grant(request.getResources());
                        } else {
                            multiplePermissionLauncher.launch(permissions.toArray(new String[0]));
                        }
                    }
                };
            }

            @Override
            public void onActivityResult(Map<String, Boolean> o) {
                boolean allGranted = true;
                for (Boolean granted : o.values()) {
                    if (!granted) {
                        allGranted = false;
                        break;
                    }
                }
                if (allGranted) {
                    permissionRequest.grant(permissionRequest.getResources());
                } else {
                    permissionRequest.deny();
                }
            }

            private List<String> getRuntimePermissions(String[] resources) {
                List<String> permissions = new ArrayList<>();
                for (String resource : resources) {
                    switch (resource) {
                        case PermissionRequest.RESOURCE_VIDEO_CAPTURE:
                            permissions.add(android.Manifest.permission.CAMERA);
                            break;
                        case PermissionRequest.RESOURCE_AUDIO_CAPTURE:
                            permissions.add(android.Manifest.permission.RECORD_AUDIO);
                            break;
                    }
                }
                return permissions;
            }
        }
        ```
      </CodeGroup>
    </Accordion>

    <Accordion title="Files / gallery (onShowFileChooser)">
      To let the customer pick an image, override `onShowFileChooser` on your `WebChromeClient`. We recommend the **Android photo picker** (`PickVisualMedia`) — it requires no storage permissions. If you wire up a custom file chooser instead, you must handle the required permissions yourself. Our web app accepts **images only**.

      ```kotlin theme={"dark"}
      var uploadMessageCallback: ValueCallback<Array<Uri>>? = null

      val fileChooserContract = registerForActivityResult(ActivityResultContracts.PickVisualMedia()) { result ->
          val callback = uploadMessageCallback ?: return@registerForActivityResult

          val URIs = result?.let { arrayOf(it) }

          callback.onReceiveValue(URIs)
          uploadMessageCallback = null
      }

      // Web chrome client implementation here. This implementation should be set to your WebView.
      object : WebChromeClient() {
          override fun onShowFileChooser(
              webView: WebView?,
              filePathCallback: ValueCallback<Array<Uri>>?,
              fileChooserParams: FileChooserParams?
          ): Boolean {
              uploadMessageCallback = filePathCallback
              fileChooserContract.launch(
                  PickVisualMediaRequest(ActivityResultContracts.PickVisualMedia.ImageOnly)
              )
              return true
          }
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

## Next steps

Reading the status in the app is only half of it — the order is then captured and processed on your backend, exactly as in the web integration:

* <a href="/pay-in-4-custom-integration/payment-processing">Payment Processing</a> — capture the payment and process the order.
* <a href="/pay-in-4-custom-integration/webhooks">Webhooks</a> — receive payment status updates server-side.


# Mobile App SDKs
Source: https://docs.tabby.ai/pay-in-4-custom-integration/mobile-apps/sdk-all

Native SDKs for iOS, Android, Flutter, and React Native: checkout initialisation and promo snippets.

Tabby offers SDKs for all major mobile platforms:

* **iOS SDK** — <a href="https://github.com/tabby-ai/tabby-ios-sdk">github.com/tabby-ai/tabby-ios-sdk</a>
* **Android SDK** — <a href="https://github.com/tabby-ai/tabby-android-sdk">github.com/tabby-ai/tabby-android-sdk</a>
* **Flutter SDK** — <a href="https://pub.dev/publishers/tabby.ai/packages">pub.dev/publishers/tabby.ai</a>
* **React Native SDK** — <a href="https://www.npmjs.com/package/tabby-react-native-sdk">npmjs.com/package/tabby-react-native-sdk</a>

The SDKs cover:

1. App checkout initialisation
2. Product, Cart, and Checkout page snippets

Payment verification and processing are integrated on your backend with the Tabby Payments API and webhooks, the same way as for the web integration:

* <a href="/pay-in-4-custom-integration/payment-processing">Payment Processing</a>
* <a href="/pay-in-4-custom-integration/webhooks">Webhooks</a>


# On‑Site Messaging
Source: https://docs.tabby.ai/pay-in-4-custom-integration/on-site-messaging



Tabby's JavaScript snippets show split-price messaging right where customers decide to buy — on your Product, Cart and Checkout pages. They raise awareness of flexible payments before checkout, which directly increases conversion. Each snippet includes a "Learn more" link that opens a pop-up with the payment schedule.

<div>
  <img alt="Product page snippet" />

  <img alt="Product page snippet" />

  <img alt="Checkout page snippet" />
</div>

## Add the snippets

Two components cover all pages:

* **`TabbyPromo`** — Product and Cart pages.
* **`TabbyCard`** — Checkout page, the recommended way to present Tabby payment details at checkout (see <a href="/pay-in-4-custom-integration/checkout-flow#tabby-on-checkout">Tabby on Checkout</a>).

<Warning>
  Don't give the container an `id` equal to a component name (`TabbyPromo`, `TabbyCard`): browsers expose element ids on `window`, and the div shadows the Tabby constructor, so the snippet silently doesn't render.
</Warning>

### Product and Cart page snippet

The Product and Cart page snippet uses the `TabbyPromo` component to display promotional messaging on product and cart pages.

Create an empty `<div>` element with a unique selector, preferably using an `id`:

```html theme={"dark"}
<div id="TabbyPromo"></div>
```

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"}
<script src="https://checkout.tabby.ai/tabby-promo.js"></script>
<script>
  new TabbyPromo({
    selector: '#TabbyPromo', // required
    currency: 'AED', // required, 'AED' or 'SAR', uppercase, no spaces
    price: '2000.00', // required, 2 decimal places for AED and SAR
    lang: 'en', // optional, 'en' or 'ar'
    source: 'product', // optional, 'product' or 'cart'
    shouldInheritBg: false, // optional, true or false
    publicKey: 'your_pk', // required, your public key
    merchantCode: 'your_merchant_code' // required, your merchant code, based on your store currency
  });
</script>
```

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"}
<html>
  <body>
    <div id="TabbyPromo"></div>
    <script src="https://checkout.tabby.ai/tabby-promo.js"></script>
    <script>
      new TabbyPromo({
        selector: '#TabbyPromo',
        currency: 'AED',
        price: '2000.00',
        lang: 'en',
        source: 'product',
        shouldInheritBg: false,
        publicKey: 'your_pk',
        merchantCode: 'your_merchant_code'
      });
    </script>
  </body>
</html>
```

### Checkout snippet

The checkout snippet uses the `TabbyCard` component to display payment information during checkout.

Create an empty `<div>` element where the Tabby Card will be displayed:

```html theme={"dark"}
<div id="TabbyCard"></div>
```

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"}
<script src="https://checkout.tabby.ai/tabby-card.js"></script>
<script>
  new TabbyCard({
    selector: '#TabbyCard', // required
    currency: 'AED', // required, 'AED' or 'SAR', uppercase, no spaces
    price: '2000.00', // required, 2 decimal places for AED and SAR
    lang: 'en', // optional, 'en' or 'ar'
    shouldInheritBg: false, // optional, true or false
    publicKey: 'your_pk', // required, your public key
    merchantCode: 'your_merchant_code' // required, your merchant code, based on your store currency
  });
</script>
```

#### Complete Checkout snippet example

```html theme={"dark"}
<html>
  <body>
    <div id="TabbyCard"></div>
    <script src="https://checkout.tabby.ai/tabby-card.js"></script>
    <script>
      new TabbyCard({
        selector: '#TabbyCard',
        currency: 'AED',
        price: '2000.00',
        lang: 'en',
        shouldInheritBg: false,
        publicKey: 'your_pk',
        merchantCode: 'your_merchant_code'
      });
    </script>
  </body>
</html>
```

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.

<iframe title="Tabby On-Site Messaging live demo" />

## 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\&currency=AED\&merchant\_code=your\_merchant\_code\&public\_key=pk\_xyz**](https://checkout.tabby.ai/promos/product-page/installments/en/?price=2000.00\&currency=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\&currency=SAR\&merchant\_code=your\_merchant\_code\&public\_key=pk\_xyz**](https://checkout.tabby.sa/promos/product-page/installments/ar/?price=2000.00\&currency=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.
</Note>

<div>
  <img alt="UAE pop-up with price, en" />

  <img alt="KSA pop-up with price, en" />
</div>

For promo messaging inside native mobile apps, see <a href="/pay-in-4-custom-integration/mobile-apps/app-promo-messaging">App Promo Messaging</a>.


# Payment Processing
Source: https://docs.tabby.ai/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:

<Steps>
  <Step
    title={(
  <span>
    <a href="/pay-in-4-custom-integration/payment-processing#payment-verification">
      Verify
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;the payment status server-to-server
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <a href="/pay-in-4-custom-integration/payment-processing#payment-capture">
      Capture
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;the payment — only captured payments are settled to you
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <a href="/pay-in-4-custom-integration/payment-processing#payment-refund">
      Refund
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;the payment when needed
    </span>
  </span>
)}
  />
</Steps>

## 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 <a href="/api-reference/payments/retrieve-a-payment">Retrieve Request</a> with the `payment_id` you received at <a href="/pay-in-4-custom-integration/checkout-flow#checkout-session-initiation">session creation</a> 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 <a href="/pay-in-4-custom-integration/payment-statuses">Payment Statuses</a> for the full lifecycle):

| Payment `status` | Your action |
| - | - |
| `AUTHORIZED` | Process the order in your OMS, <a href="/pay-in-4-custom-integration/payment-processing#payment-capture">capture the payment</a>, 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).** <a href="/pay-in-4-custom-integration/webhooks">Webhooks</a> 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 <a href="/pay-in-4-custom-integration/payment-statuses#statuses-in-api-responses-vs-webhooks">Payment Statuses</a>.
</Tip>

### 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 <a href="/api-reference/payments/capture-a-payment">Capture Request</a> 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.
</Warning>

### 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 <a href="/api-reference/payments/refund-a-payment">Refund Request</a> or on Merchant Dashboard (<a href="https://merchant.tabby.ai/">merchant.tabby.ai</a> / <a href="https://merchant.tabby.sa/">merchant.tabby.sa</a> 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 <a href="/introduction/faq#if-a-refund-is-requested-will-the-fees-or-murabaha-profit-be-refunded-too">F.A.Q.</a>).

### 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 <a href="/introduction/technical-requirements#amount">requirements</a>?

## 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.
</Tip>

### 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 <a href="/pay-in-4-custom-integration/webhooks#a-capture-confirmation-is-not-a-request-to-capture">Handling Edge Cases</a>: a webhook whose `captures` array is already non-empty is a confirmation, not a trigger.


# Payment Statuses
Source: https://docs.tabby.ai/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

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


# Quick Start
Source: https://docs.tabby.ai/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

<video alt="Tabby demo" />

## Integration Steps

### Setup

<Steps>
  <Step
    title={(
  <span>
    <a href="https://merchant.tabby.ai/">
      Register for a Tabby merchant account
    </a>
    <span style={{ fontWeight: 'normal', fontSize: '0.9em' }}>
      &nbsp;(KSA: <a href="https://merchant.tabby.sa/">merchant.tabby.sa</a>)
    </span>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;and complete your application to obtain access to Tabby Merchant Dashboard
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    Retrieve your test API keys and merchant codes from Tabby Merchant Dashboard or your Tabby account manager
  </span>
)}
  />
</Steps>

### Development

<Steps>
  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Implement checkout integration for your platform:&nbsp;
    </span>
    <a href="/pay-in-4-custom-integration/checkout-flow">
      Web
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;or&nbsp;
    </span>
    <a href="/pay-in-4-custom-integration/mobile-apps/sdk-all">
      Mobile
    </a>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Integrate&nbsp;
    </span>
    <a href="/pay-in-4-custom-integration/payment-processing">
      Payment Processing
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;to handle payment status updates and order fulfillment
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <span style={{ fontWeight: 'normal' }}>
      Add&nbsp;
    </span>
    <a href="/pay-in-4-custom-integration/on-site-messaging">
      Tabby Promo snippets and widgets
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;to your site (required for optimal conversion)
    </span>
  </span>
)}
  />

  <Step
    title={(
  <span>
    <a href="/testing-guidelines/testing-credentials">
      Test basic scenarios
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;with test credentials, then complete the&nbsp;
    </span>
    <a href="/pay-in-4-custom-integration/full-testing-checklist">
      full testing checklist
    </a>
    <span style={{ fontWeight: 'normal' }}>
      &nbsp;before submitting for Tabby QA review
    </span>
  </span>
)}
  />
</Steps>

#### 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: <a href="/api-reference/checkout/session-payload-model">Session payload model</a>.

<Accordion title="Code examples: cURL · Node.js · Python · PHP · C#">
  <CodeGroup>
    ```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<JsonElement>();

    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
    ```
  </CodeGroup>
</Accordion>

After the customer returns, verify the payment server-side and capture it — see <a href="/pay-in-4-custom-integration/payment-processing">Payment Processing</a>.

### Going Live

<Steps>
  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    Submit your integration for Tabby QA review after completing the full testing checklist
  </span>
)}
  />

  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    After successful QA approval, coordinate your go-live plan and marketing campaign with your Tabby account manager
  </span>
)}
  />

  <Step
    title={(
  <span style={{ fontWeight: 'normal' }}>
    Request live API keys and deploy to production
  </span>
)}
  />
</Steps>

#### 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 <a href="/pay-in-4-custom-integration/webhooks">Webhooks</a>).
* [ ] Confirm all calls use the base URL matching the merchant's region (<a href="/api-reference/overview#base-urls">Base URLs</a>).
* [ ] 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 <a href="/pay-in-4-custom-integration/checkout-flow">Checkout Flow Guide</a>.
</Note>

## 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<br/>{ amount, currency, buyer.phone, buyer.email, merchant_code }
    Tabby API -->>- Merchant Backend: Response<br/>{"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<br/>{ all required attributes }
        Tabby API -->>- Merchant Backend: Response<br/>{"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 <br/>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<br/>via webhook or merchant checks it via API
        Tabby API -->>+ Merchant Backend: POST webhook <br />{ "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<br/>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<br/>{ amount, reference_id}
    else payment.status == "CLOSED"
        Merchant Backend ->>+ Merchant Site: Create order in backend<br/>(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:

* <a href="/pay-in-4-custom-integration/payment-statuses">Payment statuses reference</a>
* <a href="/api-reference/payments/refund-a-payment">Refunds and cancellations</a>
* <a href="/pay-in-4-custom-integration/disputes">Disputes handling</a>
* <a href="/introduction/faq">FAQ</a> for common implementation questions
* <a href="/marketing/toolkit">Marketing toolkit</a> 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.ai/pay-in-4-custom-integration/webhooks

Get notified about payment status changes: registration, payload, supported events, delivery order, and retries.

<a href="/api-reference/webhooks">Tabby Webhooks</a> 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 <a href="/pay-in-4-custom-integration/payment-processing#dont-miss-authorized-payments">catch authorized payments</a>.

## How They Work

<Steps>
  <Step title="Register an endpoint">
    <a href="/api-reference/webhooks/register-a-webhook">Register a webhook</a> 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 <a href="/api-reference/webhooks/register-a-webhook">API reference</a>.
    </Note>
  </Step>

  <Step title="Receive notifications">
    Tabby sends a POST request to your URL whenever the <a href="/pay-in-4-custom-integration/webhooks#supported-events">payment status changes</a>.
  </Step>

  <Step title="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 <a href="/pay-in-4-custom-integration/webhooks#retry-attempts">retries</a>.
  </Step>
</Steps>

## 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 <a href="/api-reference/payments/retrieve-a-payment">Retrieve Request</a> returns uppercase (`"AUTHORIZED"`) — this is expected. See <a href="/pay-in-4-custom-integration/payment-statuses#statuses-in-api-responses-vs-webhooks">Payment Statuses</a>.
</Tip>

## 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 <a href="/api-reference/payments/capture-a-payment">Capture Request</a>.
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 <a href="/pay-in-4-custom-integration/dispute-webhooks">Dispute webhooks</a> — a separate webhook family with its own endpoints under `/api/v1/dispute-webhooks`, registered with a live secret key.
</Note>

## 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 <a href="/pay-in-4-custom-integration/webhooks#handling-edge-cases">Handling Edge Cases</a> 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 <a href="https://webhook.site/">Webhook.site</a> 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 <a href="/pay-in-4-custom-integration/webhooks#retry-attempts">retries</a> — 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 href="/pay-in-4-custom-integration/webhooks#a-typical-payment">A Typical Payment</a> — `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.ai/product-catalogue/shopify-product-catalogue



<div>
  <p>
    This page describes the installation process for Tabby Catalogue in Shopify.
  </p>
</div>

* 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;

<div>
  <img alt="Shopify Product Catalogue in Dashboard" />

  <p>Shopify Product Catalogue in Dashboard</p>
</div>

* Wait for the redirection here to the documentation and <a href="https://apps.shopify.com/tabby-product-feed">installation link</a>;
* 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:

<div>
  <img alt="App Permissions" />

  <p>App Permissions</p>
</div>

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

<div>
  <img alt="Connection Step" />

  <p>Connection Step</p>
</div>

<div>
  <img alt="Key Installation" />

  <p>Key Installation</p>
</div>

* Once you connect the application with the secret key, you will observe the "Publish" button;

<div>
  <img alt="Publishing Step" />

  <p>Publishing Step</p>
</div>

* After publishing, you are ready to use Tabby Catalogue, the synchronization starts immediately.


# Zid Product Catalogue
Source: https://docs.tabby.ai/product-catalogue/zid-product-catalogue



<div>
  <p>
    Here you will find the instruction how to install Tabby Catalogue in Zid.
  </p>
</div>

* 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** - <a href="https://apps.zid.sa/en/application/3981">Tabby Catalogue (KSA)</a>;
  * **UAE market** - <a href="https://apps.zid.sa/en/application/6343">Tabby Catalogue (UAE/Kuwait)</a>.

  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 <a href="https://merchant.tabby.sa">merchant.tabby.sa</a> and the UAE app connects to <a href="https://merchant.tabby.ai">merchant.tabby.ai</a>;

<div>
  <img alt="Make sure your store is published before uploading the items" />

  <p>Make sure your store is published before uploading the items</p>
</div>

<div>
  <img alt="Tabby Catalogue in Zid App Market" />

  <p>Tabby Catalogue in Zid App Market</p>
</div>

<div>
  <img alt="Activation Page" />

  <p>Activation Page</p>
</div>


# Postman API Collection
Source: https://docs.tabby.ai/testing-guidelines/postman-api-collections



Download the Postman collection, import it into Postman, and set the Collection Variables:

* <code>base\_url</code> — `https://api.tabby.ai` (UAE) or `https://api.tabby.sa` (KSA). See <a href="/api-reference/overview#base-urls">Base URLs</a>.
* <code>secret\_key</code> — your Tabby Secret API Key
* <code>merchant\_code</code> — your merchant code
* <code>currency</code> — `AED` or `SAR`

<Card href="/custom-api.json" icon="file-arrow-down">
  <span>
    Tabby API Collection
  </span>
</Card>


# Testing Credentials
Source: https://docs.tabby.ai/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 <code>8888</code>.
</Note>

| 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 <code>OTP:8888</code> on Tabby HPP and redirect to the store's success page.
5. Verify that the capture of the successful payment occurred - check for status <code>CAPTURED</code> on the Merchant Dashboard or Payment status <code>AUTHORIZED</code> and <code>CLOSED</code> 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 <code>Success URL</code>; the store's 'Thank you' page appears.
5. Order is captured:
   * Payment Status is <code>CLOSED</code>;
   * captured amount is present in the <code>"captures":\[]</code> 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 <code>Cancel URL</code> - 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 <code>OTP:8888</code> 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 <code>Failure URL</code> - 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 <code>REJECTED</code>.

## 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 <code>OTP:8888</code> 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 <code>CAPTURED</code> on the Merchant Dashboard** or Payment status via Retrieve Payment API is <code>CLOSED</code>. 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 <code>AUTHORIZED</code>, then after capture is triggered, it changes to <code>CLOSED</code> with a captured amount in the <code>"captures":\[]</code> array of objects, triggered by the Webhook notifications or Cron Job.<br />
   Retrieve payment status returned status <code>AUTHORIZED</code> **before capture** and <code>CLOSED</code> **after capture**.

<Note>
  If you encounter any non-captured payments (with <code>AUTHORIZED</code> status on Payments API or <code>NEW</code> status on Merchant Dashboard), you can initiate a **Manual Capture** or **Cancel** on the Merchant Dashboard, or **Capture** or **Close** Payment API Request.
</Note>

## 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 <code>reference\_id</code>) — then perform a genuinely new refund with a **new** <code>reference\_id</code>.

**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 <code>CLOSED</code> with the refunded amount in the <code>refunds":\[]</code> array of objects.
3. The retry with the same <code>reference\_id</code> 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 <code>reference\_id</code> 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.