Sign in

v1

latestOpenAPI 3.1.02026-07-131991131.4 KB
Checkout

Create a session

Creates a Checkout session. Creates Session and Payment, returns Pre-Scoring result (status), ids of Payment and Session.

post/api/v2/checkout

Request body

lang'ar' | 'en' required

Session language, used to launch HPP with desired language.

merchant_codestring required

Please contact your integration manager to get the merchant code.

tokenstring

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

Example request

{
  "payment": {
    "amount": "100",
    "currency": "AED",
    "description": "test payload",
    "buyer": {
      "name": "John Doe",
      "phone": "500000001",
      "dob": "2000-01-20"
    },
    "shipping_address": {
      "city": "Dubai",
      "address": "Dubai",
      "zip": "1111"
    },
    "order": {
      "reference_id": "1001",
      "items": [
        {
          "reference_id": "SKU123",
          "title": "Name of the product",
          "description": "Description of the product",
          "quantity": 1,
          "unit_price": "0.00",
          "discount_amount": "0.00",
          "image_url": "https://example.com/",
          "product_url": "https://example.com/",
          "gender": "Kids",
          "category": "Clothes",
          "color": "white",
          "product_material": "cotton",
          "size_type": "EU",
          "size": "M",
          "brand": "Name of the Brand",
          "barcode": "12345678",
          "ppn": "MNXT2ZM/A",
          "seller": "Name of the Seller"
        }
      ]
    },
    "order_history": [
      {
        "amount": "100",
        "payment_method": "card",
        "buyer": {
          "name": "John Doe",
          "phone": "500000001",
          "dob": "2000-01-20"
        },
        "shipping_address": {
          "city": "Dubai",
          "address": "Dubai",
          "zip": "1111"
        },
        "items": [
          {
            "reference_id": "SKU123",
            "title": "Name of the product",
            "description": "Description of the product",
            "quantity": 1,
            "unit_price": "0.00",
            "discount_amount": "0.00",
            "image_url": "https://example.com/",
            "product_url": "https://example.com/",
            "gender": "Kids",
            "category": "Clothes",
            "color": "white",
            "product_material": "cotton",
            "size_type": "EU",
            "size": "M",
            "brand": "Name of the Brand",
            "barcode": "12345678",
            "ppn": "MNXT2ZM/A",
            "seller": "Name of the Seller"
          }
        ]
      }
    ],
    "meta": {
      "customer": "#customer-id",
      "order_id": "#1234"
    },
    "attachment": {
      "body": {
        "flight_reservation_details": {
          "pnr": "Trip booking number, e.g. TR9088999",
          "itinerary": [
            {
              "departure_city": "departure_city",
              "departure_country": "departure_country",
              "arrival_city": "arrival_city",
              "arrival_country": "arrival_country",
              "carrier": "carrier",
              "class": "class"
            }
          ],
          "insurance": [
            {
              "insurance_company": "insurance_company",
              "insurance_type": "insurance_type"
            }
          ],
          "passengers": [
            {
              "full_name": "full_name",
              "first_name": "first_name",
              "last_name": "last_name",
              "dob": "2018-10-17T00:00:00.000Z",
              "document_type": "document_type",
              "document_id": "document_id",
              "nationality": "nationality",
              "gender": "F"
            }
          ],
          "affiliate_name": "Name of the affiliate that originated the purchase. If none, leave blank."
        },
        "hotel_reservation_details": {
          "pnr": "TR9088999",
          "hotel_itinerary": [
            {
              "hotel_name": "hotel_name",
              "address": "address",
              "hotel_city": "hotel_city",
              "hotel_country": "hotel_country",
              "number_of_rooms": 1,
              "class": "class"
            }
          ],
          "insurance": [
            {
              "insurance_company": "insurance_company",
              "insurance_type": "insurance_type"
            }
          ],
          "passengers": [
            {
              "full_name": "full_name",
              "first_name": "first_name",
              "last_name": "last_name",
              "dob": "2018-10-17T00:00:00.000Z",
              "document_type": "document_type",
              "document_id": "document_id",
              "nationality": "nationality",
              "gender": "M"
            }
          ],
          "affiliate_name": "Name of the affiliate that originated the purchase. If none, leave blank."
        },
        "insurance_details": {
          "policy_details": {
            "insurance_type": "Insurance policy type",
            "insurance_start_dt": "2018-10-17T00:00:00.000Z",
            "insurance_end_dt": "2018-10-17T00:00:00.000Z",
            "insured_amount": "100",
            "car_details": {
              "manufacturer": "manufacturer",
              "model": "model",
              "year": "year"
            },
            "travel_details": {
              "departure_country": "departure_country",
              "arrival_country": "arrival_country"
            },
            "provider_name": "provider_name"
          },
          "client": {
            "full_name": "full_name",
            "first_name": "first_name",
            "last_name": "last_name",
            "dob": "2018-10-17T00:00:00.000Z",
            "document_type": "document_type",
            "document_id": "document_id",
            "nationality": "nationality",
            "gender": "F"
          },
          "payment_history_simple": {
            "unique_account_identifier": "unique name / id of the customer"
          }
        },
        "payment_history_full": {
          "unique_account_identifier": "unique name / id of the customer",
          "payment_option": "card",
          "number_paid_purchases": 1,
          "total_amount_paid_purchases": 1,
          "count_paid_purchases_last_month": 1,
          "amount_paid_purchases_last_month": 1,
          "max_paid_amount_for_1purchase": 1
        },
        "payment_history_simple": {
          "unique_account_identifier": "unique name / id of the customer"
        },
        "flight_points_simple": {
          "origin": {
            "air_code": "JFK",
            "city_code": "NYC"
          },
          "destination": {
            "air_code": "LAX",
            "city_code": "LAX"
          }
        },
        "marketplaces": {
          "seller_id": "57327813",
          "seller_name": "Pet Shop",
          "seller_category": "Electronics",
          "seller_website": "https://www.petshop.com",
          "seller_phone": "500000001",
          "seller_commercial_registration_number": "1012345678"
        },
        "education_details": {
          "merchant_subtype": "formal_education",
          "program": {
            "payment_tenure_months": 6,
            "months_to_completion": 9
          },
          "student_history": {
            "late_payments_count": 2,
            "avg_overdue_duration_days": 4.5,
            "observation_window_months": 12
          }
        }
      }
    }
  },
  "lang": "en",
  "merchant_code": "code provided to you from Tabby side",
  "merchant_urls": {
    "success": "https://your-store/success",
    "cancel": "https://your-store/cancel",
    "failure": "https://your-store/failure"
  }
}

