Tabby Checkout API

openapi: 3.2.0
info:
  title: Tabby API Reference Checkout API
  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, Kuwait)
- url: https://api.tabby.sa/
  description: Production (KSA)
tags:
- name: Checkout
  description: Checkout is a whole process of customer data collection and payment authorization.
paths:
  /api/v2/checkout:
    post:
      tags:
      - Checkout
      summary: Create a session
      description: Creates a Checkout session. Creates Session and Payment, returns Pre-Scoring result (status), ids of Payment and Session.
      operationId: postCheckoutSession
      security:
      - bearerAuth:
        - secret_key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                payment:
                  $ref: '#/components/schemas/CheckoutCreation'
                lang:
                  $ref: '#/components/schemas/LanguageCode'
                merchant_code:
                  type: string
                  example: code provided to you from Tabby side
                  description: Please contact your integration manager to get the merchant code.
                merchant_urls:
                  $ref: '#/components/schemas/MerchantUrls'
                token:
                  type: string
                  default: null
                  description: 'If you already have `token`, you can pass it there. Authorization header still requires Secret Key.

                    '
              required:
              - payment
              - lang
              - merchant_code
      responses:
        '200':
          $ref: '#/components/responses/CheckoutSession'
        '400':
          $ref: '#/components/responses/BadRequestError_CheckoutPost'
        '401':
          $ref: '#/components/responses/AuthenticationError_CheckoutPost'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /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
      security:
      - bearerAuth:
        - secret_key
      parameters:
      - $ref: '#/components/parameters/sessionIdParam'
      responses:
        '200':
          $ref: '#/components/responses/CheckoutSession'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError_key_doesnt_exist'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
