--- title: "Retrieve an existing checkout session" method: GET path: "/api/v2/checkout/{id}" tags: ["Checkout"] --- # Retrieve an existing checkout session `GET /api/v2/checkout/{id}` Use this API to retrieve the token (only if tokens used in your integration ) ## Path parameters - `id` string, uuid, required ## Response `200` Success. Checkout session object is returned. - CheckoutSession - `id` string, uuid — Unique identifier for the checkout Session, assigned by Tabby. - `configuration` object — Some details associated with the current session. - `available_products` object, nullable - `installments` object[], nullable - `web_url` string, uri, nullable — UAE: checkout.tabby.ai, KSA: checkout.tabby.sa - `qr_code` string, uri, nullable — UAE: api.tabby.ai, KSA: api.tabby.sa - `products` object — Products and theirs availability - `installments` CheckoutProduct - `type` 'installments', required — Type of product. - `is_available` boolean, required - `rejection_reason` 'order_amount_too_high' | 'order_amount_too_low' | 'not_available' | 'null', nullable — 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. - `token` string, nullable — 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` CheckoutResponsePayment — Payment object associated with the current session. - `id` string, uuid — Unique identifier for the payment (UUID), assigned by Tabby. Save it on your side! - `created_at` string, date-time — Date and time the payment was created, in UTC, and displayed in ISO 8601 datetime format. - `status` 'CREATED' | 'AUTHORIZED' | 'CLOSED' | 'REJECTED' | 'EXPIRED' — 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. - `is_test` boolean — Indicates whether this is a test payment (created using the Test API keys or Production API Keys). - `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. - `currency` 'AED' | 'SAR', required — 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 - `description` string, nullable - `order` OrderResponse, nullable, required - `reference_id` string, nullable, required — Merchant-assigned order number. - `updated_at` string, date-time — Date and time the order was last updated, in UTC, and displayed in ISO 8601 datetime format. - `tax_amount` string — Total tax for the order. - `shipping_amount` string — Total shipping cost for the order. - `discount_amount` string — Total discount for the order. Should be positive or zero. Shows up on Tabby App for the Customer's convenience. - `items` OrderItemResponse[], nullable, required — Array of objects representing the order items in this payment. - `reference_id` string, nullable — Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes. - `title` string, nullable, required — Name of the product. - `description` string, nullable — Description of the product. - `quantity` integer, required — Quantity of the product ordered. - `unit_price` string, required — Price per unit of the product. Should be positive or zero. - `image_url` string, uri, nullable — URL of the item image to show in the order information. - `product_url` string, uri, nullable — URL of the item at your store. - `gender` 'Male' | 'Female' | 'Kids' | 'Other', nullable — Who the goods are designed to. - `category` string, nullable, 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. - `color` string, nullable — white / blue/ green - `product_material` string, nullable — cotton / polyester / synthetic - `size_type` string, nullable — EU / UK - `size` string, nullable — L / XL / 12 - `brand` string, nullable — Mango / Dorothy Perkins / Tommy Hilfiger - `is_refundable` boolean, nullable — Indicates whether a product can be returned - `meta` Meta, nullable — Merchant-defined data about the payment. This field is a key-value map. The example properties provided below. - `customer` string, nullable - `order_id` string, nullable - `attachment` AttachmentV1, nullable — Extra data (booking info, insurance, flight reservations, ...) as serialized JSON - `body` object, required — Should be an object containing any of the keys with corresponded sub objects - `flight_reservation_details` FlightReservationDetails - `pnr` string — Trip booking number, e.g. TR9088999 - `itinerary` object[], required — Itinerary data, one per segment - `departure_city` string - `departure_country` string - `arrival_city` string - `arrival_country` string - `carrier` string - `departure_date` string, date-time — RFC3339 e.g. 2018-10-17T07:26:33Z - `class` string - `refundable` boolean — true - if ticket can be cancelled/refunded - `insurance` object[], required — Insurance data - `insurance_company` string - `insurance_type` string - `insurance_price` number - `passengers` object[], required — Passengers data - `full_name` string - `first_name` string - `last_name` string - `dob` string — ISO 8601 date of birth, e.g. 2018-10-17 - `document_type` string - `document_id` string - `expiration_id_date` string, date — ISO 8601 date e.g. 2018-10-17 - `nationality` string - `gender` 'F' | 'M' | 'O' — F - female, M - male, O - other - `affiliate_name` string — Name of the affiliate that originated the purchase. If none, leave blank. - `hotel_reservation_details` HotelReservationDetails - `pnr` string — Trip booking number, e.g. TR9088999 - `hotel_itinerary` object[], required — Hotel itinerary data, one per segment - `hotel_name` string - `address` string - `hotel_city` string - `hotel_country` string - `start_date` string, date — ISO 8601 date e.g. 2018-10-17 - `end_date` string, date — ISO 8601 date e.g. 2018-10-17 - `number_of_rooms` integer - `class` string - `insurance` object[], required — Insurance data - `insurance_company` string - `insurance_type` string - `insurance_price` number - `passengers` object[], required — Passengers data - `full_name` string - `first_name` string - `last_name` string - `dob` string — ISO 8601 date of birth, e.g. 2018-10-17 - `document_type` string - `document_id` string - `expiration_id_dt` string, date — ISO 8601 date e.g. 2018-10-17 - `nationality` string - `gender` 'F' | 'M' | 'O' — F - female, M - male, O - other - `affiliate_name` string — Name of the affiliate that originated the purchase. If none, leave blank. - `insurance_details` InsuranceDetails - `policy_details` object, required — Information about insurance - `insurance_type` string, required — Insurance policy type - `insurance_start_dt` string, required — ISO 8601 start date, e.g. 2018-10-17 - `insurance_end_dt` string, required — ISO 8601 end date, e.g. 2018-10-17 - `insured_amount` string, required — Amount of insurance policy - `car_details` object — Required for car insurance - … - `travel_details` object — Required for travel insurance - … - `refundable` boolean — If insurance can be cancelled/refunded - true, otherwise - false - `provider_name` string - `client` object, required - `full_name` string - `first_name` string, required - `last_name` string, required - `dob` string — ISO 8601 date of birth, e.g. 2018-10-17 - `document_type` string, required - `document_id` string - `expiration_id_dt` string, date — ISO 8601 date e.g. 2018-10-17 - `nationality` string - `gender` string — F - female, M - male, O - other - `payment_history_simple` object - `unique_account_identifier` string — Unique name / number to identify the specific customer account - `paid_before_flag` boolean — Whether the customer has paid before or not - `date_of_last_paid_purchase` string, date, required — ISO 8601 date e.g. 2018-10-17 - `date_of_first_paid_purchase` string, date, required — ISO 8601 date e.g. 2018-10-17 - `payment_history_full` AttachmentPaymentHistoryFull - `unique_account_identifier` string — Unique name / number to identify the specific customer account - `payment_option` 'card' | 'direct banking' | 'cod' | 'other' — One of - card / direct banking / COD (cash) / other - `number_paid_purchases` number - `total_amount_paid_purchases` number - `date_of_last_paid_purchase` string, date — ISO 8601 date e.g. 2018-10-17 - `date_of_first_paid_purchase` string, date — ISO 8601 date e.g. 2018-10-17 - `count_paid_purchases_last_month` number - `amount_paid_purchases_last_month` number - `max_paid_amount_for_1purchase` number - `payment_history_simple` AttachmentPaymentHistorySimple - `unique_account_identifier` string — Unique name / number to identify the specific customer account - `paid_before_flag` boolean — Whether the customer has paid before or not - `date_of_last_paid_purchase` string, date — ISO 8601 date e.g. 2018-10-17 - `date_of_first_paid_purchase` string, date — ISO 8601 date e.g. 2018-10-17 - `flight_points_simple` FlightPointsSimple - `origin` object, required — Origin city and airport - `air_code` string, required — Origin IATA airport code, for example - JFK - `city_code` string, required — Origin city code, for example - NYC - `destination` object, required — Destination city and airport - `air_code` string, required — Destination IATA airport code, for example - LAX - `city_code` string, required — Destination city code, for example - LAX - `marketplaces` Marketplaces — Sellers' details within marketplaces. - `seller_id` string, required — Unique ID of the seller within your marketplace. - `seller_name` string, required — Name of the seller within your marketplace. - `seller_category` string, required — Category of the seller within your marketplace. - `seller_website` string, required — Website of the seller within your marketplace. - `seller_phone` string, required — Seller's phone number. - `seller_registration_date` string, date-time, required — Seller's registration date, in UTC, and displayed in ISO 8601 datetime format. - `seller_commercial_registration_number` string, required — Seller's commercial registration number. - `education_details` EducationDetails — Education-vertical risk signals for the current session. - `merchant_subtype` 'formal_education' | 'courses_training', required — Duplicated from onboarding config for self-check. - `program` object, required — Details of the education program being paid for. - `payment_tenure_months` integer, required — Total payment plan tenure in months. - `months_to_completion` integer, required — Months remaining until program completion / graduation. - `student_history` object, required — Student's payment history with the merchant. - `late_payments_count` integer, required — Total count of late payments by the student across history. - `avg_overdue_duration_days` number, required — Average overdue duration in days. - `observation_window_months` integer — Window over which history was calculated, to distinguish a new student's 0 late payments from a long-history clean student's 0. - `content_type` string, required — Version of used schema - `status` 'created' | 'rejected' | 'expired' | 'approved' — 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` object - `success` string, uri, nullable — URL where to redirect after payment is Authorized. 'Thank you' page recommended. - `cancel` string, uri, nullable — URL where to proceed after cancel payment status. Checkout page recommended. - `failure` string, uri, nullable — URL where to proceed after failure payment status (Rejected). Checkout page recommended. ## Other responses - `400` — One of the required fields is missing or request is not formatted correctly. - `401` — The request cannot be authorized. - `403` — You tried to perform an action which is forbidden. - `404` — You are using an incorrect ID. - `500` — Something bad happened. We're notified. ## Changes - **2026-08-28** `cff62a2a6ee9` — 1 breaking, 4 info - the response's body type/format changed from `string`/`` to `object`/`` for status `500` - added the optional property `error` to the response with the `500` status - added the optional property `errorType` to the response with the `500` status - added the optional property `status` to the response with the `500` status - …1 more [Change history](https://skmtc.dev/tabby/apis/tabby-api-reference/changes/api/v2/checkout/:id/get.md) --- [API](https://skmtc.dev/tabby/apis/tabby-api-reference.md) · [All operations](https://skmtc.dev/tabby/apis/tabby-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tabby/tabby-api-reference/revisions/cff62a2a6ee9/schema)