How to integrate MyFatoorah: a Kuwait guide for Next.js and React Native

MyFatoorah covers two ways Kuwaiti businesses collect money online: a checkout inside a website or app, and payment links sent by email, SMS or WhatsApp. This guide covers licence status, account setup, integration types, the v3 API, testing, Next.js and React Native (Expo) outlines, and webhooks.

This is a technical guide based on MyFatoorah's public documentation, checked on 27 September 2026. It is not legal or financial advice. Confirm fees, contract terms and enabled payment methods with MyFatoorah before launch.

Is MyFatoorah licensed by the Central Bank of Kuwait?

As of 27 September 2026, yes. The Central Bank of Kuwait (CBK) publishes a register of e-money service providers. It lists MyFatoorah for Electronic Payment Services K.S.C.C. as a Large e-Money Service Provider, based in Sharq, phone 1888805, support email supportkwt@myfatoorah.com.

Two practical checks before you sign:

• Other Kuwaiti gateways may hold a different CBK licence category. Look each provider up by name on the CBK site rather than assuming. Our guide to payment gateways in Kuwait covers the wider market.
• At the time of checking (27 September 2026), the footer of MyFatoorah's English website names Fatoorah for electronic marketing, licensed by the Saudi Central Bank (SAMA) under licence No. 21/LLC/1444. If you trade in Kuwait, confirm your merchant agreement is with the Kuwaiti entity on the CBK register.

What MyFatoorah offers

MyFatoorah says it accepts payments in eight countries: Kuwait, Saudi Arabia, the UAE, Qatar, Bahrain, Oman, Egypt and Jordan. Its main products:

The payment methods list in the docs includes KNET, Visa and Mastercard, AMEX, Apple Pay, Google Pay, Samsung Pay and STC Pay, plus methods for other markets such as Benefit, mada and Meeza. The same page says that, based on your account and agreement, not all methods will be available to you. Ask for your enabled methods in writing. For KNET specifically, see our KNET integration guide.

Opening and activating a MyFatoorah account

1. Register at register.myfatoorah.com and choose your country.
2. Call a MyFatoorah account manager or sales representative to activate the account and the API role your integration uses.
3. Ask at the same time for any extra features you need, such as tokenization, shipping or multiple suppliers, and get your enabled payment methods and rate card in writing.
4. Until activation, build against the sandbox with the public test token.

One account can serve several of MyFatoorah's countries: you ask your account manager to add a country rather than opening a new account.

Which integration type to choose

MyFatoorah documents three options for most merchants and a fourth for merchants with their own PCI certification.

According to the docs, embedded payment processes cards, Apple Pay, Google Pay and STC Pay on your page. Other enabled methods, KNET included, redirect to the hosted page. So a typical Kuwaiti checkout is a mix: embedded cards and wallets, plus a KNET redirect.

Apple Pay on the embedded form needs your domain verified first. See our Apple Pay integration guide for the wider setup in Kuwait.

Sandbox, API keys and base URLs

Every request carries the header Authorization: Bearer <your key>. These are the base URLs from the API key page:

MyFatoorah publishes a public test token on the API key page. You can also register a demo account at registertest.myfatoorah.com, choose Kuwait, skip the bank details step, and email tech@myfatoorah.com to activate it.

Live keys are created in the portal under Integration Settings, then API Key, by the Super Master Account. Each key has a name, an expiry date, an active flag and a list of endpoint permissions. Four details catch teams out:

• You can create up to 5 API keys, so plan rotation rather than creating a key per developer.
• Each enabled country has its own key. Use each country's key so customers there pay in their local currency.
• Disabling the portal user who created a key disables the key. Create keys from a dedicated Super Master user that will not be disabled when a staff member leaves.
• A key without the right permission returns a 401 error, so give each key only the permissions its job needs.

MyFatoorah test cards

MyFatoorah's test cards page lists test cards per method. As checked on 27 September 2026, it includes a KNET card whose expiry date decides whether the result is Captured or Not Captured, so you can test both paths, and several Visa and Mastercard cards used with any two-part cardholder name. There is no MyFatoorah card for Apple Pay; use Apple's own sandbox test cards. Copy the values from the page on the day you test, because they can change.

The page also warns that not every country supports the KNET test gateway, so run KNET tests on a demo account set to Kuwait.

The v3 payment flow

The docs say to use the /v3 endpoints and that /v2 should not be used for new integrations. Older tutorials still show v2 names such as SendPayment. The v3 flow has four moving parts:

1. POST /v3/sessions creates an embedded payment session. You need one session per payment, and the response includes a SessionId and an EncryptionKey.
2. POST /v3/payments creates a payment or an invoice and returns an InvoiceId and a PaymentURL.
3. After payment, MyFatoorah redirects the customer to your Redirection URL with a paymentId query parameter.
4. GET /v3/payments/{paymentId} returns the invoice, transaction, customer and amount details. An invoice is PAID when at least one of its transactions has SUCCESS status.

The fields you will set most often on POST /v3/payments:

Next.js integration outline

This is the structure we use for a Next.js App Router project. It keeps the key on the server and treats the browser as untrusted.

