Tabby
Beta

Last updated: November 13, 2024

Start accepting payments using Tabby, a popular MENA payment method that lets customers split a payment into four installments.

Information

To start accepting Tabby payments, reach out to your Account Manager or [email protected].

Model	Gateway
Payment flow	Direct
Auto capture
Manual capture	Full and partial capture
Refund	Full and partial refund
Void
Disputes	All disputes are handled directly via Tabby
Chargeback	All chargeback are handled directly via Tabby

To accept Tabby payments, follow these steps:

Request a payment context.
Request a payment.
- If you used a manual capture flow, you must also capture the payment.

To check if Tabby is available for a purchase, call the Request a payment context endpoint:

post

https://api.checkout.com/payment-contexts

Information

The Payment Contexts API supports idempotency. You can safely retry API requests without the risk of duplicate requests.


1{
2  "source": {
3    "type": "tabby"
4  },
5  "amount": 10000,
6  "currency": "AED",
7  "customer": {
8    "email": "[email protected]",
9    "name": "John Smith",
10    "phone": {
11      "country_code": "+971",
12      "number": "500000001"
13    }
14  },
15   "processing": {
16      "locale": "ar-AE"
17    },
18    "processing_channel_id": "{{tabby-processing-channel-id}}",
19    "success_url": "http://www.example.com/success.html",
20    "failure_url": "http://www.example.com/failure.html"
21}

For a better acceptance rate, ensure you include:

The items[] object in your payment context request, along with the shipping[] object if items.type is set to physical
As many details as you can in the customer object
Tabby performs a credit assessment on each customer as they go through the sign up and checkout process. For more information, see the Risk assessment section.

For the full API specification, see the API reference.

If your request is successful, you receive a 201 Created response code and you can offer Tabby as a payment method for this purchase.

A successful request contains the available_payment_types field:


1{
2  "id": "pct_y3oqhf46pyzuxjbcn2giaqnb44", 
3  "available_payment_types": [  
4    {
5    "payment_type": "Installment" 
6    }
7  ],
8  "_links": {  
9    "self": "https://api.checkout.com/payment-contexts/pct_y3oqhf46pyzuxjbcn2giaqnb44"  }
10}

If you receive a 201 Created response code with the unavailable_payment_types field, you cannot offer Tabby as payment method for this purchase:


1{
2  "id": "pct_y3oqhf46pyzuxjbcn2giaqnb44", 
3  "unavailable_payment_types": [  
4    {
5    "payment_type": "installment", 
6    "rejection_reason": "order_amount_too_low"
7    }
8  ],
9  "_links": {  
10    "self": "https://api.checkout.com/payment-contexts/pct_y3oqhf46pyzuxjbcn2giaqnb44"  } 
11}

When the customer selects Tabby and requests to pay, call the Request a payment endpoint:

post

https://api.checkout.com/payments


1{
2  "payment_context_id": "pct_xxx",
3  "payment_type": "Installment",
4  "processing_channel_id": "{{processing_channel_id}}"
5}

Ensure you include the items[] array if you did not provide it in your payment context request. Additionally, you must include the shipping[] object if all items[].type are set to physical.

If your request is successful, you receive a 202 Success response code with a status field set to Pending.


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
7    "email": "[email protected]",
8    "name": "John Smith",
9    "phone": {
10      "country_code": "+1",
11      "number": "415 555 2671"
12    }
13  },
14  "_links": {
15    "self": {
16      "href": "https://api.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
17    },
18    "redirect": {
19      "href": "https://api.tabby.ai/"
20    },
21    "qr_code": {
22      "href": "https://api.tabby.ai/api/v2/checkout/{id}/hpp_link_qr"
23    }
24  }
25}

A successful authorization places a hold on the customer's funds. With the manual capture flow, you can capture the funds at a later point in time. For example, if you need to verify that the item the customer purchased is still in stock.

Note

Trigger the manual capture when you ship the items.

Checkout.com can capture the full amount for the payment or perform multiple partial captures. For partial captures, include information about the items in the items[] object.

If the capture amount is equal to the authorized amount, we consider the capture full and final.
If the capture amount is less than the authorized amount and your capture request:
- Includes "capture_type": "Non-Final", we do not release the remaining authorized amount
- Does not include "capture_type", or includes "capture_type": "Final", we release the remaining authorized amount

For more information on capturing payments, see Capture a payment.

If you want to capture the full amount, call the Capture a payment endpoint, and provide the payment_id.

post

https://api.checkout.com//payments/{id}/captures

Response example

If your request is successful, you receive a 202 Success response code.


1{
2  "action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
3  "_links": {
4    "payment": {
5      "href": "https://api.sandbox.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
6    }
7  }
8}

