> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tabby.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve an existing checkout session
> Use this API to retrieve the token (only if tokens used in your integration )
> [!WARNING]
>
> This endpoint is intentionally hidden from the main API documentation and should only be used in specific integrations where its purpose is well understood. It is accessible via direct link for those who require it, but is not intended for general use or new standard implementations.
## OpenAPI
````yaml get /api/v2/checkout/{id}
openapi: 3.1.0
info:
title: Tabby API Reference
version: 1.0.0
x-logo:
url: assets/tabby-new.png
altText: tabby Logo
description: |
Tabby Documentation: **[docs.tabby.ai](https://docs.tabby.ai/)**
servers:
- url: https://api.tabby.ai/
description: Production (UAE)
- url: https://api.tabby.sa/
description: Production (KSA)
security: []
tags:
- name: Checkout
description: >-
Checkout is a whole process of customer data collection and payment
authorization.
- name: Payments
description: >-
The core of tabby is a payments flow enabling you to handle payments at
your webstore.
- name: Webhooks
description: Manage webhook endpoints.
- name: Dispute webhooks
description: >-
Manage dispute webhook endpoints. Live secret key and `X-Merchant-Code` on
every request; disputes have no test mode.
- name: Disputes
description: >-
The Disputes API is designed to simplify the process of handling disputes
and help merchants resolve issues with customer orders more efficiently.
Merchants can use this API to retrieve a list of disputes, view details
about a specific dispute, and approve or challenge a bunch of disputes. It
mirrors the functionality available in Tabby Merchant Dashboard and
operates exclusively with live payments using live credentials. A secret
key is required for using the Disputes API.
paths:
/api/v2/checkout/{id}:
get:
tags:
- Checkout
summary: Retrieve an existing checkout session
description: >-
Use this API to retrieve the token (only if tokens used in your
integration )
operationId: getCheckoutSession
parameters:
- $ref: '#/components/parameters/sessionIdParam'
responses:
'200':
$ref: '#/components/responses/CheckoutSession'
'400':
$ref: '#/components/responses/BadRequestError_invalid_session_id'
'401':
$ref: '#/components/responses/AuthenticationError_key_doesnt_exist'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError_no_session'
'500':
$ref: '#/components/responses/UnexpectedError'
security:
- bearerAuth:
- secret_key
components:
parameters:
sessionIdParam:
in: path
name: id
required: true
schema:
type: string
format: uuid
example: session id, uuid format
description: ID of the session.
responses:
CheckoutSession:
description: Success. Checkout session object is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutSession'
BadRequestError_invalid_session_id:
description: The session ID in the path is not a valid UUID.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_400_invalid_session_id'
AuthenticationError_key_doesnt_exist:
description: The request cannot be authorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_401_key_doesnt_exist'
ForbiddenError:
description: You tried to perform an action which is forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_403'
NotFoundError_no_session:
description: >-
No session with this ID exists for your merchant. A session that belongs
to another merchant returns the same response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_404_no_session'
UnexpectedError:
description: Something bad happened. We're notified.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_500'
schemas:
CheckoutSession:
type: object
properties:
id:
type: string
format: uuid
example: session id, uuid format
readOnly: true
description: Unique identifier for the checkout Session, assigned by Tabby.
configuration:
type: object
description: Some details associated with the current session.
properties:
available_products:
type: object
nullable: true
properties:
installments:
$ref: '#/components/schemas/CheckoutConfigurationProduct'
description: Links to redirect customers to Tabby Checkout.
products:
type: object
description: Products and theirs availability
properties:
installments:
$ref: '#/components/schemas/CheckoutProduct'
token:
type: string
example: null
nullable: true
description: >
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.
payment:
$ref: '#/components/schemas/CheckoutResponsePayment'
status:
type: string
readOnly: true
enum:
- created
- rejected
- expired
- approved
example: created
description: >
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
merchant_urls:
type: object
properties:
success:
type: string
nullable: true
format: uri
example: https://your-store/success
description: >-
URL where to redirect after payment is Authorized. 'Thank you'
page recommended.
cancel:
type: string
nullable: true
format: uri
example: https://your-store/cancel
description: >-
URL where to proceed after cancel payment status. Checkout page
recommended.
failure:
type: string
nullable: true
format: uri
example: https://your-store/failure
description: >-
URL where to proceed after failure payment status (Rejected).
Checkout page recommended.
merchant:
type: object
readOnly: true
description: Merchant the session was created for.
properties:
name:
type: string
example: Your store name
description: Name of your store as registered with Tabby.
Error_400_invalid_session_id:
type: object
properties:
status:
type: string
example: error
errorType:
type: string
example: bad_data
error:
type: string
example: sessionID must be a valid UUID
Error_401_key_doesnt_exist:
type: object
properties:
status:
type: string
example: error
errorType:
type: string
example: not_authorized
error:
type: string
example: 'auth: provided key doesn''t exist'
Error_403:
type: object
properties:
status:
type: string
example: error
errorType:
type: string
example: no_permission
Error_404_no_session:
type: object
properties:
status:
type: string
example: error
errorType:
type: string
example: not_found
error:
type: string
example: no session
Error_500:
type: object
properties:
status:
type: string
example: error
errorType:
type: string
example: internal
error:
type: string
example: Internal Server Error
CheckoutConfigurationProduct:
type: array
nullable: true
items:
type: object
properties:
web_url:
type: string
nullable: true
format: uri
example: https://checkout.tabby.ai/
description: 'UAE: checkout.tabby.ai, KSA: checkout.tabby.sa'
readOnly: true
qr_code:
type: string
nullable: true
format: uri
example: https://api.tabby.ai/api/v2/checkout/{id}/hpp_link_qr
description: 'UAE: api.tabby.ai, KSA: api.tabby.sa'
readOnly: true
CheckoutProduct:
type: object
properties:
type:
type: string
enum:
- installments
example: installments
description: Type of product.
readOnly: true
is_available:
type: boolean
example: true
readOnly: true
rejection_reason:
$ref: '#/components/schemas/CheckoutProductRejectionReason'
required:
- type
- is_available
CheckoutResponsePayment:
description: Payment object associated with the current session.
type: object
properties:
id:
$ref: '#/components/schemas/PaymentID'
created_at:
$ref: '#/components/schemas/PaymentCreatedAt'
status:
$ref: '#/components/schemas/PaymentStatus'
example: CREATED
is_test:
readOnly: true
type: boolean
description: >-
Indicates whether this is a test payment (created using the Test API
keys or Production API Keys).
amount:
$ref: '#/components/schemas/PaymentAmount'
currency:
$ref: '#/components/schemas/Currency'
description:
type: string
nullable: true
example: test payload
order:
$ref: '#/components/schemas/OrderResponse'
meta:
$ref: '#/components/schemas/Meta'
attachment:
$ref: '#/components/schemas/Attachment_V1'
required:
- amount
- currency
- buyer
- order
- buyer_history
- order_history
- shipping_address
CheckoutProductRejectionReason:
type: string
nullable: true
enum:
- order_amount_too_high
- order_amount_too_low
- not_available
- 'null'
example: null
description: |
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.
PaymentID:
type: string
format: uuid
example: payment id, uuid format
readOnly: true
description: >-
Unique identifier for the payment (UUID), assigned by Tabby. Save it on
your side!
PaymentCreatedAt:
type: string
readOnly: true
format: date-time
description: >-
Date and time the payment was created, in UTC, and displayed in ISO 8601
datetime format.
PaymentStatus:
type: string
readOnly: true
enum:
- CREATED
- AUTHORIZED
- CLOSED
- REJECTED
- EXPIRED
example: CLOSED
description: >
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.
PaymentAmount:
type: string
example: '100'
description: >-
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.
Currency:
type: string
enum:
- AED
- SAR
example: AED
description: >
ISO 4217 currency code for the payment amount. Currently there are 2
possible currency options - depending on the country where the store is
located:
- `AED` - United Arab Emirates Dirham
- `SAR` - Saudi Riyal
OrderResponse:
type: object
nullable: true
properties:
reference_id:
type: string
nullable: true
example: '1001'
description: Merchant-assigned order number.
updated_at:
type: string
format: date-time
description: >-
Date and time the order was last updated, in UTC, and displayed in
ISO 8601 datetime format.
tax_amount:
type: string
default: '0'
example: '0.00'
description: Total tax for the order.
shipping_amount:
type: string
default: '0'
example: '0.00'
description: Total shipping cost for the order.
discount_amount:
type: string
default: '0'
example: '0.00'
description: >-
Total discount for the order. Should be positive or zero. Shows up
on Tabby App for the Customer's convenience.
items:
type: array
nullable: true
items:
$ref: '#/components/schemas/OrderItemResponse'
description: Array of objects representing the order items in this payment.
required:
- items
- reference_id
Meta:
description: >-
Merchant-defined data about the payment. This field is a key-value map.
The example properties provided below.
type: object
nullable: true
properties:
customer:
type: string
nullable: true
example: '#customer-id'
order_id:
type: string
nullable: true
example: '#1234'
Attachment_V1:
type: object
nullable: true
description: >-
Extra data (booking info, insurance, flight reservations, ...) as
serialized JSON
properties:
body:
description: >-
Should be an object containing any of the keys with corresponded sub
objects
example: >-
{"flight_reservation_details": {"pnr": "TR9088999","itinerary":
[...],"insurance": [...],"passengers": [...],"affiliate_name": "some
affiliate"}}
properties:
flight_reservation_details:
$ref: '#/components/schemas/FlightReservationDetails'
hotel_reservation_details:
$ref: '#/components/schemas/HotelReservationDetails'
insurance_details:
$ref: '#/components/schemas/InsuranceDetails'
payment_history_full:
$ref: '#/components/schemas/AttachmentPaymentHistoryFull'
payment_history_simple:
$ref: '#/components/schemas/AttachmentPaymentHistorySimple'
flight_points_simple:
$ref: '#/components/schemas/FlightPointsSimple'
marketplaces:
$ref: '#/components/schemas/Marketplaces'
education_details:
$ref: '#/components/schemas/EducationDetails'
content_type:
description: Version of used schema
type: string
default: application/vnd.tabby.v1+json
OrderItemResponse:
type: object
properties:
reference_id:
type: string
nullable: true
example: SKU123
description: >-
Merchant’s product identifier. Displayed in Customer's App and
Merchant Dashboard, used for Item refunds and disputes.
title:
type: string
nullable: true
example: Name of the product
description: Name of the product.
description:
type: string
nullable: true
example: Description of the product
description: Description of the product.
quantity:
type: integer
default: 0
minimum: 0
example: 1
description: Quantity of the product ordered.
unit_price:
type: string
default: '0'
example: '0.00'
description: Price per unit of the product. Should be positive or zero.
image_url:
type: string
nullable: true
format: uri
example: https://example.com/
description: URL of the item image to show in the order information.
product_url:
type: string
nullable: true
format: uri
example: https://example.com/
description: URL of the item at your store.
gender:
type: string
nullable: true
enum:
- Male
- Female
- Kids
- Other
example: Kids
description: Who the goods are designed to.
category:
type: string
nullable: true
example: Clothes
description: >-
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.
color:
type: string
nullable: true
example: white
description: white / blue/ green
product_material:
type: string
nullable: true
example: cotton
description: cotton / polyester / synthetic
size_type:
type: string
nullable: true
example: EU
description: EU / UK
size:
type: string
nullable: true
example: M
description: L / XL / 12
brand:
type: string
nullable: true
example: Name of the Brand
description: Mango / Dorothy Perkins / Tommy Hilfiger
is_refundable:
type: boolean
nullable: true
description: Indicates whether a product can be returned
required:
- title
- quantity
- unit_price
- category
FlightReservationDetails:
type: object
properties:
itinerary:
description: Itinerary data, one per segment
type: array
items:
type: object
properties:
departure_city:
type: string
example: departure_city
departure_country:
type: string
example: departure_country
arrival_city:
type: string
example: arrival_city
arrival_country:
type: string
example: arrival_country
carrier:
type: string
example: carrier
departure_date:
description: RFC3339 e.g. 2018-10-17T07:26:33Z
type: string
format: date-time
pattern: >-
^2[0-9]{3}-[0-1][0-9]-[0-3][0-9]T[0-2][0-9]:[0-5][0-9]:[0-5][0-9]Z$
class:
type: string
example: class
refundable:
description: true - if ticket can be cancelled/refunded
type: boolean
insurance:
description: Insurance data
type: array
items:
type: object
properties:
insurance_company:
type: string
example: insurance_company
insurance_type:
type: string
example: insurance_type
insurance_price:
type: number
example: insurance_price
passengers:
description: Passengers data
type: array
items:
type: object
properties:
full_name:
type: string
example: full_name
first_name:
type: string
example: first_name
last_name:
type: string
example: last_name
dob:
description: ISO 8601 date of birth, e.g. 2018-10-17
type: string
example: '2018-10-17T00:00:00.000Z'
document_type:
type: string
example: document_type
document_id:
type: string
example: document_id
expiration_id_date:
description: ISO 8601 date e.g. 2018-10-17
type: string
format: date
pattern: ^2[0-9]{3}-[0-1][0-9]-[0-3][0-9]$
nationality:
type: string
example: nationality
gender:
description: F - female, M - male, O - other
type: string
enum:
- F
- M
- O
example: F
pnr:
type: string
example: Trip booking number, e.g. TR9088999
description: Trip booking number, e.g. TR9088999
affiliate_name:
description: >-
Name of the affiliate that originated the purchase. If none, leave
blank.
type: string
example: >-
Name of the affiliate that originated the purchase. If none, leave
blank.
HotelReservationDetails:
type: object
properties:
hotel_itinerary:
description: Hotel itinerary data, one per segment
type: array
items:
type: object
properties:
hotel_name:
type: string
example: hotel_name
address:
type: string
example: address
hotel_city:
type: string
example: hotel_city
hotel_country:
type: string
example: hotel_country
start_date:
description: ISO 8601 date e.g. 2018-10-17
type: string
format: date
pattern: ^2[0-9]{3}-[0-1][0-9]-[0-3][0-9]$
end_date:
description: ISO 8601 date e.g. 2018-10-17
type: string
format: date
pattern: ^2[0-9]{3}-[0-1][0-9]-[0-3][0-9]$
number_of_rooms:
type: integer
example: 1
class:
type: string
example: class
insurance:
description: Insurance data
type: array
items:
type: object
properties:
insurance_company:
type: string
example: insurance_company
insurance_type:
type: string
example: insurance_type
insurance_price:
type: number
example: insurance_price
passengers:
description: Passengers data
type: array
items:
type: object
properties:
full_name:
type: string
example: full_name
first_name:
type: string
example: first_name
last_name:
type: string
example: last_name
dob:
description: ISO 8601 date of birth, e.g. 2018-10-17
type: string
example: '2018-10-17T00:00:00.000Z'
document_type:
type: string
example: document_type
document_id:
type: string
example: document_id
expiration_id_dt:
description: ISO 8601 date e.g. 2018-10-17
type: string
format: date
pattern: ^2[0-9]{3}-[0-1][0-9]-[0-3][0-9]$
nationality:
type: string
example: nationality
gender:
description: F - female, M - male, O - other
type: string
enum:
- F
- M
- O
example: M
pnr:
type: string
example: TR9088999
description: Trip booking number, e.g. TR9088999
affiliate_name:
description: >-
Name of the affiliate that originated the purchase. If none, leave
blank.
type: string
example: >-
Name of the affiliate that originated the purchase. If none, leave
blank.
InsuranceDetails:
type: object
properties:
policy_details:
description: Information about insurance
type: object
properties:
insurance_type:
description: Insurance policy type
type: string
example: Insurance policy type
insurance_start_dt:
description: ISO 8601 start date, e.g. 2018-10-17
type: string
example: '2018-10-17T00:00:00.000Z'
insurance_end_dt:
description: ISO 8601 end date, e.g. 2018-10-17
type: string
example: '2018-10-17T00:00:00.000Z'
insured_amount:
description: Amount of insurance policy
type: string
example: '100'
car_details:
description: Required for car insurance
type: object
properties:
manufacturer:
type: string
example: manufacturer
model:
type: string
example: model
year:
type: string
example: year
travel_details:
description: Required for travel insurance
type: object
properties:
departure_country:
type: string
example: departure_country
arrival_country:
type: string
example: arrival_country
refundable:
description: If insurance can be cancelled/refunded - true, otherwise - false
type: boolean
provider_name:
type: string
example: provider_name
client:
type: object
properties:
first_name:
type: string
example: first_name
last_name:
type: string
example: last_name
document_type:
type: string
example: document_type
full_name:
type: string
example: full_name
dob:
description: ISO 8601 date of birth, e.g. 2018-10-17
type: string
example: '2018-10-17T00:00:00.000Z'
document_id:
type: string
example: document_id
expiration_id_dt:
description: ISO 8601 date e.g. 2018-10-17
type: string
format: date
pattern: ^2[0-9]{3}-[0-1][0-9]-[0-3][0-9]$
nationality:
type: string
example: nationality
gender:
description: F - female, M - male, O - other
example: F
payment_history_simple:
type: object
properties:
unique_account_identifier:
type: string
example: unique name / id of the customer
description: Unique name / number to identify the specific customer account
paid_before_flag:
type: boolean
description: Whether the customer has paid before or not
date_of_last_paid_purchase:
description: ISO 8601 date e.g. 2018-10-17
type: string
format: date
pattern: ^2[0-9]{3}-[0-1][0-9]-[0-3][0-9]$
date_of_first_paid_purchase:
description: ISO 8601 date e.g. 2018-10-17
type: string
format: date
pattern: ^2[0-9]{3}-[0-1][0-9]-[0-3][0-9]$
AttachmentPaymentHistoryFull:
type: object
properties:
unique_account_identifier:
type: string
example: unique name / id of the customer
description: Unique name / number to identify the specific customer account
payment_option:
description: One of - card / direct banking / COD (cash) / other
type: string
enum:
- card
- direct banking
- cod
- other
example: card
number_paid_purchases:
type: number
example: 1
total_amount_paid_purchases:
type: number
example: 1
date_of_last_paid_purchase:
description: ISO 8601 date e.g. 2018-10-17
type: string
format: date
pattern: ^2[0-9]{3}-[0-1][0-9]-[0-3][0-9]$
date_of_first_paid_purchase:
description: ISO 8601 date e.g. 2018-10-17
type: string
format: date
pattern: ^2[0-9]{3}-[0-1][0-9]-[0-3][0-9]$
count_paid_purchases_last_month:
type: number
example: 1
amount_paid_purchases_last_month:
type: number
example: 1
max_paid_amount_for_1purchase:
type: number
example: 1
AttachmentPaymentHistorySimple:
type: object
properties:
unique_account_identifier:
type: string
example: unique name / id of the customer
description: Unique name / number to identify the specific customer account
paid_before_flag:
type: boolean
description: Whether the customer has paid before or not
date_of_last_paid_purchase:
description: ISO 8601 date e.g. 2018-10-17
type: string
format: date
pattern: ^2[0-9]{3}-[0-1][0-9]-[0-3][0-9]$
date_of_first_paid_purchase:
description: ISO 8601 date e.g. 2018-10-17
type: string
format: date
pattern: ^2[0-9]{3}-[0-1][0-9]-[0-3][0-9]$
FlightPointsSimple:
type: object
properties:
origin:
description: Origin city and airport
type: object
properties:
air_code:
type: string
example: JFK
description: Origin IATA airport code, for example - JFK
city_code:
type: string
example: NYC
description: Origin city code, for example - NYC
destination:
description: Destination city and airport
type: object
properties:
air_code:
type: string
example: LAX
description: Destination IATA airport code, for example - LAX
city_code:
type: string
example: LAX
description: Destination city code, for example - LAX
Marketplaces:
type: object
description: Sellers' details within marketplaces.
properties:
seller_id:
type: string
example: '57327813'
description: Unique ID of the seller within your marketplace.
seller_name:
type: string
example: Pet Shop
description: Name of the seller within your marketplace.
seller_category:
type: string
example: Electronics
description: Category of the seller within your marketplace.
seller_website:
type: string
example: https://www.petshop.com
description: Website of the seller within your marketplace.
seller_phone:
type: string
example: '500000001'
description: Seller's phone number.
seller_registration_date:
type: string
format: date-time
description: >-
Seller's registration date, in UTC, and displayed in ISO 8601
datetime format.
seller_commercial_registration_number:
type: string
example: '1012345678'
description: Seller's commercial registration number.
EducationDetails:
type: object
description: Education-vertical risk signals for the current session.
properties:
merchant_subtype:
type: string
enum:
- formal_education
- courses_training
example: formal_education
description: Duplicated from onboarding config for self-check.
program:
type: object
description: Details of the education program being paid for.
properties:
payment_tenure_months:
type: integer
example: 6
description: Total payment plan tenure in months.
months_to_completion:
type: integer
example: 9
description: Months remaining until program completion / graduation.
student_history:
type: object
description: Student's payment history with the merchant.
properties:
late_payments_count:
type: integer
example: 2
description: Total count of late payments by the student across history.
avg_overdue_duration_days:
type: number
example: 4.5
description: Average overdue duration in days.
observation_window_months:
type: integer
example: 12
description: >-
Window over which history was calculated, to distinguish a new
student's 0 late payments from a long-history clean student's 0.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >
Bearer authentication header of the form `Bearer `, where
`` is your `secret_key`.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.