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 | ادفع لاحقًا عبر تابي |
| Payment Method Description | Use any card | استخدم أي بطاقة |
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.
Quick Implementation
Call POST https://api.tabby.ai/api/v2/checkout endpoint with minimal required data (but more is better): amount, currency, buyer.email, buyer.phone, and merchant_code.
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.available_products.installments[0].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.
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"
}
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.
- 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 - \ | / : ;., + {}? & @ = # %