If you want to capture part of the amount, we recommend including information about the items in the items[] object.

Additionally, you can include processing information such as discount and tax amounts in the processing object.

post

https://api.checkout.com/payments/{id}/captures

Request example


1{
2  "amount": 5000,
3  "capture_type": "NonFinal",
4  "items": [
5      {
6        "name": "jumper",
7        "quantity": 1,
8        "unit_price": 6000,
9        "reference": "858818ac",
10        "type": "physical",
11        "discount_amount": 1000,
12        "url": "string",
13        "image_url": "string"
14      }
15  ],
16  "processing": {
17    "shipping_amount": 200,
18    "tax_amount": 100,
19    "discount_amount": 1000
20  }
21}

Response example

If your request is successful, you receive a 202 Success response code and the action_id.


1{
2   "action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
3   "_links": {
4       "payment": {
5           "href": "https://api.sandbox.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
6       }
7   }
8}

If you want to perform multiple partial captures, include "capture_type": "NonFinal" in your request.

post

https://api.checkout.com/payments/{id}/captures

Request example


1{
2  "amount": 1000,
3  "capture_type": "NonFinal"
4}

Response example

If your response is successful, you receive a 202 Success response code and an action_id.


1{
2  "action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
3  "_links": {
4    "payment": {
5      "href": "https://api.sandbox.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
6    }
7  }
8}

To retrieve details about the payment, call the Get payment details endpoint, and provide the {id} path parameter using the payment_id value you received in the Create a payment response.

Tabby supports both partial and full refunds.

You can only refund manually captured payments if:

You performed a final capture.
The payment was voided after a partial or non-final capture.

For more information, see Refund a payment.

Call the Refund a payment endpoint, and provide the payment id as a path parameter.

post

https://api.checkout.com/payments/{id}/refunds


1{
2 "amount": 100
3}


1{
2   "actionId": "act_cxpffngdvouvabegyy3asiuou",
3   "_links": {
4       "payment": {
5           "href": "https://api.checkout.com/payments/pay_ok7yhvutuylevnatk3x3dxviq4"
6       }
7   }
8}

For a partial refund, ensure you include information about the items in the items[] object.

You cannot perform a partial refund if the capture is not final.

Call the Refund a payment endpoint, and provide the payment id as a path parameter.

post

https://api.checkout.com/payments/{id}/refunds


1{
2  "amount": 5000,
3  "items": [
4    {
5      "name": "jumper",
6      "quantity": 1,
7      "unit_price": 5000,
8      "reference": "858818ac",
9      "type": "physical",
10      "discount_amount": 0,
11      "url": "string",
12      "image_url": "string"
13    }
14  ]
15}

If your request is successful, you receive a 202 Success response code and the action_id.


1{
2   "action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
3   "_links": {
4       "payment": {
5           "href": "https://api.sandbox.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
6       }
7   }
8}

Once you create a payment using the auto-capture payment flow, you cannot void it. If you want to reverse a payment that is in progress, wait until you receive the payment_captured webhook, and then process a refund.

You can void a payment after it is authorized but not yet captured.

For more information, see the Void a payment page.

Learn how to manage webhooks using our API, or the Dashboard.

When integrating Tabby, you can configure the following webhooks:

Webhook	Description
`payment_pending`	Sent when a payment request has been successfully initiated.
`payment_context_approved`	Sent when payment is approved by the partner.
`payment_approved` – Manual-capture payments only	Sent when payment is approved by the customer.
`payment_declined`	Sent when a payment request has been rejected.
`payment_captured`	Sent when the payment has been successfully captured.
`payment_capture_declined` – Manual-capture payments only	Sent when a capture request has been rejected.
`payment_expired`	Sent when a payment reaches its expiry date.
`payment_refunded`	Sent when the payment has been (fully or partially) refunded.
`payment_refund_declined`	Sent when a refund has been unsuccessful.
`payment_voided` – Manual-capture payments only	The payment was voided after authorization. The payment was voided after partial capture and the remaining amount is released. The payment has expired.
`payment_void_declined` – Manual-capture payments only	Sent when void request is unsuccessful.

Optional features include:

Risk assessment
Travel industry data

Tabby performs a credit assessment on each customer as they go through the sign up and checkout process.

To ensure a better acceptance rate, ensure you provide as many fields as possible in the customer object when requesting the payment context:

customer.email
customer.email_verified
customer.name
customer.phone
customer.phone.country_code
customer.phone.number
customer.phone.phone_verified

Request example