Response

Success. Checkout session object is returned.

idstring uuid

Unique identifier for the checkout Session, assigned by Tabby.

tokenstring 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.

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

Example response

{
  "id": "session id, uuid format",
  "configuration": {
    "available_products": {
      "installments": [
        {
          "web_url": "https://checkout.tabby.ai/",
          "qr_code": "https://api.tabby.ai/api/v2/checkout/{id}/hpp_link_qr"
        }
      ]
    },
    "products": {
      "installments": {
        "type": "installments",
        "is_available": true
      }
    }
  },
  "payment": {
    "id": "payment id, uuid format",
    "status": "CLOSED",
    "amount": "100",
    "currency": "AED",
    "description": "test payload",
    "order": {
      "reference_id": "1001",
      "tax_amount": "0.00",
      "shipping_amount": "0.00",
      "discount_amount": "0.00",
      "items": [
        {
          "reference_id": "SKU123",
          "title": "Name of the product",
          "description": "Description of the product",
          "quantity": 1,
          "unit_price": "0.00",
          "image_url": "https://example.com/",
          "product_url": "https://example.com/",
          "gender": "Kids",
          "category": "Clothes",
          "color": "white",
          "product_material": "cotton",
          "size_type": "EU",
          "size": "M",
          "brand": "Name of the Brand"
        }
      ]
    },
    "meta": {
      "customer": "#customer-id",
      "order_id": "#1234"
    },
    "attachment": {
      "body": {
        "flight_reservation_details": {
          "pnr": "Trip booking number, e.g. TR9088999",
          "itinerary": [
            {
              "departure_city": "departure_city",
              "departure_country": "departure_country",
              "arrival_city": "arrival_city",
              "arrival_country": "arrival_country",
              "carrier": "carrier",
              "class": "class"
            }
          ],
          "insurance": [
            {
              "insurance_company": "insurance_company",
              "insurance_type": "insurance_type"
            }
          ],
          "passengers": [
            {
              "full_name": "full_name",
              "first_name": "first_name",
              "last_name": "last_name",
              "dob": "2018-10-17T00:00:00.000Z",
              "document_type": "document_type",
              "document_id": "document_id",
              "nationality": "nationality",
              "gender": "F"
            }
          ],
          "affiliate_name": "Name of the affiliate that originated the purchase. If none, leave blank."
        },
        "hotel_reservation_details": {
          "pnr": "TR9088999",
          "hotel_itinerary": [
            {
              "hotel_name": "hotel_name",
              "address": "address",
              "hotel_city": "hotel_city",
              "hotel_country": "hotel_country",
              "number_of_rooms": 1,
              "class": "class"
            }
          ],
          "insurance": [
            {
              "insurance_company": "insurance_company",
              "insurance_type": "insurance_type"
            }
          ],
          "passengers": [
            {
              "full_name": "full_name",
              "first_name": "first_name",
              "last_name": "last_name",
              "dob": "2018-10-17T00:00:00.000Z",
              "document_type": "document_type",
              "document_id": "document_id",
              "nationality": "nationality",
              "gender": "M"
            }
          ],
          "affiliate_name": "Name of the affiliate that originated the purchase. If none, leave blank."
        },
        "insurance_details": {
          "policy_details": {
            "insurance_type": "Insurance policy type",
            "insurance_start_dt": "2018-10-17T00:00:00.000Z",
            "insurance_end_dt": "2018-10-17T00:00:00.000Z",
            "insured_amount": "100",
            "car_details": {
              "manufacturer": "manufacturer",
              "model": "model",
              "year": "year"
            },
            "travel_details": {
              "departure_country": "departure_country",
              "arrival_country": "arrival_country"
            },
            "provider_name": "provider_name"
          },
          "client": {
            "full_name": "full_name",
            "first_name": "first_name",
            "last_name": "last_name",
            "dob": "2018-10-17T00:00:00.000Z",
            "document_type": "document_type",
            "document_id": "document_id",
            "nationality": "nationality",
            "gender": "F"
          },
          "payment_history_simple": {
            "unique_account_identifier": "unique name / id of the customer"
          }
        },
        "payment_history_full": {
          "unique_account_identifier": "unique name / id of the customer",
          "payment_option": "card",
          "number_paid_purchases": 1,
          "total_amount_paid_purchases": 1,
          "count_paid_purchases_last_month": 1,
          "amount_paid_purchases_last_month": 1,
          "max_paid_amount_for_1purchase": 1
        },
        "payment_history_simple": {
          "unique_account_identifier": "unique name / id of the customer"
        },
        "flight_points_simple": {
          "origin": {
            "air_code": "JFK",
            "city_code": "NYC"
          },
          "destination": {
            "air_code": "LAX",
            "city_code": "LAX"
          }
        },
        "marketplaces": {
          "seller_id": "57327813",
          "seller_name": "Pet Shop",
          "seller_category": "Electronics",
          "seller_website": "https://www.petshop.com",
          "seller_phone": "500000001",
          "seller_commercial_registration_number": "1012345678"
        },
        "education_details": {
          "merchant_subtype": "formal_education",
          "program": {
            "payment_tenure_months": 6,
            "months_to_completion": 9
          },
          "student_history": {
            "late_payments_count": 2,
            "avg_overdue_duration_days": 4.5,
            "observation_window_months": 12
          }
        }
      }
    }
  },
  "status": "created",
  "merchant_urls": {
    "success": "https://your-store/success",
    "cancel": "https://your-store/cancel",
    "failure": "https://your-store/failure"
  }
}