​
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 EndpointPurposeMethod
/api/v2/checkoutCreate session and paymentPOST
/api/v2/payments/{payment.id}Retrieve payment statusGET
/api/v2/checkout/{id of session}/cancelCancel sessionPOST
Key Status CodesDescription
CREATEDPayment initiated, waiting for completion
AUTHORIZEDPayment approved, not yet captured
CLOSED with “captures” objectPayment approved and captured successfully
REJECTEDPayment declined
EXPIREDSession/payment expired or cancelled

​
Steps to Integrate Tabby with your POS

1

Register with Tabby and finish the application

2

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

3

Set up the Tabby session creation from your terminal

4

Show a QR code on the POS screen

5

Set up Payment status check on your Backend. This can be done automatically by checking until the payment is completed or manually from the POS

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, receive the Live API keys and deploy to production

​
Integration Flow

​
Create Session and Payment Using Checkout API

Call the Create a session API. The required payload 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
    },
    "description": "string", // Unique terminal id
    "attachment": {
            "body": "{\"location\": \"latitude, longitude\"}", // Example:"-9.833796, 168.954266\"
            "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 - “created” or “rejected”:
  • if the session status is “created” - 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 “rejected” - 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 “created” you will receive the QR Code link and web_url link in the response. Use any of the links to generate and show the QR Code on the POS screen to the customer to scan.

​
Payment Processing

Once QR Code is shown, check the payment status using the Retrieve Payment API call. 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:
  • CREATED - the payment has not been completed yet, wait for it to change to one of the terminal statuses.
  • AUTHORIZED or CLOSED - the payment is successful, mark order as successful, print a receipt.
  • REJECTED or EXPIRED - 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 CREATED. Once canceled - the status will change to EXPIRED. If the payment has already been successful, 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 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)
Native Screen POS Journey

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, 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
Kuwait: otp.success@tabby.ai, phone: +96590000001
  1. Complete the payment using OTP:8888 on Tabby Checkout page.
  2. Verify that the successful status is received.
Expected Results:
  1. Session creation response has status “created”, 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 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 update auto-capture settings.

​
2. Eligibility Check Reject

Testing Steps:
  1. Choose Tabby on the POS terminal and enter the payment amount 30000.
  2. 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”. Tabby payment method is not available. 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. 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 “created”, 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 Retrieve Payment API call it should be EXPIRED status. A new session can be created from POS terminal.
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.

​
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
Kuwait: otp.rejected@tabby.ai, phone: +96590000001
  1. Finish the payment using OTP:8888 on Tabby Checkout page.
  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”, 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 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
This API collection is used for both POS Integration and Custom Payment Links integration and includes all the POS steps.