Custom Payment Links Integration
Steps to Integrate Custom Payment Links
Register with Tabby and finish the application
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 or shown as a QR code on the POS screen
Set up Payment Processing on your Backend
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
Standard customer's journey - Customer receives a Payment link via SMS or by scanning a QR-code from POS
Create Session and Payment Using Checkout API
The required Request parameters are:
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.
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 notification and cancellation steps) and payment_id (will be required for payment verification and refund steps) received in the response:
- 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:
The “rejection_reason”
field can take the following values, you may add human readable messages from below to your system (optional):
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 | قيمة الطلب أقل من الحد الأدنى المطلوب لاستخدام خدمة تابي. يُرجى زيادة قيمة الطلب أو استخدام وسيلة دفع أخرى. |
Customer payment options
- First option: Send the payment link to the customer via SMS using Tabby Notification API (provided in a Postman Collection). You can use this method only if you send a
buyer.phone
and receive a“created”
status in the response to the previous request. - Second option: show the payment QR-code to the customer from the response
available_products.installments[].qr_code
. You can show it only if you receive a“created”
status in the response to the previous request.
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
orclosed
status is received - mark the order as successful in your OMS. You can ignore other Webhooks received for thispayment.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
orCLOSED
- a payment was placed successfully, mark orders as successful and proceed with the order on your POS/OMS.REJECTED
orEXPIRED
- 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
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.
Payment Refund
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
.
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 to create session and payment.
- A session should be created with a real phone number.
- Send a payment link as an SMS to the customer or show it as a QR code on the POS screen.
- Open the link / scan the QR code.
- On Tabby Checkout page use these credentials:
- Complete the payment using
OTP:8888
on Tabby HPP. - Verify that the capture of the successful payment occurred - check for status
CAPTURED
on the Merchant Dashboard or Payment statusCLOSED
via Retrieve Payment API call.
Expected Results:
- Tabby is present among payment methods on Cashier’s POS.
- 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 or shown as a QR code on the POS screen.
- Tabby Hosted Payment Page opens.
- The success Tabby screen appears.
- 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.
- on Merchant Dashboard payment status is
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:
- From a Cashier’s POS choose Tabby to create session and payment.
- Fill in all the required fields and use the following phone numbers:
- Attempt to create session and payment with Tabby.
Expected Results:
- Tabby is present among payment methods on Cashier’s POS.
- Session creation response has status
“rejected”
- the customer is not eligible to use Tabby. - 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: نأسف، تابي غير قادرة على الموافقة على هذه العملية. الرجاء استخدام طريقة دفع أخرى.
- Another payment method should be selected on Cashier’s POS.
3. Payment Cancellation
Testing Steps:
- From a Cashier’s POS choose Tabby to create session and payment.
- A session should be created with a real phone number.
- Send a payment link as an SMS to the customer or show it as a QR code on the POS screen.
- Open the link / scan the QR code.
- Leave or abandon Tabby Checkout page.
- You may additionally cancel the session from your side.
Expected Results:
- Tabby is present among payment methods on Cashier’s POS.
- 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 or shown as a QR code on the POS screen.
- Tabby Hosted Payment Page opens.
- After the payment is left / abandoned / cancelled a new session can be created from Cashier’s POS.
- No order appears on the Merchant Dashboard (unsuccessful orders are not displayed on the Dashboard).
- 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 20 minutes from opening the link (sometimes plus additional 10-20 minutes) -
EXPIRED
.
- first -
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:
- From a Cashier’s POS choose Tabby to create session and payment.
- A session should be created with a real phone number.
- Send a payment link as an SMS to the customer or show it as a QR code on the POS screen.
- Open the link / scan the QR code.
- On Tabby Checkout page use these credentials:
- Finish the payment using
OTP:8888
in Tabby HPP. - Verify the payment status via Retrieve Payment API.
Expected Results:
- Tabby is present among payment methods on Cashier’s POS.
- 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 or shown as a QR code on the POS screen.
- Tabby Hosted Payment Page opens.
- The rejection screen with the message ‘We can’t approve this purchase’ appears.
- Tabby payment method is still available for selection on Cashier’s POS.
- No order appears on the Merchant Dashboard (unsuccessful orders are not displayed on the Dashboard).
- On checking Payment Status via Retrieve Payment API call it should be
REJECTED
.
Postman Collection
Find the Postman collection for the Custom Payment Links Integration via the link below.
- Download the JSON file.
- Import the JSON file from the downloaded archive into Postman.
- Enter your Tabby
Secret API Key
andmerchant_code
into the appropriate Collection Variables.
Custom Payment Links API Collection