1. Store the key server-side. Put it in environment variables such as MYFATOORAH_API_KEY and MYFATOORAH_BASE_URL. Never give them the NEXT_PUBLIC_ prefix, which would ship them to the browser.
2. Create your order first. Save it with your own order ID and a "pending payment" status before calling MyFatoorah.
3. Call MyFatoorah from a Route Handler. For example app/api/checkout/route.ts calls POST /v3/sessions for embedded checkout, or POST /v3/payments for a hosted page or invoice link, and returns only the SessionId or PaymentURL to the client.
4. Load the embedded form on the checkout page only. The docs load session.js from demo.myfatoorah.com in test and portal.myfatoorah.com for live Kuwait, then call myfatoorah.init with the sessionId, a container ID and a callback.
5. Do not treat the callback as proof of payment. The docs state that paymentCompleted: true only means the flow finished. Decrypt the callback data with the session's EncryptionKey as documented, or wait for the webhook.
6. Verify on the result page. A server component reads paymentId from the URL, calls GET /v3/payments/{paymentId}, and checks that the invoice status is PAID and the amount matches your order.
7. Add a webhook route. app/api/webhooks/myfatoorah/route.ts checks the signature, updates the order only if it is not already paid, and returns HTTP 200.

React Native (Expo) integration outline

MyFatoorah's SDK overview lists SDKs for iOS, Android, Flutter, React Native and Cordova. For an Expo (React Native) app, this is the structure we use:

1. Keep payment creation on your backend. The app calls your own API, which calls POST /v3/payments with the server-side key and returns only the PaymentURL. No live MyFatoorah key ships inside the app.
2. Open the payment page in an in-app browser. Use expo-web-browser with the PaymentURL. This also covers KNET, which redirects to the hosted page in every integration type.
3. Return through a deep link. Point IntegrationUrls.Redirection at a page on your domain that hands the paymentId back to the app through a universal link or your app scheme.
4. Confirm on the server. When the app returns to the foreground, it asks your backend for the order status. The backend relies on the webhook and GET /v3/payments/{paymentId}, never on the redirect alone.
5. In-app card fields are optional. For MyFatoorah's native card view or embedded Apple Pay, use its React Native SDK. Native SDKs run in an Expo development build, not in Expo Go. If the SDK needs an API key in the app, treat that key as exposed: give it a dedicated key with minimal permissions and an expiry date.

Flutter alternative. If your app is built in Flutter, MyFatoorah maintains the myfatoorah_flutter plugin. According to its guide, you initialise it with MFSDK.init(apiKey, MFCountry.KUWAIT, MFEnvironment.TEST), use initiateSession() and MFPaymentCardView for in-app card fields, and initiatePayment then executePayment for redirect methods such as KNET. The guide's sample hard-codes the KNET method ID; read the IDs from the response instead. The same server-confirmation rule applies. If you are still choosing a framework, see Flutter vs React Native.

Sending invoices and payment links on WhatsApp

MyFatoorah's website markets invoice delivery by WhatsApp, email and SMS. In the v3 API, an invoice is POST /v3/payments without a PaymentMethod, plus a NotificationOption:

To send the link from your own WhatsApp Business number, request LINK and post the PaymentURL yourself:

1. The customer confirms the order in the chat.
2. Your system creates the invoice with NotificationOption LINK and stores the InvoiceId against the order.
3. The agent or bot sends the PaymentURL in the same chat.
4. The webhook marks the order paid, and your system posts the confirmation in the chat.

For example, a clinic that takes a deposit before each booking could send the link the moment a slot is agreed, and see the booking confirmed without anyone checking the portal. Set PaymentExpiry so an unpaid link does not stay open forever. WhatsApp's own rules on business-initiated messages still apply; see our WhatsApp Business API guide.

Waslo, Rukn's messaging platform, handles this kind of chat sale: an AI agent answers from the business's own knowledge base in Arabic and English, takes the order, and sends a payment link from the business's own licensed gateway account in the chat, with funds settling directly to the business, never through Rukn. It hands off to a human when it should.

Webhooks and payment status

From MyFatoorah's payment status guidelines:

• The redirect is not reliable. It fails if the customer closes the page or the network is slow. Use it for the customer's screen, not for your records.
• The webhook usually arrives first, because it is server to server. Turn on the secure key on the portal's webhook page so each event carries a MyFatoorah-Signature header. Rebuild the signature (HMAC SHA-256 over the documented fields as ordered key=value pairs, with nulls as empty strings, Base64-encoded) and compare it before you update the order and return HTTP 200.
• Duplicates happen. In rare cases some methods, KNET among them, send more than one webhook for the same payment. A SUCCESS status overrides any other status, even one received first, and success is final. Make your handler idempotent.
• Retries. With Webhook V2 you set the retry count and interval in the dashboard.
• Resilience. If the status call fails, the docs suggest retrying 3 times, 5 seconds apart, with a timeout of at least 30 seconds, then parking the order in a pending state for a scheduled retry or manual review.
• Rate limits. The status endpoint is rate limited. If you expect heavy traffic, ask your account manager for a higher limit.

Fees and reconciliation

As of 27 September 2026, we did not find a Kuwait per-transaction price list on MyFatoorah's website; its FAQ says fees depend on business type, transaction volume and other factors. Ask for a written rate card for each payment method before launch.

Whatever you agree, the payment details response includes ServiceCharge, ServiceChargeVAT and ReceivableAmount alongside the paid amount and currencies. Store them per transaction, and reconciliation against settlements becomes a query.

Switching gateways later

Keep your own order ID as the primary key, store MyFatoorah's InvoiceId and PaymentId next to it, and put the gateway behind an adapter so only one module knows MyFatoorah's endpoints. Refunds for past payments still go through the provider that took them. For other CBK-licensed providers, see our guide to payment gateways in Kuwait and our Tap Payments integration guide.

How Rukn builds MyFatoorah integrations

For a custom storefront or app, Rukn builds the integration end to end: a server-side checkout, signed webhooks, bilingual result pages and reconciliation fields, on the web and in React Native (Expo) apps, as part of our website development service. Websites start from KD 799 and mobile apps from KD 1,999; the final quote depends on scope.