1{
2  "source": {
3    "type": "tabby"
4  },
5  "amount": 6540,
6  "currency": "AED",
7  "capture": true,
8  "reference": "ORD-5023-4E89",
9  "description": "Set of 3 masks",
10  "customer": {
11    "email": "[email protected]",
12    "email_verified": true,
13    "name": "John Smith",
14    "phone": {
15      "country_code": "+1",
16      "number": "415 555 2671",
17      "phone_verified": true
18    },
19    "summary": {
20      "registration_date": "2019-08-24",
21      "total_order_count": 10,
22      "first_transaction_date": "2017-06-24",
23      "last_payment_date": "2024-06-15",
24      "last_payment_amount": 300
25    },
26    "shipping": {
27      "address": {
28        "address_line1": "123 High St.",
29        "city": "London",
30        "zip": "SW1A 1AA"
31      }
32    },
33    "processing": {
34      "shipping_amount": 300,
35      "discount_amount": 100,
36      "tax_amount": 3000,
37      "locale": "ar"
38    }
39  },
40  "items": [
41    {
42      "type": "Physical",
43      "name": "Test item",
44      "quantity": 2,
45      "unit_price": 50,
46      "reference": "858818ac",
47      "discount_amount": 1000,
48      "url": "string",
49      "image_url": "string"
50    }
51  ],
52  "processing_channel_id": "{{processing_channel_id}}",
53  "success_url": "https://example.com/payments/success",
54  "failure_url": "https://example.com/payments/fail"
55}

If you're in the travel sector, provide the processing.airline_data[] or processing.accommodation_data[] objects whenever possible in your payment context or payment request:


1{
2  "processing": {
3    "airline_data": [
4      {
5        "ticket": {
6          "number": "045-21351455613"
7        },
8        "passenger": [
9          {
10            "first_name": "John",
11            "last_name": "White",
12            "date_of_birth": "1990-05-26"
13          }
14        ],
15        "flight_leg_details": [
16          {
17            "travel_class": "Economy",
18            "carrier_code": "BA",
19            "departure_date": "2023-06-19",
20            "departure_airport": "LHR",
21            "arrival_airport": "LAX"
22          },
23          {
24            "travel_class": "Economy",
25            "carrier_code": "BA",
26            "departure_date": "2023-06-23",
27            "departure_airport": "LAX",
28            "departure_time": "15:30",
29            "arrival_airport": "LHR"
30          }
31        ]
32      }
33    ]
34  }
35}


1{
2  "processing": {
3    "accommodation_data": [
4      {
5        "booking_reference": "ABC123",
6        "name": "Jim's Hotel",
7        "address": {
8          "address_line1": "39 Hercules St",
9          "city": "Brisbane",
10          "country": "AU"
11        },
12        "check_in_date": "2024-05-20",
13        "check_out_date": "2024-05-20",
14        "guests": [
15          {
16            "first_name": "John",
17            "last_name": "Doe",
18            "date_of_birth": "1990-05-20"
19          }
20        ],
21        "number_of_rooms": 1
22      }
23    ]
24  }
25}

To activate Tabby payments in the sandbox environment and start testing, contact your Account Manager, Integrations Engineer, or [email protected].

Follow the Tabby payment flow to create a payment, using either auto capture or manual capture.

Finish the payment in the Tabby hosted payment page, using the following sample data:

OTP: 8888
Card: 4111111111111111
Expiration date: 12/30
CVV: 123

For more detailed testing instructions, see Tabby testing credentials.

To activate Tabby payments in the live environment, contact your Account Manager, Integrations Engineer, or [email protected].

Tabby
Beta

Information

Tabby payment flow

Request a payment context

Information

Request example

Response example

Request a payment

Request example

Response example

Manually capture the payment
Optional

Note

Full capture

Response example

Partial capture with items

Request example

Response example

Multiple partial capture

Request example

Response example

Get details about a payment

Refund a payment

Request example

Response example

Partial refund with items

Request example

Response example

Cancel or void a payment

Cancel a payment with auto capture

Void payment for manual captured payment flow

Webhooks

Optional features

Risk assessment

Request example

Travel industry data

Airline data

Accommodation data

Test your integration

Move your integration to the production environment

Information

Tabby payment flow

Request a payment context

Information

Request example

Response example

Request a payment

Request example

Response example

Manually capture the payment Optional

Note

Full capture

Response example

Partial capture with items

Request example

Response example

Multiple partial capture

Request example

Response example

Get details about a payment

Refund a payment

Request example

Response example

Partial refund with items

Request example

Response example

Cancel or void a payment

Cancel a payment with auto capture

Void payment for manual captured payment flow

Webhooks

Optional features

Risk assessment

Request example

Travel industry data

Airline data

Accommodation data

Test your integration

Move your integration to the production environment

Manually capture the payment
Optional