SADAD Payment Gateway Components for React Applications

Louis Innovations has released an open source React component library for SADAD Payment Gateway, providing drop-in UI components for checkout, payment status, and refund workflows. The library is published on npm and supports TypeScript, making it straightforward for Qatar-based development teams to integrate the national payment gateway into React applications without building payment UI from scratch.

Installation and Setup

The package is available on npm under the @louisinnovations/sadad-react namespace. Install it in your React project using npm or yarn:

npm install @louisinnovations/sadad-react
# or
yarn add @louisinnovations/sadad-react

The library requires React 18 or later and has a peer dependency on axios for HTTP communication. After installation, wrap your application with the SadadProvider component to configure the SADAD API credentials and environment:

import { SadadProvider } from '@louisinnovations/sadad-react';

function App() {
  return (
    <SadadProvider
      merchantId={process.env.NEXT_PUBLIC_SADAD_MERCHANT_ID}
      apiKey={process.env.NEXT_PUBLIC_SADAD_API_KEY}
      environment="sandbox" // or "production"
    >
      <YourApp />
    </SadadProvider>
  );
}

CheckoutForm Component

The CheckoutForm component renders a complete payment form with card input fields, amount display, and a submit button. It handles form validation, loading states, and error display automatically:

import { CheckoutForm } from '@louisinnovations/sadad-react';

function PaymentPage() {
  const handleSuccess = (transactionId: string) => {
    console.log('Payment successful:', transactionId);
  };

  const handleError = (error: SadadError) => {
    console.error('Payment failed:', error.message);
  };

  return (
    <CheckoutForm
      amount={150.00}
      currency="QAR"
      description="Premium Plan - Monthly"
      onSuccess={handleSuccess}
      onError={handleError}
    />
  );
}

The component accepts an options prop to customize the form appearance, including submit button text, theme colors, and supported card types. All card data is tokenized client-side before submission to the SADAD gateway, ensuring PCI DSS compliance without requiring SAQ D certification on your end.

PaymentStatus Component

Display real-time payment status updates using the PaymentStatus component. It polls the SADAD API at configurable intervals and renders status badges for pending, successful, failed, and refunded transactions:

import { PaymentStatus } from '@louisinnovations/sadad-react';

function OrderConfirmation({ transactionId }) {
  return (
    <div>
      <h2>Order #12345</h2>
      <PaymentStatus
        transactionId={transactionId}
        pollInterval={3000}
        showDetails={true}
        onStatusChange={(status) => {
          if (status === 'SUCCESS') triggerFulfillment();
        }}
      />
    </div>
  );
}

The component supports both automatic polling and manual refresh via a ref handle, giving developers fine-grained control over the UI experience.

RefundButton Component

Process refunds directly from your admin dashboard with the RefundButton component. It includes a confirmation dialog, amount input for partial refunds, and progress indicators:

import { RefundButton } from '@louisinnovations/sadad-react';

function OrderActions({ transactionId, remainingAmount }) {
  return (
    <RefundButton
      transactionId={transactionId}
      maxAmount={remainingAmount}
      onRefundComplete={(refundId) => {
        console.log('Refund processed:', refundId);
      }}
    />
  );
}

TypeScript Support

The library ships with complete TypeScript definitions. Key types exported include SadadConfig, TransactionResponse, RefundResponse, CheckoutFormProps, and SadadError. This enables full IDE autocompletion and compile-time type checking for all component props and API responses.

For custom implementations beyond the provided components, the library also exports raw API hooks: useCreateTransaction, useTransactionStatus, and useProcessRefund. These hooks give you the flexibility to build bespoke UI while retaining the SDKs connection management and error handling logic.

Frequently Asked Questions

Q: Does the library support server-side rendering with Next.js?

Yes. All components are compatible with Next.js 13 and later. Import components with dynamic imports and disable SSR for payment form components that rely on browser APIs.

Q: Is the component library PCI DSS compliant?

The library handles tokenization client-side, meaning raw card data never reaches your server. This reduces your PCI DSS compliance scope to SAQ A, the lowest tier. The SADAD gateway handles all sensitive data processing.

Q: Does the library support Arabic language and RTL layouts?

Yes. All components respect the dir attribute on the HTML element and automatically switch to Arabic labels and RTL layout when the document direction is set to rtl. Translation keys are also available for customization.

Q: How do I test payments in sandbox mode?

Set the environment prop on SadadProvider to "sandbox". Use the test card numbers provided by QNB (the SADAD acquiring bank) to simulate successful and failed transactions without moving real funds. Check our contact page for test credential requests.