Tabby Payment Gateway

The TabbyPaymentGateway component provides seamless integration with Tabby, enabling installment and deferred payment options directly within your checkout experience. Built for compatibility with the Akinon ProjectZero platform, this extension securely manages customer data and transaction flows while maintaining flexibility for localized currency and language support.

With minimal setup, the component generates the necessary context—including order, user, and historical data—to initiate secure transactions via Tabby. The extension also handles hash-based request validation and supports easy deployment through environment-based configuration.

This guide covers installation, configuration, usage, and internal mechanics to help you implement Tabby in your checkout flow with confidence.

Installation Method

You can use the following command to install the extension with the latest plugins:

npx @akinon/projectzero@latest --plugins

Props

Prop	Type	Required	Description
sessionId	string	Yes	The session identifier received from Tabby.
currency	string	Yes	Currency code used in the transaction (e.g., AED, SAR).
locale	string	Yes	Language/locale code used for translations (e.g., en, ar).
extensionUrl	string	Yes	The base URL for the Tabby extension server.
hashKey	string	Yes	Secret hash key used to generate a secure transaction hash.

Environment Variables

Add the following variables to your .env file:

TABBY_EXTENSION_URL=<your_extension_url>
TABBY_HASH_KEY=<your_hash_key>

Usage Example

Create a file in the path:

src/app/[commerce]/[locale]/[currency]/payment-gateway/tabby/page.tsx

import { TabbyPaymentGateway } from '@akinon/pz-tabby-extension';

const TabbyGateway = async ({
  searchParams: { sessionId },
  params: { currency, locale }
}: {
  searchParams: Record<string, string>;
  params: { currency: string; locale: string };
}) => {
  return (
    <TabbyPaymentGateway
      sessionId={sessionId}
      currency={currency}
      locale={locale}
      extensionUrl={process.env.TABBY_EXTENSION_URL}
      hashKey={process.env.TABBY_HASH_KEY}
    />
  );
};

export default TabbyGateway;

Context Object (Auto-generated Internally)

The TabbyPaymentGateway component internally generates a context object using:

- preOrder data from the current checkout session - userProfile and wishlist details - Historical orders and previous purchases

This context includes:

{
  salt: string,
  hash: string,
  shipping_address: {
    city: string,
    address: string,
    zip: string
  },
  order_items: Array<{
    unit_price: number,
    title: string,
    quantity: number,
    category: string
  }>,
  buyer_history: {
    registered_since: string,
    loyalty_level: number,
    wishlist_count: number,
    is_email_verified: boolean,
    is_social_networks_connected: boolean,
    is_phone_number_verified: boolean
  },
  order_history: Array<{
    purchased_at: string,
    amount: number,
    payment_method: string,
    status: string,
    buyer: {
      phone: string,
      email: string,
      name: string
    },
    shipping_address: {
      city: string,
      address: string,
      zip: string
    },
    order_items: object
  }>
}

This object is passed to the FormComponent for completing the payment via Tabby.