components:
  responses:
    AuthenticationError_key_doesnt_exist:
      description: The request cannot be authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_401_key_doesnt_exist'
    BadRequestError:
      description: One of the required fields is missing or request is not formatted correctly.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_400'
    CheckoutSession:
      description: Success. Checkout session object is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CheckoutSession'
    ForbiddenError:
      description: You tried to perform an action which is forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_403'
    NotFoundError:
      description: You are using an incorrect ID.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_404'
    UnexpectedError:
      description: Something bad happened. We're notified.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_500'
    AuthenticationError_CheckoutPost:
      description: The request cannot be authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_401_merchantNull'
    BadRequestError_CheckoutPost:
      description: One of the required fields is missing or request is not formatted correctly.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_400_CheckoutPost'
  schemas:
    Buyer:
      description: Customer information
      type: object
      properties:
        name:
          type: string
          example: John Doe
          description: Customer’s full name.
        email:
          type: string
          format: email
          description: Customer’s email address.
        phone:
          type: string
          example: '500000001'
          description: 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`.
        dob:
          type: string
          format: date
          example: '2000-01-20'
          description: Customer's date of birth; format is YYYY-MM-DD.
      required:
      - phone
      - email
      - name
    Error_400:
      type: object
      properties:
        status:
          type: string
          example: error
        errorType:
          type: string
          example: bad_data
        error:
          type: string
          example: could not decode request
    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
    CheckoutConfigurationProduct:
      type: array
      nullable: true
      items:
        type: object
        properties:
          web_url:
            type: string
            nullable: true
            format: uri
            example: https://checkout.tabby.ai/
            description: 'UAE/Kuwait: 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/Kuwait: api.tabby.ai, KSA: api.tabby.sa'
            readOnly: true
    HotelReservationDetails:
      type: object
      required:
      - hotel_itinerary
      - insurance
      - passengers
      properties:
        pnr:
          type: string
          example: TR9088999
          description: Trip booking number, e.g. TR9088999
        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-17 00:00:00+00:00
              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
        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.
    Error_500:
      type: string
      example: Internal Server error
    Error_401_merchantNull:
      type: object
      properties:
        status:
          type: string
          example: error
        errorType:
          type: string
          example: not_authorized
        error:
          type: string
          example: merchant is null
    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
    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.
    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]$
    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\nPossible values:\n  * `order_amount_too_high` - 'This purchase is above your current spending limit with Tabby, try a smaller cart or use another payment method.'\n  * `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.'\n  * `not_available` - 'Sorry, Tabby is unable to approve this purchase, please use an alternative payment method for your order.'\n  * `null` - if `is_available` is `true` and customer is able to use it.\n"
    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
      required:
      - body
      - content_type
    InsuranceDetails:
      type: object
      required:
      - policy_details
      - client
      properties:
        policy_details:
          description: Information about insurance
          type: object
          required:
          - insurance_type
          - insurance_start_dt
          - insurance_end_dt
          - insured_amount
          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-17 00:00:00+00:00
            insurance_end_dt:
              description: ISO 8601 end date, e.g. 2018-10-17
              type: string
              example: 2018-10-17 00:00:00+00:00
            insured_amount:
              description: Amount of insurance policy
              type: string
              example: '100'
            car_details:
              description: Required for car insurance
              type: object
              required:
              - manufacturer
              - model
              - year
              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
              required:
              - departure_country
              - arrival_country
              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
          required:
          - first_name
          - last_name
          - document_type
          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-17 00:00:00+00:00
            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
              example: F
        payment_history_simple:
          type: object
          required:
          - date_of_last_paid_purchase
          - date_of_first_paid_purchase
          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]$
    FlightReservationDetails:
      type: object
      required:
      - itinerary
      - insurance
      - passengers
      properties:
        pnr:
          type: string
          example: Trip booking number, e.g. TR9088999
          description: Trip booking number, e.g. TR9088999
        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-17 00:00:00+00:00
              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
        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.
    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.\n  - `created` is returned when the request is approved and the customer is eligible to use Tabby\n  - `rejected` means that there are no available products for a customer\n  - `expired` and `approved` - used for specific type of integration, kindly ignore them if not communicated directly\n"
        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.
    Error_403:
      type: object
      properties:
        status:
          type: string
          example: error
        errorType:
          type: string
          example: no_permission
    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'
    OrderItem:
      type: object
      properties:
        reference_id:
          type: string
          example: SKU123
          description: Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.
        title:
          type: string
          example: Name of the product
          description: Name of the product.
        description:
          type: string
          example: Description of the product
          description: Description of the product.
        quantity:
          type: integer
          default: 1
          minimum: 1
          example: 1
          description: Quantity of the product ordered.
        unit_price:
          type: string
          default: '0.00'
          example: '0.00'
          description: Price per unit of the product. Should be positive or zero.
        discount_amount:
          type: string
          default: '0.00'
          example: '0.00'
          description: Amount of the applied discount if any. Should be positive or zero.
        image_url:
          type: string
          format: uri
          example: https://example.com/
          description: URL of the item image to show in the order information.
        product_url:
          type: string
          format: uri
          example: https://example.com/
          description: URL of the item at your store.
        gender:
          type: string
          enum:
          - Male
          - Female
          - Kids
          - Other
          example: Kids
          description: Who the goods are designed to.
        category:
          type: string
          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
          example: white
          description: white / blue/ green
        product_material:
          type: string
          example: cotton
          description: cotton / polyester / synthetic
        size_type:
          type: string
          example: EU
          description: EU / UK
        size:
          type: string
          example: M
          description: L / XL / 12
        brand:
          type: string
          example: Name of the Brand
          description: Mango / Dorothy Perkins / Tommy Hilfiger
        is_refundable:
          type: boolean
          description: Indicates whether a product can be returned
        barcode:
          type: string
          example: '12345678'
          description: A machine-readable product identifier. Typically used for logistics and scanning.
        ppn:
          type: string
          example: MNXT2ZM/A
          description: Product Part Number assigned by the manufacturer. Used to identify specific components or versions of a product.
        seller:
          type: string
          example: Name of the Seller
          description: The name of the seller offering this item. This field is used to distinguish products from different vendors on a single marketplace.
      required:
      - title
      - quantity
      - unit_price
      - category
    Currency:
      type: string
      enum:
      - AED
      - SAR
      - KWD
      example: AED
      description: "ISO 4217 currency code for the payment amount. Currently there are 3 possible currency options - depending on the country where the store is located:\n  - `AED` - United Arab Emirates Dirham\n  - `SAR` - Saudi Riyal\n  - `KWD` - Kuwaiti Dinar\n"
    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!
    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_purcha

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tabby/refs/heads/main/openapi/tabby-checkout-api-openapi.yml