Tabby for Payments Setup API

Last updated: March 4, 2026

To accept Tabby payments, you must:

Create a payment setup.
Update the payment setup and initialize Tabby as a payment method.
Confirm the payment.
Redirect the customer to complete the payment on Tabby's hosted page.

Call the Create a payment setup endpoint.

Information

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

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payment-contexts


1{
2    "processing_channel_id": "pc_vxhxgm52yoxejcsdtoffscf35i",
3    "currency": "AED",
4    "amount": 2000,
5    "reference": "test",
6    "description": "test-demo",
7    "payment_type": "Regular",
8    "settings": {
9        "success_url": "https://success.co.uk",
10        "failure_url": "https://failure.co.uk"
11    },
12    "order": {
13        "items": [
14            {
15                "name": "Item1",
16                "quantity": 2,
17                "unit_price": 10,
18                "total_amount": 20,
19                "reference": "item-ref",
20                "discount_amount": 1,
21                "type": "digital"
22            }
23        ],
24        "shipping": {
25            "address": {
26                "address_line1": "barhsa1",
27                "city": "Dubai",
28                "zip": "0000"
29            },
30            "method": "string"
31        }
32    },
33    "customer": {
34        "name": "test",
35        "phone": {
36            "country_code": "44",
37            "number": "7898789879"
38        },
39        "email": {
40            "address": "test@email.com"
41        },
42        "device": {
43            "locale": "en-GB"
44        }
45    }
46}

In the request body, provide the following:

processing_channel_id – The processing channel's unique identifier
amount – The payment amount
currency – Set payment currency to any of the following:
- AED
- SAR
- KWD


1{
2    "id": "set_cgrjtiqxgdzedh57if4ftbyv3i",
3    "processing_channel_id": "pc_vxhxgm52yoxejcsdtoffscf35i",
4    "amount": 2000,
5    "currency": "AED",
6    "payment_type": "Regular",
7    "reference": "test",
8    "description": "test-demo",
9    "payment_methods": {
10        "tabby": {
11            "initialization": "disabled",
12            "status": "available",
13            "flags": [
14                "initialization_not_enabled"
15            ]
16        }
17    },
18    "available_payment_methods": ["tabby"],
19    "settings": {
20        "success_url": "https://success.co.uk/",
21        "failure_url": "https://failure.co.uk/"
22    },
23    "customer": {
24        "email": {
25            "address": "test@email.com"
26        },
27        "name": "test",
28        "phone": {
29            "country_code": "44",
30            "number": "7898789879"
31        },
32        "device": {
33            "locale": "en-GB"
34        }
35    },
36    "order": {
37        "items": [
38            {
39                "name": "Item1",
40                "quantity": 2,
41                "unit_price": 10,
42                "total_amount": 20,
43                "reference": "item-ref",
44                "discount_amount": 1,
45                "type": "digital"
46            }
47        ],
48        "shipping": {
49            "address": {
50                "address_line1": "barhsa1",
51                "city": "Dubai",
52                "zip": "0000"
53            },
54            "method": "string"
55        }
56    }
57}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

For Tabby, payment_methods contains the following fields:

flags – An array of error codes or indicators that highlight missing or invalid information which you can prompt the customer to provide.
status – The status of the payment method.
initialization - The initialization status of the payment method, which can be either enabled or disabled. If initialization is disabled, you need to initialize the payment method before offering it to the customer.

When the customer selects Tabby, you must update the payment setup to initialize the payment method.

Call the Update a payment setup endpoint, setting payment_methods.tabby.initialization to enabled.

Additionally, provide the following required fields:

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum value: 1
`customer.name` string	The customer's name.
`customer.email.address` string	The customer's email address.
`customer.phone.number` string	The customer's phone number.
`customer.device.locale` string	The locale of the customer's device. For example, `en-GB`.
`order.items[]` array[object]	The list of line items in the order. Minimum value: 1
`order.items[].name` string	The descriptive name of the line item.
`order.items[].quantity` integer	The quantity of the line item. Minimum value: 1
`order.items[].unit_price` string	The unit price of the line item, in the minor currency unit.
`order.items[].type` string	The item type. For example, physical or digital.
`order.items[].discount_amount` integer	The discount applied to each line item in the invoice.


