Create a session

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <secret_key>, where <secret_key> is your secret_key.

Body

application/json

payment

object

required

Payment object associated with the current session.

Show child attributes

payment.amount

string

required

Total payment amount, including tax, shipping and any discounts. Allows to send up to 2 decimals for AED and SAR, up to 3 decimals for KWD.

Example:

"100"

payment.currency

enum<string>

required

ISO 4217 currency code for the payment amount. Currently there are 3 possible currency options - depending on the country where the store is located:

AED - United Arab Emirates Dirham
SAR - Saudi Riyal
KWD - Kuwaiti Dinar

Available options:

AED,

SAR,

KWD

Example:

"AED"

payment.buyer

object

required

Customer information

Show child attributes

payment.buyer.name

string

required

Customer’s full name.

Example:

"John Doe"

payment.buyer.email

string<email>

required

Customer’s email address.

payment.buyer.phone

string

required

Customer’s phone number. This must be a valid mobile phone where the consumer can receive text messages. The accepted phone masks are - 500000001, 0500000001, +971500000001, 971500000001.

Example:

"500000001"

payment.buyer.dob

string<date>

Customer's date of birth; format is YYYY-MM-DD.

Example:

"2000-01-20"

payment.shipping_address

object

required

Show child attributes

payment.shipping_address.city

string

required

Name of city, municipality, or village.

Example:

"Dubai"

payment.shipping_address.address

string

required

Building name, apartment number.

Example:

"Dubai"

payment.shipping_address.zip

string

required

Postal code.

Example:

"1111"

payment.order

object

required

Show child attributes

payment.order.reference_id

string

required

Merchant-assigned order number.

Example:

"1001"

payment.order.items

object[]

required

Array of objects representing the order items in this payment.

Show child attributes

payment.order.items.title

string

required

Name of the product.

Example:

"Name of the product"

payment.order.items.quantity

integer

default:1

required

Quantity of the product ordered.

Required range: x >= 1

Example:

1

payment.order.items.unit_price

string

default:0.00

required

Price per unit of the product. Should be positive or zero.

Example:

"0.00"

payment.order.items.category

string

required

Required as name of high-level category (Clothes, Electronics,etc.); or a tree of category-subcategory1-subcategory2; or id of the category and table with category-ids data mapped provided.

Example:

"Clothes"

payment.order.items.reference_id

string

Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.

Example:

"SKU123"

payment.order.items.description

string

Description of the product.

Example:

"Description of the product"

payment.order.items.discount_amount

string

default:0.00

Amount of the applied discount if any. Should be positive or zero.

Example:

"0.00"

payment.order.items.image_url

string<uri>

URL of the item image to show in the order information.

Example:

"https://example.com/"

payment.order.items.product_url

string<uri>

URL of the item at your store.

Example:

"https://example.com/"

payment.order.items.gender

enum<string>

Who the goods are designed to.

Available options:

Male,

Female,

Kids,

Other

Example:

"Kids"

payment.order.items.color

string

white / blue/ green

Example:

"white"

payment.order.items.product_material

string

cotton / polyester / synthetic

Example:

"cotton"

payment.order.items.size_type

string

EU / UK

Example:

"EU"

payment.order.items.size

string

L / XL / 12

Example:

"M"

payment.order.items.brand

string

Mango / Dorothy Perkins / Tommy Hilfiger

Example:

"Name of the Brand"

payment.order.items.is_refundable

boolean

Indicates whether a product can be returned

payment.order.items.barcode

string

A machine-readable product identifier. Typically used for logistics and scanning.

Example:

"12345678"

payment.order.items.ppn

string

Product Part Number assigned by the manufacturer. Used to identify specific components or versions of a product.

Example:

"MNXT2ZM/A"

payment.order.items.seller

string

The name of the seller offering this item. This field is used to distinguish products from different vendors on a single marketplace.

Example:

"Name of the Seller"

payment.order.updated_at

string<date-time>

Date and time the order was last updated, in UTC, and displayed in ISO 8601 datetime format.

payment.order.tax_amount

string

default:0.00

Total tax for the order.

payment.order.shipping_amount

string

default:0.00

Total shipping cost for the order.

payment.order.discount_amount

string

default:0.00

Total discount for the order. Should be positive or zero. Shows up on Tabby App for the Customer's convenience.

payment.buyer_history

object

required

