Custom Payment Links Integration

Integration Overview

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

Creating a payment session
Sending payment link to customer
Customer completes payment on their device
Merchant receiving payment confirmation

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

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

Set up the Tabby session creation from your terminal

Make sure a payment link is successfully sent as an SMS to the customer

Set up Payment Processing on your Backend

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

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

After successful testing passed 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 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
    "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": "{\"location\": \"latitude, longitude\"}", // Example:"-9.833796, 168.954266\"
            "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 required in the API Docs, 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 - “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

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",
"configuration"."products"."installments"."rejection_reason": "string" // reason for rejection

The “rejection_reason” 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 “created” status in the response to the previous request.
Second option: use the POS QR Code integration as a fallback option.

Payment Processing

Verify the payment status using:

Webhooks

Tabby sends you a notification payment status update. The initial payment status is CREATED.
If the Webhook with the authorized or closed status is received - mark the order as successful in your OMS. You can ignore other Webhooks received for this payment.id.
If the Webhook returns a rejected 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.
Optional: You can also add a cancel button using the Cancel Session API (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 Retrieve Payment API call. 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:

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

You can use both Retrieve Payment API call and Webhooks methods for speed and reliability.

It is an expected behaviour that webhooks return payment status in lower case - e.g., authorized, while Retrieve Request - in upper case: AUTHORIZED.

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

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:

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

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

Open received payment link.
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

Complete the payment using OTP:8888 on Tabby Checkout Page.
Verify that the successful payment status is received.

Expected Results:

Session creation response has status “created” - the customer is eligible to use Tabby.
A payment link is successfully sent as an SMS to the customer and Tabby Checkout Page opened.
Credentials are entered.
The success Tabby screen appears.
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:

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

Eligibility Check Reject flow:
UAE: +971500000002
KSA: +966500000002
Kuwait: +96590000002

Expected Results:

Session creation response has status “rejected” - the customer is not eligible to use Tabby.
- Optionally: one of the rejection reasons can be shown to cashier.

3. Payment Cancellation

Testing Steps:

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

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

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

Expected Results:

Session creation response has status “created” - the customer is eligible to use Tabby.
A payment link is successfully sent as an SMS to the customer, Tabby Checkout Page opens.
A session is cancelled.
On checking Payment Status via Retrieve Payment API call it should be EXPIRED.

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 “EXPIRED” after session expiry timeout + 5 minutes (20 + 5 by default). After that the payment will remain in status “EXPIRED”, no need to check it further.

4. Payment Failure

Testing Steps:

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

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

Open received payment link.
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

Finish the payment using OTP:8888 on Tabby Checkout Page.
Verify the payment status via Retrieve Payment API.

Expected Results:

Session creation response has status “created” - the customer is eligible to use Tabby.
A payment link is successfully sent as an SMS to the customer.
Tabby Checkout Page opens, credentials are entered.
The rejection screen with the message ‘We can’t approve this purchase’ appears.
On checking Payment Status via Retrieve Payment API call it should be REJECTED.

Postman Collection

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

Custom Payment Links API Collection

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

Introduction

E-commerce Platforms

Online Custom Integration

Offline Integrations

Testing Guidelines

Custom Payment Links Integration

Integration Overview

Quick Reference

Steps to Integrate Tabby using Custom Payment Links

Integration Flow

Create Session and Payment Using Checkout API

Eligibility Check

Customer payment options

Payment Processing

Webhooks

Retrieve Request

Cancel a Payment

Refund a Payment

Print a Receipt

Testing Scenarios

1. Payment Success

2. Eligibility Check Reject

3. Payment Cancellation

4. Payment Failure

Postman Collection

Introduction

E-commerce Platforms

Online Custom Integration

Offline Integrations

Testing Guidelines

​Integration Overview

​Quick Reference

​Steps to Integrate Tabby using Custom Payment Links

​Integration Flow

​Create Session and Payment Using Checkout API

​Eligibility Check

​Customer payment options

​Payment Processing

​Webhooks

​Retrieve Request

​Cancel a Payment

​Refund a Payment

​Print a Receipt

​Testing Scenarios

​1. Payment Success

​2. Eligibility Check Reject

​3. Payment Cancellation

​4. Payment Failure

​Postman Collection

Integration Overview

Quick Reference

Steps to Integrate Tabby using Custom Payment Links

Integration Flow

Create Session and Payment Using Checkout API

Eligibility Check

Customer payment options

Payment Processing

Webhooks

Retrieve Request

Cancel a Payment

Refund a Payment

Print a Receipt

Testing Scenarios

1. Payment Success

2. Eligibility Check Reject

3. Payment Cancellation

4. Payment Failure

Postman Collection