Steps to Integrate POS

1

Register with Tabby and finish the application

2

Collect the Test API Keys and Merchant codes from Tabby Merchant Dashboard or your Tabby Account manager

4

Make sure a payment link is successfully shown as a QR code on the POS screen

5

Set up Payment Processing on your Backend. This can be done manually from the POS or set to automatically check until updated.

6

Once the payment is complete - print the receipt for the customer

7

Test your Integration, contact Tabby Integrations Team in the Integration email thread to complete the testing process

8

After successful testing passed receive the Live API keys and deploy to production

Create Session and Payment Using Checkout API

Call the Create a session API. The required Request parameters for the POS session:

{
  "payment": {
    "amount": "string", // Up to 2 decimals for AED and SAR, 3 decimals for KWD, e.g. 100.00
    "currency": "string", // Use the ISO 4217 standard for defining currencies: AED, SAR, KWD
    "order": {
      "reference_id": "string" // Merchant's Order or Transaction ID to match with the Tabby Payment ID
    }
  },
  "merchant_code": "string" // Merchant's branch code or MID
}

Background Pre-scoring Checks

As a response you receive one of the two session statuses - “created” or “rejected”:

  • if the session status is “created” - save the session_id (it will be required for cancellation step) and payment_id (will be required for payment verification and refund steps) received in the response:
"status": "created"
"id": "string"
"payment"."id":"string"
"payment"."status":"CREATED"
  • if the session status is “rejected” - inform the cashier that the customer is not eligible for Tabby and offer the customer an alternative payment method. Please, do not proceed with any further steps with Tabby. The response payload will containt the following:
"status": "rejected",
"configuration"."products"."installments"."rejection_reason": "not_available"

The “rejection_reason” field can take the following values, you may add human readable messages from below to your system (optional):

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

Show QR Code

When the session has status “created” you will receive the QR code link in the response. The path is available_products.installments[].qr_code.

Payment Processing

Check the payment status using the Retrieve Payment API call. We recommend calling the Retrieve API every 10 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:

  • CREATED - the payment has not been completed yet, wait for it to change to one of the terminal statuses.
  • AUTHORIZED or CLOSED - a payment was placed successfully, mark orders as successful, print a receipt and proceed with the order on your POS/OMS.
  • REJECTED or EXPIRED - a 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 scenarios:

  1. The customer changes their mind, and the cashier presses the “Cancel” button on the POS.
  2. Automatically, after a timeout period. 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 CREATED. Once canceled - the status will change to EXPIRED.

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

{
  "status": "error",
  "errorType": "bad_data",
  "error": "session is finalized"
}

In this case check the payment status via the Retrieve Payment API call and verify the status is AUTHORIZED or CLOSED. Then show a success screen, print a receipt and proceed with the order.

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 - AUTHORIZED, CLOSED, REJECTED or EXPIRED - the session cannot be cancelled.

Refund a Payment

You can process a full or partial Refund. Call Refund API for a specific Payment ID with the desired amount. You can find the payment.id by matched payment.order.reference_id in your OMS.

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

Only payment in status CLOSED with a captured amount present in the “captures”:[] array of objects can be refunded.
On Merchant Dashboard such payment will have status CAPTURED.

Show your 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)

Native Screen POS Journey

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.
  2. Show the QR code on the POS terminal for the customer to scan.
  3. On Tabby Checkout page use these credentials:
Positive flow:
UAE: otp.success@tabby.ai, phone: +971500000001
KSA: otp.success@tabby.ai, phone: +966500000001
Kuwait: otp.success@tabby.ai, phone: +96590000001
  1. Complete the payment using OTP:8888 on Tabby HPP.
  2. Verify that the capture of the successful payment occurred - check for status CAPTURED on the Merchant Dashboard or Payment status CLOSED via Retrieve Payment API call.