Customer information. registered_since (as a date of the customer's registration in the App), loyalty_level (as a number of successful orders) and wishlist_count (paid amount by a customer previously, e.g. 500) must be sent for Monthly Billing. is_social_networks_connected is also required for Monthly Billing.

Show child attributes

payment.buyer_history.registered_since

string<date-time>

required

Date and time the customer got registred with you, in UTC, and displayed in ISO 8601 datetime format.

payment.buyer_history.loyalty_level

number

default:0

required

Customer's loyalty level within your store, should be sent as a number of successfully placed orders in the store with any payment methods.

payment.buyer_history.wishlist_count

number

default:0

Number of items in Customer's wishlist.

Required range: x >= 0

Is social network connected

payment.buyer_history.is_phone_number_verified

boolean

Is phone number verified

payment.buyer_history.is_email_verified

boolean

Is email verified

payment.order_history

object[]

required

Array of objects, should contain information on 5-10 previously placed via any payment method orders in any status, current order excluded.

Show child attributes

payment.order_history.purchased_at

string<date-time>

required

Date and time the order was placed, in UTC, and displayed in ISO 8601 datetime format.

payment.order_history.amount

string

required

Total payment amount, including tax, shipping, and excluding any discounts. Allows to send up to 2 decimals for AED and SAR, up to 3 decimals for KWD.

Example:

"100"

payment.order_history.status

enum<string>

required

Status of the order.

Available options:

new,

processing,

complete,

refunded,

canceled,

unknown

payment.order_history.buyer

object

required

Customer information

Show child attributes

payment.order_history.buyer.name

string

required

Customer’s full name.

Example:

"John Doe"

payment.order_history.buyer.email

string<email>

required

Customer’s email address.

payment.order_history.buyer.phone

string

required

Customer’s phone number. This must be a valid mobile phone where the consumer can receive text messages. The accepted phone masks are - 500000001, 0500000001, +971500000001, 971500000001.

Example:

"500000001"

payment.order_history.buyer.dob

string<date>

Customer's date of birth; format is YYYY-MM-DD.

Example:

"2000-01-20"

payment.order_history.shipping_address

object

required

Show child attributes

payment.order_history.shipping_address.city

string

required

Name of city, municipality, or village.

Example:

"Dubai"

payment.order_history.shipping_address.address

string

required

Building name, apartment number.

Example:

"Dubai"

payment.order_history.shipping_address.zip

string

required

Postal code.

Example:

"1111"

payment.order_history.payment_method

enum<string>

Payment method used.

Available options:

card,

cod

Example:

"card"

payment.order_history.items

object[]

Array of objects representing the order items in this payment. If you want to offer consumers a discount, use this object to create a “discount order item”, with the unit_price set to the negative value of the discount.

Show child attributes

payment.order_history.items.reference_id

string

Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.

Example:

"SKU123"

payment.order_history.items.title

string

Name of the product.

Example:

"Name of the product"

payment.order_history.items.description

string

Description of the product.

Example:

"Description of the product"

payment.order_history.items.quantity

integer

default:1

Quantity of the product ordered.

Required range: x >= 1

Example:

1

payment.order_history.items.unit_price

string

default:0.00

Price per unit of the product. Should be positive or zero.

Example:

"0.00"

payment.order_history.items.discount_amount

string

default:0.00

Amount of the applied discount if any. Should be positive or zero.

Example:

"0.00"

payment.order_history.items.image_url

string<uri>

URL of the item image to show in the order information.

Example:

"https://example.com/"

payment.order_history.items.product_url

string<uri>

URL of the item at your store.

Example:

"https://example.com/"

payment.order_history.items.gender

enum<string>

Who the goods are designed to.

Available options:

Male,

Female,

Kids,

Other

Example:

"Kids"

payment.order_history.items.category

string

Required as name of high-level category (Clothes, Electronics,etc.); or a tree of category-subcategory1-subcategory2; or id of the category and table with category-ids data mapped provided.

Example:

"Clothes"

payment.order_history.items.color

string

white / blue/ green

Example:

"white"

payment.order_history.items.product_material

string

cotton / polyester / synthetic

Example:

"cotton"

payment.order_history.items.size_type

string

EU / UK

Example:

"EU"

payment.order_history.items.size

string

L / XL / 12

Example:

"M"

payment.order_history.items.brand

string

Mango / Dorothy Perkins / Tommy Hilfiger

Example:

"Name of the Brand"

payment.order_history.items.is_refundable

boolean

Indicates whether a product can be returned

payment.order_history.items.barcode

string

A machine-readable product identifier. Typically used for logistics and scanning.

Example:

"12345678"

payment.order_history.items.ppn

string

Product Part Number assigned by the manufacturer. Used to identify specific components or versions of a product.

Example:

"MNXT2ZM/A"

payment.order_history.items.seller

string

The name of the seller offering this item. This field is used to distinguish products from different vendors on a single marketplace.

Example:

"Name of the Seller"

payment.description

string

Example:

"test payload"

payment.meta

object

Merchant-defined data about the payment. This field is a key-value map. The example properties provided below.

Show child attributes

payment.meta.customer

string | null

Example:

"#customer-id"

payment.meta.order_id

string | null

Example:

"#1234"

payment.attachment

object

Extra data (booking info, insurance, flight reservations, ...) as serialized JSON

Show child attributes

payment.attachment.body

object

required

Should be an object containing any of the keys with corresponded sub objects

Show child attributes

payment.attachment.body.flight_reservation_details

object

Show child attributes

payment.attachment.body.flight_reservation_details.itinerary

object[]

required

Itinerary data, one per segment

Show child attributes

payment.attachment.body.flight_reservation_details.itinerary.departure_city

string

Example:

"departure_city"

payment.attachment.body.flight_reservation_details.itinerary.departure_country

string

Example:

"departure_country"

payment.attachment.body.flight_reservation_details.itinerary.arrival_city

string

Example:

"arrival_city"

payment.attachment.body.flight_reservation_details.itinerary.arrival_country

string

Example:

"arrival_country"

payment.attachment.body.flight_reservation_details.itinerary.carrier

string

Example:

"carrier"

payment.attachment.body.flight_reservation_details.itinerary.departure_date

string<date-time>

RFC3339 e.g. 2018-10-17T07:26:33Z

payment.attachment.body.flight_reservation_details.itinerary.class

string

Example:

"class"

payment.attachment.body.flight_reservation_details.itinerary.refundable

boolean

true - if ticket can be cancelled/refunded

payment.attachment.body.flight_reservation_details.insurance

object[]

required

Insurance data

Show child attributes

payment.attachment.body.flight_reservation_details.insurance.insurance_company

string

Example:

"insurance_company"

payment.attachment.body.flight_reservation_details.insurance.insurance_type

string

Example:

"insurance_type"

payment.attachment.body.flight_reservation_details.insurance.insurance_price

number

Example:

"insurance_price"

payment.attachment.body.flight_reservation_details.passengers

object[]

required

Passengers data

Show child attributes

payment.attachment.body.flight_reservation_details.passengers.full_name

string

Example:

"full_name"

payment.attachment.body.flight_reservation_details.passengers.first_name

string

Example:

"first_name"

payment.attachment.body.flight_reservation_details.passengers.last_name

string

Example:

"last_name"

payment.attachment.body.flight_reservation_details.passengers.dob

string

ISO 8601 date of birth, e.g. 2018-10-17

Example:

"2018-10-17T00:00:00.000Z"

payment.attachment.body.flight_reservation_details.passengers.document_type

string

Example:

"document_type"

payment.attachment.body.flight_reservation_details.passengers.document_id

string

Example:

"document_id"

payment.attachment.body.flight_reservation_details.passengers.expiration_id_date

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.flight_reservation_details.passengers.nationality

string

Example:

"nationality"

payment.attachment.body.flight_reservation_details.passengers.gender

enum<string>

F - female, M - male, O - other

Available options:

F,

M,

O

Example:

"F"

payment.attachment.body.flight_reservation_details.pnr

string

Trip booking number, e.g. TR9088999

Example:

"Trip booking number, e.g. TR9088999"

payment.attachment.body.flight_reservation_details.affiliate_name

string

Name of the affiliate that originated the purchase. If none, leave blank.

Example:

"Name of the affiliate that originated the purchase. If none, leave blank."

payment.attachment.body.hotel_reservation_details

object

Show child attributes

payment.attachment.body.hotel_reservation_details.hotel_itinerary

object[]

required

Hotel itinerary data, one per segment

Show child attributes

payment.attachment.body.hotel_reservation_details.hotel_itinerary.hotel_name

string

Example:

"hotel_name"

payment.attachment.body.hotel_reservation_details.hotel_itinerary.address

string

Example:

"address"

payment.attachment.body.hotel_reservation_details.hotel_itinerary.hotel_city

string

Example:

"hotel_city"

payment.attachment.body.hotel_reservation_details.hotel_itinerary.hotel_country

string

Example:

"hotel_country"

payment.attachment.body.hotel_reservation_details.hotel_itinerary.start_date

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.hotel_reservation_details.hotel_itinerary.end_date

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.hotel_reservation_details.hotel_itinerary.number_of_rooms

integer

Example:

1

payment.attachment.body.hotel_reservation_details.hotel_itinerary.class

string

Example:

"class"

payment.attachment.body.hotel_reservation_details.insurance

object[]

required

Insurance data

Show child attributes

payment.attachment.body.hotel_reservation_details.insurance.insurance_company

string

Example:

"insurance_company"

payment.attachment.body.hotel_reservation_details.insurance.insurance_type

string

Example:

"insurance_type"

payment.attachment.body.hotel_reservation_details.insurance.insurance_price

number

Example:

"insurance_price"

payment.attachment.body.hotel_reservation_details.passengers

object[]

required

Passengers data

Show child attributes

payment.attachment.body.hotel_reservation_details.passengers.full_name

string

Example:

"full_name"

payment.attachment.body.hotel_reservation_details.passengers.first_name

string

Example:

"first_name"

payment.attachment.body.hotel_reservation_details.passengers.last_name

string

Example:

"last_name"

payment.attachment.body.hotel_reservation_details.passengers.dob

string

ISO 8601 date of birth, e.g. 2018-10-17

Example:

"2018-10-17T00:00:00.000Z"

payment.attachment.body.hotel_reservation_details.passengers.document_type

string

Example:

"document_type"

payment.attachment.body.hotel_reservation_details.passengers.document_id

string

Example:

"document_id"

payment.attachment.body.hotel_reservation_details.passengers.expiration_id_dt

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.hotel_reservation_details.passengers.nationality

string

Example:

"nationality"

payment.attachment.body.hotel_reservation_details.passengers.gender

enum<string>

F - female, M - male, O - other

Available options:

F,

M,

O

Example:

"M"

payment.attachment.body.hotel_reservation_details.pnr

string

Trip booking number, e.g. TR9088999

Example:

"TR9088999"

payment.attachment.body.hotel_reservation_details.affiliate_name

string

Name of the affiliate that originated the purchase. If none, leave blank.

Example:

"Name of the affiliate that originated the purchase. If none, leave blank."

payment.attachment.body.insurance_details

object

Show child attributes

payment.attachment.body.insurance_details.policy_details

object

required

Information about insurance

Show child attributes

payment.attachment.body.insurance_details.policy_details.insurance_type

string

required

Insurance policy type

Example:

"Insurance policy type"

payment.attachment.body.insurance_details.policy_details.insurance_start_dt

string

required

ISO 8601 start date, e.g. 2018-10-17

Example:

"2018-10-17T00:00:00.000Z"

payment.attachment.body.insurance_details.policy_details.insurance_end_dt

string

required

ISO 8601 end date, e.g. 2018-10-17

Example:

"2018-10-17T00:00:00.000Z"

payment.attachment.body.insurance_details.policy_details.insured_amount

string

required

Amount of insurance policy

Example:

"100"

payment.attachment.body.insurance_details.policy_details.car_details

object

Required for car insurance

Show child attributes

payment.attachment.body.insurance_details.policy_details.car_details.manufacturer

string

required

Example:

"manufacturer"

payment.attachment.body.insurance_details.policy_details.car_details.model

string

required

Example:

"model"

payment.attachment.body.insurance_details.policy_details.car_details.year

string

required

Example:

"year"

payment.attachment.body.insurance_details.policy_details.travel_details

object

Required for travel insurance

Show child attributes

payment.attachment.body.insurance_details.policy_details.travel_details.departure_country

string

required

Example:

"departure_country"

payment.attachment.body.insurance_details.policy_details.travel_details.arrival_country

string

required

Example:

"arrival_country"

payment.attachment.body.insurance_details.policy_details.refundable

boolean

If insurance can be cancelled/refunded - true, otherwise - false

payment.attachment.body.insurance_details.policy_details.provider_name

string

Example:

"provider_name"

payment.attachment.body.insurance_details.client

object

required

Show child attributes

payment.attachment.body.insurance_details.client.first_name

string

required

Example:

"first_name"

payment.attachment.body.insurance_details.client.last_name

string

required

Example:

"last_name"

payment.attachment.body.insurance_details.client.document_type

string

required

Example:

"document_type"

payment.attachment.body.insurance_details.client.full_name

string

Example:

"full_name"

payment.attachment.body.insurance_details.client.dob

string

ISO 8601 date of birth, e.g. 2018-10-17

Example:

"2018-10-17T00:00:00.000Z"

payment.attachment.body.insurance_details.client.document_id

string

Example:

"document_id"

payment.attachment.body.insurance_details.client.expiration_id_dt

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.insurance_details.client.nationality

string

Example:

"nationality"

payment.attachment.body.insurance_details.client.gender

any

F - female, M - male, O - other

Example:

"F"

payment.attachment.body.insurance_details.payment_history_simple

object

Show child attributes

payment.attachment.body.insurance_details.payment_history_simple.date_of_last_paid_purchase

string<date>

required

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.insurance_details.payment_history_simple.date_of_first_paid_purchase

string<date>

required

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.insurance_details.payment_history_simple.unique_account_identifier

string

Unique name / number to identify the specific customer account

Example:

"unique name / id of the customer"

payment.attachment.body.insurance_details.payment_history_simple.paid_before_flag

boolean

Whether the customer has paid before or not

payment.attachment.body.payment_history_full

object

Show child attributes

payment.attachment.body.payment_history_full.unique_account_identifier

string

Unique name / number to identify the specific customer account

Example:

"unique name / id of the customer"

payment.attachment.body.payment_history_full.payment_option

enum<string>

One of - card / direct banking / COD (cash) / other

Available options:

card,

direct banking,

cod,

other

Example:

"card"

payment.attachment.body.payment_history_full.number_paid_purchases

number

Example:

1

payment.attachment.body.payment_history_full.total_amount_paid_purchases

number

Example:

1

payment.attachment.body.payment_history_full.date_of_last_paid_purchase

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.payment_history_full.date_of_first_paid_purchase

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.payment_history_full.count_paid_purchases_last_month

number

Example:

1

payment.attachment.body.payment_history_full.amount_paid_purchases_last_month

number

Example:

1

payment.attachment.body.payment_history_full.max_paid_amount_for_1purchase

number

Example:

1

payment.attachment.body.payment_history_simple

object

Show child attributes

payment.attachment.body.payment_history_simple.unique_account_identifier

string

Unique name / number to identify the specific customer account

Example:

"unique name / id of the customer"

payment.attachment.body.payment_history_simple.paid_before_flag

boolean

Whether the customer has paid before or not

payment.attachment.body.payment_history_simple.date_of_last_paid_purchase

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.payment_history_simple.date_of_first_paid_purchase

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.flight_points_simple

object

Show child attributes

payment.attachment.body.flight_points_simple.origin

object

required

Origin city and airport

Show child attributes

payment.attachment.body.flight_points_simple.origin.air_code

string

required

Origin IATA airport code, for example - JFK

Example:

"JFK"

payment.attachment.body.flight_points_simple.origin.city_code

string

required

Origin city code, for example - NYC

Example:

"NYC"

payment.attachment.body.flight_points_simple.destination

object

required

Destination city and airport

Show child attributes

payment.attachment.body.flight_points_simple.destination.air_code

string

required

Destination IATA airport code, for example - LAX

Example:

"LAX"

payment.attachment.body.flight_points_simple.destination.city_code

string

required

Destination city code, for example - LAX

Example:

"LAX"

payment.attachment.body.marketplaces

object

Sellers' details within marketplaces.

Show child attributes

payment.attachment.body.marketplaces.seller_id

string

required

Unique ID of the seller within your marketplace.

Example:

"57327813"

payment.attachment.body.marketplaces.seller_name

string

required

Name of the seller within your marketplace.

Example:

"Pet Shop"

payment.attachment.body.marketplaces.seller_category

string

required

Category of the seller within your marketplace.

Example:

"Electronics"

payment.attachment.body.marketplaces.seller_website

string

required

Website of the seller within your marketplace.

Example:

"https://www.petshop.com"

payment.attachment.body.marketplaces.seller_phone

string

required

Seller's phone number.

Example:

"500000001"

payment.attachment.body.marketplaces.seller_registration_date

string<date-time>

required

Seller's registration date, in UTC, and displayed in ISO 8601 datetime format.

payment.attachment.body.marketplaces.seller_commercial_registration_number

string

required

Seller's commercial registration number.

Example:

"1012345678"

Example:

"{\"flight_reservation_details\": {\"pnr\": \"TR9088999\",\"itinerary\": [...],\"insurance\": [...],\"passengers\": [...],\"affiliate_name\": \"some affiliate\"}}"

payment.attachment.content_type

string

default:application/vnd.tabby.v1+json

required

Version of used schema

lang

enum<string>

required

Session language, used to launch HPP with desired language.

Available options:

ar,

en

Example:

"en"

merchant_code

string

required

Please contact your integration manager to get the merchant code.

Example:

"code provided to you from Tabby side"

merchant_urls

object

Used for redirecting the customer after Tabby Checkout flow. Required for Web integration, optional for Mobile App integration.

Show child attributes

merchant_urls.success

string<uri>

URL to redirect the customer to merchant's 'Thank you' page after success payment. Payment status = AUTHORIZED or CLOSED.

Example:

"https://your-store/success"

merchant_urls.cancel

string<uri>

URL to redirect the customer back to merchant's Checkout page after payment cancellation by customer. Payment status = EXPIRED.

Example:

"https://your-store/cancel"

merchant_urls.failure

string<uri>

URL to redirect the customer back to merchant's Checkout page after payment rejection by Tabby. Payment status = REJECTED.

Example:

"https://your-store/failure"

token

string

If you already have token, you can pass it there. Authorization header still requires Secret Key.

Response

Success. Checkout session object is returned.

string<uuid>

Unique identifier for the checkout Session, assigned by Tabby.

Example:

"session id, uuid format"

configuration

object

Some details associated with the current session.

Show child attributes

configuration.available_products

object

Show child attributes

configuration.available_products.installments

object[] | null

Links to redirect customers to Tabby Checkout.

Show child attributes

configuration.available_products.installments.web_url

string<uri> | null

Example:

"https://checkout.tabby.ai/"

configuration.available_products.installments.qr_code

string<uri> | null

Example:

"https://api.tabby.ai/api/v2/checkout/{id}/hpp_link_qr"

configuration.products

object

Products and theirs availability

Show child attributes

configuration.products.installments

object

Show child attributes

configuration.products.installments.type

enum<string>

required

Type of product.

Available options:

installments

Example:

"installments"

configuration.products.installments.is_available

boolean

required

Example:

true

configuration.products.installments.rejection_reason

enum<string> | null

The reason why this product is not available to use Possible values:

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.'
not_available - 'Sorry, Tabby is unable to approve this purchase, please use an alternative payment method for your order.'
null - if is_available is true and customer is able to use it.

Available options:

order_amount_too_high,

order_amount_too_low,

not_available,

null

Example:

null

token

string | null

In the response, this field will be filled with token value if session status is 'approved'. You can use that token for Tokenized Payments and Web Checkout.

Example:

null

payment

object

Payment object associated with the current session.

Show child attributes

payment.amount

string

required

Total payment amount, including tax, shipping and any discounts. Allows to send up to 2 decimals for AED and SAR, up to 3 decimals for KWD.

Example:

"100"

payment.currency

enum<string>

required

ISO 4217 currency code for the payment amount. Currently there are 3 possible currency options - depending on the country where the store is located:

AED - United Arab Emirates Dirham
SAR - Saudi Riyal
KWD - Kuwaiti Dinar

Available options:

AED,

SAR,

KWD

Example:

"AED"

payment.order

object

required

Show child attributes

payment.order.reference_id

string | null

required

Merchant-assigned order number.

Example:

"1001"

payment.order.items

object[] | null

required

Array of objects representing the order items in this payment.

Show child attributes

payment.order.items.title

string | null

required

Name of the product.

Example:

"Name of the product"

payment.order.items.quantity

integer

default:0

required

Quantity of the product ordered.

Required range: x >= 0

Example:

1

payment.order.items.unit_price

string

default:0

required

Price per unit of the product. Should be positive or zero.

Example:

"0.00"

payment.order.items.category

string | null

required

Required as name of high-level category (Clothes, Electronics,etc.); or a tree of category-subcategory1-subcategory2; or id of the category and table with category-ids data mapped provided.

Example:

"Clothes"

payment.order.items.reference_id

string | null

Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.

Example:

"SKU123"

payment.order.items.description

string | null

Description of the product.

Example:

"Description of the product"

payment.order.items.image_url

string<uri> | null

URL of the item image to show in the order information.

Example:

"https://example.com/"

payment.order.items.product_url

string<uri> | null

URL of the item at your store.

Example:

"https://example.com/"

payment.order.items.gender

enum<string> | null

Who the goods are designed to.

Available options:

Male,

Female,

Kids,

Other

Example:

"Kids"

payment.order.items.color

string | null

white / blue/ green

Example:

"white"

payment.order.items.product_material

string | null

cotton / polyester / synthetic

Example:

"cotton"

payment.order.items.size_type

string | null

EU / UK

Example:

"EU"

payment.order.items.size

string | null

L / XL / 12

Example:

"M"

payment.order.items.brand

string | null

Mango / Dorothy Perkins / Tommy Hilfiger

Example:

"Name of the Brand"

payment.order.items.is_refundable

boolean | null

Indicates whether a product can be returned

payment.order.updated_at

string<date-time>

Date and time the order was last updated, in UTC, and displayed in ISO 8601 datetime format.

payment.order.tax_amount

string

default:0

Total tax for the order.

Example:

"0.00"

payment.order.shipping_amount

string

default:0

Total shipping cost for the order.

Example:

"0.00"

payment.order.discount_amount

string

default:0

Total discount for the order. Should be positive or zero. Shows up on Tabby App for the Customer's convenience.

Example:

"0.00"

payment.id

string<uuid>

Unique identifier for the payment (UUID), assigned by Tabby. Save it on your side!

Example:

"payment id, uuid format"

payment.created_at

string<date-time>

Date and time the payment was created, in UTC, and displayed in ISO 8601 datetime format.

payment.status

enum<string>

Status of the current payment:

CREATED means that the payment is created successfully, but not finished yet;
AUTHORIZED and CLOSED mark the successfully approved and captured payments accordingly;
REJECTED is returned when a customer is rejected during Tabby Checkout;
EXPIRED is used when a customer cancels a payment or when Tabby doesn't receive a successfully paid transaction after timeout.

Available options:

CREATED,

AUTHORIZED,

CLOSED,

REJECTED,

EXPIRED

Example:

"CREATED"

payment.is_test

boolean

Indicates whether this is a test payment (created using the Test API keys or Production API Keys).

payment.description

string | null

Example:

"test payload"

payment.meta

object

Merchant-defined data about the payment. This field is a key-value map. The example properties provided below.

Show child attributes

payment.meta.customer

string | null

Example:

"#customer-id"

payment.meta.order_id

string | null

Example:

"#1234"

payment.attachment

object

Extra data (booking info, insurance, flight reservations, ...) as serialized JSON

Show child attributes

payment.attachment.body

object

required

Should be an object containing any of the keys with corresponded sub objects

Show child attributes

payment.attachment.body.flight_reservation_details

object

Show child attributes

payment.attachment.body.flight_reservation_details.itinerary

object[]

required

Itinerary data, one per segment

Show child attributes

payment.attachment.body.flight_reservation_details.itinerary.departure_city

string

Example:

"departure_city"

payment.attachment.body.flight_reservation_details.itinerary.departure_country

string

Example:

"departure_country"

payment.attachment.body.flight_reservation_details.itinerary.arrival_city

string

Example:

"arrival_city"

payment.attachment.body.flight_reservation_details.itinerary.arrival_country

string

Example:

"arrival_country"

payment.attachment.body.flight_reservation_details.itinerary.carrier

string

Example:

"carrier"

payment.attachment.body.flight_reservation_details.itinerary.departure_date

string<date-time>

RFC3339 e.g. 2018-10-17T07:26:33Z

payment.attachment.body.flight_reservation_details.itinerary.class

string

Example:

"class"

payment.attachment.body.flight_reservation_details.itinerary.refundable

boolean

true - if ticket can be cancelled/refunded

payment.attachment.body.flight_reservation_details.insurance

object[]

required

Insurance data

Show child attributes

payment.attachment.body.flight_reservation_details.insurance.insurance_company

string

Example:

"insurance_company"

payment.attachment.body.flight_reservation_details.insurance.insurance_type

string

Example:

"insurance_type"

payment.attachment.body.flight_reservation_details.insurance.insurance_price

number

Example:

"insurance_price"

payment.attachment.body.flight_reservation_details.passengers

object[]

required

Passengers data

Show child attributes

payment.attachment.body.flight_reservation_details.passengers.full_name

string

Example:

"full_name"

payment.attachment.body.flight_reservation_details.passengers.first_name

string

Example:

"first_name"

payment.attachment.body.flight_reservation_details.passengers.last_name

string

Example:

"last_name"

payment.attachment.body.flight_reservation_details.passengers.dob

string

ISO 8601 date of birth, e.g. 2018-10-17

Example:

"2018-10-17T00:00:00.000Z"

payment.attachment.body.flight_reservation_details.passengers.document_type

string

Example:

"document_type"

payment.attachment.body.flight_reservation_details.passengers.document_id

string

Example:

"document_id"

payment.attachment.body.flight_reservation_details.passengers.expiration_id_date

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.flight_reservation_details.passengers.nationality

string

Example:

"nationality"

payment.attachment.body.flight_reservation_details.passengers.gender

enum<string>

F - female, M - male, O - other

Available options:

F,

M,

O

Example:

"F"

payment.attachment.body.flight_reservation_details.pnr

string

Trip booking number, e.g. TR9088999

Example:

"Trip booking number, e.g. TR9088999"

payment.attachment.body.flight_reservation_details.affiliate_name

string

Name of the affiliate that originated the purchase. If none, leave blank.

Example:

"Name of the affiliate that originated the purchase. If none, leave blank."

payment.attachment.body.hotel_reservation_details

object

Show child attributes

payment.attachment.body.hotel_reservation_details.hotel_itinerary

object[]

required

Hotel itinerary data, one per segment

Show child attributes

payment.attachment.body.hotel_reservation_details.hotel_itinerary.hotel_name

string

Example:

"hotel_name"

payment.attachment.body.hotel_reservation_details.hotel_itinerary.address

string

Example:

"address"

payment.attachment.body.hotel_reservation_details.hotel_itinerary.hotel_city

string

Example:

"hotel_city"

payment.attachment.body.hotel_reservation_details.hotel_itinerary.hotel_country

string

Example:

"hotel_country"

payment.attachment.body.hotel_reservation_details.hotel_itinerary.start_date

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.hotel_reservation_details.hotel_itinerary.end_date

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.hotel_reservation_details.hotel_itinerary.number_of_rooms

integer

Example:

1

payment.attachment.body.hotel_reservation_details.hotel_itinerary.class

string

Example:

"class"

payment.attachment.body.hotel_reservation_details.insurance

object[]

required

Insurance data

Show child attributes

payment.attachment.body.hotel_reservation_details.insurance.insurance_company

string

Example:

"insurance_company"

payment.attachment.body.hotel_reservation_details.insurance.insurance_type

string

Example:

"insurance_type"

payment.attachment.body.hotel_reservation_details.insurance.insurance_price

number

Example:

"insurance_price"

payment.attachment.body.hotel_reservation_details.passengers

object[]

required

Passengers data

Show child attributes

payment.attachment.body.hotel_reservation_details.passengers.full_name

string

Example:

"full_name"

payment.attachment.body.hotel_reservation_details.passengers.first_name

string

Example:

"first_name"

payment.attachment.body.hotel_reservation_details.passengers.last_name

string

Example:

"last_name"

payment.attachment.body.hotel_reservation_details.passengers.dob

string

ISO 8601 date of birth, e.g. 2018-10-17

Example:

"2018-10-17T00:00:00.000Z"

payment.attachment.body.hotel_reservation_details.passengers.document_type

string

Example:

"document_type"

payment.attachment.body.hotel_reservation_details.passengers.document_id

string

Example:

"document_id"

payment.attachment.body.hotel_reservation_details.passengers.expiration_id_dt

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.hotel_reservation_details.passengers.nationality

string

Example:

"nationality"

payment.attachment.body.hotel_reservation_details.passengers.gender

enum<string>

F - female, M - male, O - other

Available options:

F,

M,

O

Example:

"M"

payment.attachment.body.hotel_reservation_details.pnr

string

Trip booking number, e.g. TR9088999

Example:

"TR9088999"

payment.attachment.body.hotel_reservation_details.affiliate_name

string

Name of the affiliate that originated the purchase. If none, leave blank.

Example:

"Name of the affiliate that originated the purchase. If none, leave blank."

payment.attachment.body.insurance_details

object

Show child attributes

payment.attachment.body.insurance_details.policy_details

object

required

Information about insurance

Show child attributes

payment.attachment.body.insurance_details.policy_details.insurance_type

string

required

Insurance policy type

Example:

"Insurance policy type"

payment.attachment.body.insurance_details.policy_details.insurance_start_dt

string

required

ISO 8601 start date, e.g. 2018-10-17

Example:

"2018-10-17T00:00:00.000Z"

payment.attachment.body.insurance_details.policy_details.insurance_end_dt

string

required

ISO 8601 end date, e.g. 2018-10-17

Example:

"2018-10-17T00:00:00.000Z"

payment.attachment.body.insurance_details.policy_details.insured_amount

string

required

Amount of insurance policy

Example:

"100"

payment.attachment.body.insurance_details.policy_details.car_details

object

Required for car insurance

Show child attributes

payment.attachment.body.insurance_details.policy_details.car_details.manufacturer

string

required

Example:

"manufacturer"

payment.attachment.body.insurance_details.policy_details.car_details.model

string

required

Example:

"model"

payment.attachment.body.insurance_details.policy_details.car_details.year

string

required

Example:

"year"

payment.attachment.body.insurance_details.policy_details.travel_details

object

Required for travel insurance

Show child attributes

payment.attachment.body.insurance_details.policy_details.travel_details.departure_country

string

required

Example:

"departure_country"

payment.attachment.body.insurance_details.policy_details.travel_details.arrival_country

string

required

Example:

"arrival_country"

payment.attachment.body.insurance_details.policy_details.refundable

boolean

If insurance can be cancelled/refunded - true, otherwise - false

payment.attachment.body.insurance_details.policy_details.provider_name

string

Example:

"provider_name"

payment.attachment.body.insurance_details.client

object

required

Show child attributes

payment.attachment.body.insurance_details.client.first_name

string

required

Example:

"first_name"

payment.attachment.body.insurance_details.client.last_name

string

required

Example:

"last_name"

payment.attachment.body.insurance_details.client.document_type

string

required

Example:

"document_type"

payment.attachment.body.insurance_details.client.full_name

string

Example:

"full_name"

payment.attachment.body.insurance_details.client.dob

string

ISO 8601 date of birth, e.g. 2018-10-17

Example:

"2018-10-17T00:00:00.000Z"

payment.attachment.body.insurance_details.client.document_id

string

Example:

"document_id"

payment.attachment.body.insurance_details.client.expiration_id_dt

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.insurance_details.client.nationality

string

Example:

"nationality"

payment.attachment.body.insurance_details.client.gender

any

F - female, M - male, O - other

Example:

"F"

payment.attachment.body.insurance_details.payment_history_simple

object

Show child attributes

payment.attachment.body.insurance_details.payment_history_simple.date_of_last_paid_purchase

string<date>

required

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.insurance_details.payment_history_simple.date_of_first_paid_purchase

string<date>

required

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.insurance_details.payment_history_simple.unique_account_identifier

string

Unique name / number to identify the specific customer account

Example:

"unique name / id of the customer"

payment.attachment.body.insurance_details.payment_history_simple.paid_before_flag

boolean

Whether the customer has paid before or not

payment.attachment.body.payment_history_full

object

Show child attributes

payment.attachment.body.payment_history_full.unique_account_identifier

string

Unique name / number to identify the specific customer account

Example:

"unique name / id of the customer"

payment.attachment.body.payment_history_full.payment_option

enum<string>

One of - card / direct banking / COD (cash) / other

Available options:

card,

direct banking,

cod,

other

Example:

"card"

payment.attachment.body.payment_history_full.number_paid_purchases

number

Example:

1

payment.attachment.body.payment_history_full.total_amount_paid_purchases

number

Example:

1

payment.attachment.body.payment_history_full.date_of_last_paid_purchase

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.payment_history_full.date_of_first_paid_purchase

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.payment_history_full.count_paid_purchases_last_month

number

Example:

1

payment.attachment.body.payment_history_full.amount_paid_purchases_last_month

number

Example:

1

payment.attachment.body.payment_history_full.max_paid_amount_for_1purchase

number

Example:

1

payment.attachment.body.payment_history_simple

object

Show child attributes

payment.attachment.body.payment_history_simple.unique_account_identifier

string

Unique name / number to identify the specific customer account

Example:

"unique name / id of the customer"

payment.attachment.body.payment_history_simple.paid_before_flag

boolean

Whether the customer has paid before or not

payment.attachment.body.payment_history_simple.date_of_last_paid_purchase

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.payment_history_simple.date_of_first_paid_purchase

string<date>

ISO 8601 date e.g. 2018-10-17

payment.attachment.body.flight_points_simple

object

Show child attributes

payment.attachment.body.flight_points_simple.origin

object

required

Origin city and airport

Show child attributes

payment.attachment.body.flight_points_simple.origin.air_code

string

required

Origin IATA airport code, for example - JFK

Example:

"JFK"

payment.attachment.body.flight_points_simple.origin.city_code

string

required

Origin city code, for example - NYC

Example:

"NYC"

payment.attachment.body.flight_points_simple.destination

object

required

Destination city and airport

Show child attributes

payment.attachment.body.flight_points_simple.destination.air_code

string

required

Destination IATA airport code, for example - LAX

Example:

"LAX"

payment.attachment.body.flight_points_simple.destination.city_code

string

required

Destination city code, for example - LAX

Example:

"LAX"

payment.attachment.body.marketplaces

object

Sellers' details within marketplaces.

Show child attributes

payment.attachment.body.marketplaces.seller_id

string

required

Unique ID of the seller within your marketplace.

Example:

"57327813"

payment.attachment.body.marketplaces.seller_name

string

required

Name of the seller within your marketplace.

Example:

"Pet Shop"

payment.attachment.body.marketplaces.seller_category

string

required

Category of the seller within your marketplace.

Example:

"Electronics"

payment.attachment.body.marketplaces.seller_website

string

required

Website of the seller within your marketplace.

Example:

"https://www.petshop.com"

payment.attachment.body.marketplaces.seller_phone

string

required

Seller's phone number.

Example:

"500000001"

payment.attachment.body.marketplaces.seller_registration_date

string<date-time>

required

Seller's registration date, in UTC, and displayed in ISO 8601 datetime format.

payment.attachment.body.marketplaces.seller_commercial_registration_number

string

required

Seller's commercial registration number.

Example:

"1012345678"

Example:

"{\"flight_reservation_details\": {\"pnr\": \"TR9088999\",\"itinerary\": [...],\"insurance\": [...],\"passengers\": [...],\"affiliate_name\": \"some affiliate\"}}"

payment.attachment.content_type

string

default:application/vnd.tabby.v1+json

required

Version of used schema

status

enum<string>

Status of the current session. Used at the pre-scoring and session creation steps.

created is returned when the request is approved and the customer is eligible to use Tabby
rejected means that there are no available products for a customer
expired and approved - used for specific type of integration, kindly ignore them if not communicated directly

Available options:

created,

rejected,

expired,

approved

Example:

"created"

merchant_urls

object

Show child attributes

merchant_urls.success

string<uri> | null

URL where to redirect after payment is Authorized. 'Thank you' page recommended.

Example:

"https://your-store/success"

merchant_urls.cancel

string<uri> | null

URL where to proceed after cancel payment status. Checkout page recommended.

Example:

"https://your-store/cancel"

merchant_urls.failure

string<uri> | null

URL where to proceed after failure payment status (Rejected). Checkout page recommended.

Example:

"https://your-store/failure"

API Playground

Checkout

Payments

Webhooks

Disputes

Create a session

Authorizations

Body

Response