1{
2  "processing_channel_id": "pc_vxhxgm52yoxejcsdtoffscf35i",
3  "currency": "AED",
4  "amount": 2000,
5  "reference": "test",
6  "description": "test-demo",
7  "payment_type": "Regular",
8  "settings": {
9    "success_url": "https://success.co.uk",
10    "failure_url": "https://failure.co.uk"
11  },
12  "payment_methods": {
13    "tabby": {
14        "initialization": "enabled"
15    }
16  },
17  "order":{
18    "items":[
19        {
20            "name": "Item1",
21            "quantity": 2,
22            "unit_price": 10,
23            "total_amount": 20,
24            "reference": "item-ref",
25            "discount_amount": 1,
26            "type":"digital"
27        }
28    ]
29  },
30    "customer":{
31        "name": "test",
32        "phone": {
33            "country_code": "44",
34            "number": "7898789879"
35        },
36        "email": {
37            "address": "test@email.com"
38        },
39        "device": {
40            "locale": "en-GB"
41    }
42  }
43}

In addition to the required fields, you can also send the following fields:

customer.merchant_account.first_transaction_date
customer.merchant_account.id
customer.merchant_account.last_payment_date
customer.merchant_account.registration_date
customer.phone.country_code
description
order.discount_amount
order.items[].image_url
order.items[].url
order.shipping_amount
order.tax_amount
reference


1{
2    "id": "set_cgrjtiqxgdzedh57if4ftbyv3i",
3    "processing_channel_id": "pc_vxhxgm52yoxejcsdtoffscf35i",
4    "amount": 2000,
5    "currency": "AED",
6    "payment_type": "Regular",
7    "reference": "test",
8    "description": "test-demo",
9    "payment_methods": {
10        "tabby": {
11            "initialization": "enabled",
12            "payment_types": ["installments"],
13            "status": "ready",
14            "flags": []
15        }
16    },
17    "available_payment_methods": ["tabby"],
18    "settings": {
19        "success_url": "https://success.co.uk/",
20        "failure_url": "https://failure.co.uk/"
21    },
22    "customer": {
23        "email": {
24            "address": "test@email.com"
25        },
26        "name": "test",
27        "phone": {
28            "country_code": "44",
29            "number": "7898789879"
30        },
31        "device": {
32            "locale": "en-GB"
33        }
34    },
35    "order": {
36        "items": [
37            {
38                "name": "Item1",
39                "quantity": 2,
40                "unit_price": 10,
41                "total_amount": 20,
42                "reference": "item-ref",
43                "discount_amount": 1,
44                "type": "digital"
45            }
46        ]
47    }
48}

After you initialize Tabby, the payment_methods.tabby.status changes to ready. The response also contains the payment_types array that shows Tabby's available payment types. Only installments is supported.

After the payment status changes to ready, confirm the payment by calling the Confirm a payment setup endpoint, providing the id of the payment setup as the id path parameter, and tabby as the payment_method_name path parameter.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/tabby


1{
2    "id": "pay_zc7a5eyb4pkino6i7oofmo5y6y",
3    "status": "Pending",
4    "customer": {
5        "id": "cus_kayxzritg6xujlgoje4lvmz5ki",
6        "email": "test@email.com",
7        "name": "test",
8        "phone": {
9            "number": "7898789879",
10            "country_code": "44"
11        },
12        "email_verified": false
13    },
14    "payment_type": "Installment",
15    "_links": {
16        "self": {
17            "href": "https://gwc.ckotech.co/payments/pay_zc7a5eyb4pkino6i7oofmo5y6y"
18        },
19        "redirect": {
20            "href": "https://checkout.tabby.ai/?apiKey=pk_test_e7522500-ea7b-44d4-9f76-22b3ef8167b7&lang=eng&merchantCode=CKOAED&product=installments&sessionId=019c105b-f178-7ee8-97fd-db160d3d69d9"
21        }
22    }
23}

After confirming the payment setup, use the redirect.href URL from the confirm response to redirect the customer to Tabby's hosted checkout page where they can complete the payment.

Tabby for Payments Setup API

Create a payment setup

Information

Information

Request example

Response example

Update the payment setup

Request example

Additional fields

Response example

Confirm the payment

Response example

Redirect the customer