Expected Results:

  1. Tabby is present among payment methods on POS terminal.
  2. Session creation response has status “created” - the customer is eligible to use Tabby.
  3. A QR code is shown successfully on the POS screen.
  4. Tabby Hosted Payment Page opens.
  5. The success Tabby screen appears.
  6. Order is captured:
    • on Merchant Dashboard payment status is CAPTURED
    • via a Retrieve Payment API call response Payment status is CLOSED, captured amount is present in the “captures”:[] array of objects.

If a payment status remains NEW on the Merchant Dashboard or AUTHORIZED via Retrieve Payment API call - kindly contact your Tabby Account manager or partner@tabby.ai to review the situation.

2. Background Pre-scoring Reject

Testing Steps:

  1. Choose Tabby on the POS terminal and enter the following based on the data you pass in:
    • if you do not pass a phone number in a session creation request - enter the payment amount to be over the max limit, set for your store from Tabby side. To learn the set limit kindly contact your Tabby Account manager or partner@tabby.ai.
    • if you pass a phone number in a session creation request - use the following phone numbers:
Background Pre-scoring reject flow:
UAE: +971500000002
KSA: +966500000002
Kuwait: +96590000002
  1. Attempt to create session and payment with Tabby.

Expected Results:

  1. Tabby is present among payment methods on POS terminal.
  2. Session creation response has status “rejected” - the customer is not eligible to use Tabby.
  3. Tabby payment method becomes hidden or marked unavailable, the following message can be shown (optional):
    • English: Sorry, Tabby is unable to approve this purchase, please use an alternative payment method for your order.
    • Arabic: نأسف، تابي غير قادرة على الموافقة على هذه العملية. الرجاء استخدام طريقة دفع أخرى.
  4. Another payment method should be selected on 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. Leave or abandon Tabby Checkout page.
  4. 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 “created” - the customer is eligible to use Tabby.
  3. A QR code is shown successfully on the POS screen.
  4. Tabby Hosted Payment Page opens.
  5. After the payment is left / abandoned / cancelled a new session can be created from POS terminal.
  6. No order appears on the Merchant Dashboard (unsuccessful orders are not displayed on the Dashboard).
  7. On checking Payment Status via Retrieve Payment API call it should be:
    • first - CREATED as the payment has not been completed;
    • after the cancellation from your side - EXPIRED;
    • if no cancellation has been sent from your side -> after the set timeout - recommended 300 seconds and not less than 180 seconds - EXPIRED;
    • if no cancellation from your side and no timeout is set -> after 20 minutes from opening the QR (sometimes plus additional 10-20 minutes) - EXPIRED.

By default, Tabby session expires after 20 minutes since creation and customer is not able to continue the session. However, a payment status may change to EXPIRED after additional 10-20 minutes due to more checks and awaiting a bank confirmation whether a downpayment was paid.

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 use these credentials:
Negative flow:
UAE: otp.rejected@tabby.ai, phone: +971500000001
KSA: otp.rejected@tabby.ai, phone: +966500000001
Kuwait: otp.rejected@tabby.ai, phone: +96590000001
  1. Finish the payment using OTP:8888 in Tabby HPP.
  2. 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 “created” - the customer is eligible to use Tabby.
  3. A QR code is shown successfully on the POS screen.
  4. Tabby Hosted Payment Page opens.
  5. The rejection screen with the message ‘We can’t approve this purchase’ appears.
  6. Tabby payment method is still available for selection on POS terminal.
  7. No order appears on the Merchant Dashboard (unsuccessful orders are not displayed on the Dashboard).
  8. On checking Payment Status via Retrieve Payment API call it should be REJECTED.

Postman Collection

  1. Download the JSON file.
  2. Import the JSON file from the downloaded archive into Postman.
  3. Enter your Tabby Secret API Key and merchant_code into the appropriate Collection Variables.

POS API Collection

The name of the collection is “Custom PL” - this is an expected behaviour as Custom Payment Links flow includes all the POS steps and can be used for both types of integration.