@kuwaitdev/myfatoorah-devkit

Unofficial MyFatoorah checkout examples and developer utilities for Kuwait ecommerce, mobile app, and Node.js payment gateway integrations.

Built by KuwaitDev, a Kuwait web and mobile app development team. If you are planning a Kuwait website, ecommerce store, or app, you can also use the Kuwait app and website cost calculator.

This package is not affiliated with, endorsed by, or maintained by MyFatoorah. Use the official MyFatoorah documentation and dashboard for production credentials, payment method IDs, and compliance requirements.

Why this package exists

MyFatoorah integrations usually need the same development pieces:

• A server-side checkout endpoint
• A callback page for the customer experience
• A webhook endpoint for payment updates
• Server-side status verification before fulfillment
• Clear separation between mock, sandbox, and production modes

This repo gives developers a safe starting point without placing live payment credentials in frontend or mobile code.

Install

npm install @kuwaitdev/myfatoorah-devkit

Examples

| Example | Path | Use case | | --- | --- | --- | | Express | examples/express | Server checkout, callback, webhook, and order status endpoints | | Next.js | examples/next | App Router checkout with route handlers | | React Native Expo | examples/react-native-expo | Mobile app checkout UI with backend-token warning |

Run the root build first so local file:../.. example dependencies can import the package:

npm install
npm run build

Then run an example:

cd examples/express
npm install
cp .env.example .env
npm run dev

Basic mock checkout

import {
  calculateCheckoutTotal,
  createMockPaymentSession,
  createMockWebhookEvent
} from "@kuwaitdev/myfatoorah-devkit";

const items = [
  { id: "storefront", name: "Kuwait ecommerce storefront", quantity: 1, unitPriceKwd: 250 },
  { id: "payment", name: "MyFatoorah setup", quantity: 1, unitPriceKwd: 75 }
];

const session = createMockPaymentSession({
  orderId: "order_1001",
  items,
  customer: {
    name: "Kuwait Demo Customer",
    email: "[email protected]"
  },
  callbackUrl: "https://example.com/payment/success",
  errorUrl: "https://example.com/payment/failure",
  webhookUrl: "https://example.com/api/webhook",
  currencyIso: "KWD"
});

console.log(calculateCheckoutTotal(items));
console.log(session.paymentUrl);
console.log(createMockWebhookEvent(session, "paid"));

Sandbox template

Server-side only:

import {
  MyFatoorahSandboxClient,
  assertSandboxReady,
  readMyFatoorahEnv
} from "@kuwaitdev/myfatoorah-devkit";

const config = readMyFatoorahEnv();
assertSandboxReady(config);

const client = new MyFatoorahSandboxClient({
  apiToken: config.apiToken,
  mode: config.mode,
  apiBaseUrl: config.apiBaseUrl
});

const session = await client.executePayment(checkoutRequest, {
  paymentMethodId: config.paymentMethodId
});

Required environment variables:

MYFATOORAH_MODE=sandbox
MYFATOORAH_API_TOKEN=your_sandbox_token
MYFATOORAH_PAYMENT_METHOD_ID=your_payment_method_id

Webhook handling

import {
  WebhookDeduper,
  createWebhookIdempotencyKey,
  parseMyFatoorahWebhookEvent
} from "@kuwaitdev/myfatoorah-devkit";

const deduper = new WebhookDeduper();
const event = parseMyFatoorahWebhookEvent(requestBody);
const key = createWebhookIdempotencyKey(event);

if (!deduper.hasProcessed(key)) {
  deduper.markProcessed(key);
  // Update the order status in your database.
}

Production note: use your real database for idempotency and order state. The in-memory helpers are for demos and tests only.

Security notes

• Never expose MYFATOORAH_API_TOKEN in React Native, browser JavaScript, or public build output.
• Treat customer callbacks as UX hints, not final proof of payment.
• Confirm final status server-side with MyFatoorah status APIs or trusted webhook processing.
• Store order ID, invoice ID, payment ID, amount, currency, status, and timestamps in a database.
• Make webhook handling idempotent because providers can retry events.
• Validate all amounts on the server instead of trusting client-submitted totals.

More details are in docs/security.md.

npm metadata

The package includes npm fields for homepage, repository, bugs, and relevant Kuwait/MyFatoorah payment keywords. The homepage points to KuwaitDev because this is a KuwaitDev developer resource.

Useful links

• KuwaitDev
• Kuwait app and website cost calculator
• MyFatoorah documentation
• Official MyFatoorah React Native npm package

License

MIT