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.

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 Checkout snippet 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:

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 (3 decimal places for KWD)
Learn more should open the Tabby pop-up 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.

For detailed implementation including when to perform checks, error handling, caching strategies, rejection messages, and complete code examples, see: FAQ - Eligibility Check Best Practices

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.

Use the base URL for your region: api.tabby.ai (UAE, Kuwait) or api.tabby.sa (KSA). See Base URLs.

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

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.

Background pre-scoring rejection message

Show rejection message for ineligible customers

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 Checkout API 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.

Example of a minimal payload for eligibility check

{
  "payment": {
    "amount": "340.00",
    "currency": "SAR",
    "buyer": {
      "email": "[email protected]",
      "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.

Response and Validation

In a successful response you will receive status, web_url, and payment.id:

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.

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

Save “payment”.“id” from the response - it will be used to verify, capture and refund the payment on the next steps.

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

Always verify payment status via your backend. Never rely on redirect URLs or query parameters alone as the source of truth.

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”)

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

Introduction

E-commerce Platforms

Online Custom Integration

Offline Integrations

Testing Guidelines

Checkout Flow

Tabby on Checkout

Recommended: Checkout Snippet

Alternative: Payment Method Description

Background Pre-scoring Check

Quick Implementation

Response handling

Possible rejection_reason values

Best Practices

Eligibility Check vs Session Creation

Checkout Session Initiation

Example of a minimal payload for eligibility check

Response and Validation

At Tabby Hosted Payment Page

Redirection to the Store

Handling redirects

Approved messages for redirects

Allowed characters in redirect URLs (“success”, “cancel”, “failure”)

​Tabby on Checkout

​Recommended: Checkout Snippet

​Alternative: Payment Method Description

​Background Pre-scoring Check

​Quick Implementation

​Response handling

​Possible rejection_reason values

​Best Practices

​Eligibility Check vs Session Creation

​Checkout Session Initiation

​Example of a minimal payload for eligibility check

​Response and Validation

​At Tabby Hosted Payment Page

​Redirection to the Store

​Handling redirects

​Approved messages for redirects

​Allowed characters in redirect URLs (“success”, “cancel”, “failure”)

Tabby on Checkout

Recommended: Checkout Snippet

Alternative: Payment Method Description

Background Pre-scoring Check

Quick Implementation

Response handling

Possible rejection_reason values

Best Practices

Eligibility Check vs Session Creation

Checkout Session Initiation

Example of a minimal payload for eligibility check

Response and Validation

At Tabby Hosted Payment Page

Redirection to the Store

Handling redirects

Approved messages for redirects

Allowed characters in redirect URLs (“success”, “cancel”, “failure”)