KNET vs MyFatoorah: Payment Gateway Integration, Technical Differences, and Real-World Challenges

For businesses operating an e-commerce website in Kuwait, choosing the right payment solution is an important part of building a reliable checkout experience. KNET is a widely used local electronic payment network, while MyFatoorah provides a broader payment gateway platform that can support KNET alongside other payment methods, depending on merchant eligibility and activation.

Although both can be used to accept KNET payments, they differ in their integration architecture, payment methods, onboarding requirements, development effort, and operational flexibility.

Having worked with payment integration in a Medusa v2 and Next.js e-commerce environment, I found that the real challenge goes beyond connecting an API. Authentication, currency conversion, payment-session management, callback handling, and server-side payment verification are all essential to building a reliable checkout flow.

In this article, we compare direct KNET integration with MyFatoorah and explore the practical technical challenges developers should understand before choosing or implementing either solution.

1. What Is KNET?#

KNET is Kuwait's electronic payment network, widely used for debit-card transactions through participating Kuwaiti banks.

For a Kuwait-focused e-commerce business, supporting KNET can be important because customers are familiar with the payment method and may expect it at checkout.

A direct KNET integration generally requires the merchant to coordinate with the relevant acquiring bank or payment service provider. The exact process depends on the merchant agreement, terminal configuration, technical documentation, and testing requirements.

How direct KNET integration works#

A typical payment flow looks like this:

1. The customer proceeds to checkout and selects KNET.
2. The e-commerce backend creates a payment request using the configured merchant credentials.
3. The customer is redirected to the KNET payment page.
4. The customer completes the required payment steps.
5. The gateway returns a transaction result to the merchant's system.
6. The backend validates the transaction and updates the payment status.
7. The order is completed only after the payment has been verified successfully.

The backend must not treat a successful browser redirect as sufficient proof of payment. It should validate the transaction using the supported verification mechanism and reconcile the result with the expected amount, currency, and payment session.

Advantages of direct KNET integration#

• Focused integration for businesses primarily serving Kuwait.
• A payment flow tailored to KNET requirements.
• Direct coordination with the relevant acquiring setup.
• Greater control over the custom integration and transaction lifecycle.

Potential challenges#

• Merchant onboarding and terminal configuration.
• Provider-specific request, response, and security requirements.
• Payment-status verification and callback handling.
• Testing, certification, and production activation.
• Ongoing maintenance of the custom integration.

The actual cost, transaction fees, settlement arrangements, and development effort depend on the merchant's agreement and implementation requirements.

2. What Is MyFatoorah?#

MyFatoorah is a payment gateway platform that provides APIs and integration options for businesses that want to accept payments through a unified system.

Depending on the merchant's country, account configuration, and activated payment methods, the platform may support options such as:

• KNET
• Visa and Mastercard
• Apple Pay and Google Pay
• Other regional payment methods and services

Availability should always be confirmed for the specific merchant account. A payment method appearing in a sandbox response does not guarantee that it is enabled for live transactions.

MyFatoorah offers different integration approaches, including hosted payment pages, embedded payment experiences, APIs, SDKs, and supported plugins.

For developers, this can reduce the need to implement a separate gateway integration for every supported payment method.

3. KNET vs MyFatoorah: Main Differences#

FeatureDirect KNET integrationMyFatoorah integrationPrimary purposeAccept KNET paymentsAccess supported payment methods through a gatewayPayment methodsKNET-focusedMultiple methods, depending on merchant activationMerchant onboardingAcquiring-bank or provider setupMyFatoorah merchant account and configurationAPI integrationKNET-specific implementationUnified gateway APICheckout flowConfigured KNET payment flowHosted or other supported checkout approachesPayment verificationKNET/acquirer-specific verificationMyFatoorah status APIs and supported notificationsRefundsDepends on enabled terminal services and APIsSupported refund APIs, subject to account and transaction rulesMulti-market requirementsPrimarily focused on KNETPotentially suitable for multiple supported marketsMaintenanceCustom KNET integrationCustom gateway integration or supported integration tools

Neither option is automatically better for every business. The right choice depends on the target market, available payment methods, merchant agreements, integration requirements, and operational needs.

4. Understanding the Integration Architecture#

A payment integration is not simply an API request followed by a redirect. It is a sequence of operations connecting the storefront, commerce backend, payment provider, and gateway.

In my implementation work, the architecture involved a Next.js storefront, Medusa v2 as the commerce backend, and a custom payment provider for the gateway integration.

The general architecture is:

Next.js storefront → Medusa payment module → Custom payment provider → Payment gateway → Server-side verification → Order completion

What each component does#

Next.js storefront

• Displays the available payment methods.
• Initiates the checkout payment process.
• Requests payment-session initialization.
• Redirects the customer to the gateway when required.
• Displays the appropriate payment result.

Medusa v2 backend

• Manages carts, payment collections, and payment sessions.
• Connects the checkout flow to the configured payment provider.
• Stores payment-session data.
• Coordinates authorization and order completion.

Custom payment provider

• Creates gateway payment requests.
• Stores identifiers such as invoice or transaction references.
• Handles payment authorization and status checks.
• Implements the supported refund flow.

Payment gateway

• Presents the customer-facing payment interface.
• Processes the transaction.
• Returns or exposes transaction information for verification.

The frontend should not contain secret API keys or independently decide whether an order is paid. Those responsibilities belong on the backend.

5. MyFatoorah Integration Process with Medusa v2#

For an e-commerce project using Medusa v2 and Next.js, a custom MyFatoorah provider can connect the commerce platform to the gateway.

A typical implementation involves the following steps.

Step 1: Configure the merchant environment#

The backend needs the correct API endpoint, API key, and environment configuration.

Sandbox and production credentials must be managed separately. A valid test key cannot be assumed to work against the live API, and production access may require additional merchant activation.

Credentials should be stored in server-side environment variables and must never be exposed in frontend code or public logs.

Step 2: Initialize the payment#

The backend calls the appropriate MyFatoorah API to initialize the payment and retrieve the necessary payment information.

Depending on the selected integration flow, the response can include payment-method details, an invoice identifier, and a payment URL.

The application must persist the identifiers and information required to connect the gateway transaction to the Medusa payment session and cart.

Step 3: Redirect the customer#

The storefront uses the payment information returned by the backend to redirect the customer to the hosted payment page when that integration approach is used.

The browser redirect is part of the customer experience; it is not the final authority on payment status.

Step 4: Verify the payment#

After the customer completes or leaves the payment flow, the backend should retrieve the transaction status through the appropriate MyFatoorah API.

The application must distinguish successful, pending, failed, and cancelled outcomes according to the gateway's documented responses.

Step 5: Complete the order#

Once the transaction has been verified and matched to the correct payment session, the backend can proceed with the appropriate Medusa payment and order-completion workflow.

If verification fails, the system should not create an order marked as paid.

6. Real-World Challenge: MyFatoorah Live API Authentication#

One of the most important issues I encountered was a difference between sandbox testing and live API authentication.

During testing, the sandbox environment allowed me to retrieve payment-method information. However, the live API returned an HTTP 401 response with an error indicating that the token was invalid or expired.

The important detail was that the error also occurred when I tested the API directly using cURL, outside the application.

This helped narrow the investigation: the issue was not necessarily caused by the Next.js checkout component or Medusa's payment-session workflow.

What I investigated#

• Whether the correct live API endpoint was being used.
• Whether the API key belonged to the intended environment.
• Whether the key had been copied correctly.
• Whether the production backend was loading the intended environment variable.
• Whether duplicate environment entries or process-level configuration could affect the active credentials.
• Whether merchant activation or account permissions required attention from MyFatoorah support.

Technical lesson#

An API key appearing active in a merchant portal does not, by itself, prove that live API access is working.

Testing the API independently helps separate gateway authentication problems from application-level bugs.

The live authentication issue should be considered resolved only after the intended production credentials successfully authenticate against the live endpoint and a complete payment flow has been verified.

7. Payment Methods: Sandbox Availability vs Production Availability#

Another important lesson is the difference between payment methods returned during development and those available to real customers.

MyFatoorah's payment-method retrieval flow can return methods supported by the configured environment and account. However, sandbox results should not be treated as proof of production eligibility.

For example, seeing KNET, Visa, Mastercard, or digital-wallet options in a test response does not necessarily mean every method is activated for the live merchant.

Before launch, confirm:

• Which payment methods are enabled for the merchant's country and account.
• Whether the live API returns the expected methods.
• Whether each method is available for the intended currency.
• Whether any additional merchant onboarding or verification is required.

This is particularly important when a business advertises several payment options on its checkout page.

8. Currency and Amount Conversion: Handling KWD Correctly#

Currency handling is one of the most important parts of payment integration.

Kuwaiti dinar (KWD) uses three decimal places. When connecting a commerce platform to a payment gateway, developers must understand how each system represents monetary amounts.

For example, the following amount represents the same value when expressed in different formats:

RepresentationExampleKWD major-unit amount3.150 KWDInteger representing thousandths of a KWD3150

These representations are not interchangeable without an explicit conversion.

During integration, I investigated a discrepancy between the cart amount and the amount passed to the gateway. The implementation included amount-handling logic that could divide values by 1,000 when they crossed a numeric threshold.

This approach is risky because a numeric threshold cannot reliably tell a developer whether an amount is expressed in major units or minor units.

Recommended approach#

1. Confirm the exact monetary representation used by the Medusa version and data being read.
2. Confirm the amount format expected by the MyFatoorah API.
3. Implement one explicit conversion at the appropriate boundary.
4. Avoid repeatedly converting the same amount across different layers.
5. Compare the cart total, payment-session amount, and gateway invoice amount.
6. Test decimal values, including amounts with three decimal places.

A payment should not proceed if the amount or currency sent to the gateway does not match the intended checkout total.

9. Payment Sessions, Callbacks, and Cart Mapping#

A payment session must preserve enough information to connect the gateway transaction to the correct Medusa cart and payment record.

During callback troubleshooting, I encountered a case where the application could not resolve the cart ID from the callback query parameters or the gateway's UserDefinedField. This resulted in a missing-cart payment error.

The issue demonstrated that a gateway transaction can have a valid reference while the commerce application still lacks the information needed to finish the checkout.

Information worth preserving#

Depending on the integration flow, the backend may need to retain:

• Medusa cart or payment-session identifier.
• Gateway invoice identifier.
• Transaction or tracking reference.
• Expected amount and currency.
• The relevant payment status and verification information.

A gateway-provided custom field can help associate a transaction with an application record, but it should not be treated as independent proof that the transaction is valid.

Callback handling best practices#

• Validate the gateway transaction server-side.
• Match the transaction to the expected payment session and cart.
• Verify amount and currency.
• Handle duplicate callback requests safely.
• Prevent repeated order completion.
• Distinguish failed, pending, and successful payments.
• Log useful transaction references without exposing secrets or unnecessary customer information.

The final order state should be based on verified payment information, not merely on the customer reaching a success URL.

10. Refunds, Security, and Operational Reliability#

Refund support depends on the provider's available APIs, merchant permissions, and transaction rules.

MyFatoorah provides refund-related API functionality, but developers must implement the relevant workflow and handle its response correctly. Refund requests should be associated with the original transaction and reconciled against the gateway's result.

Security also depends on the chosen integration method. Hosted checkout can reduce the amount of payment-card handling performed by the merchant's application, but it does not automatically eliminate every PCI DSS or other compliance obligation.

For a production-ready integration:

• Keep secret keys on the backend.
• Validate payment status through trusted server-side mechanisms.
• Protect callback endpoints and validate transaction references.
• Avoid logging full API credentials or sensitive card data.
• Use idempotent handling for repeated payment events.
• Record transaction references for support and reconciliation.
• Confirm the applicable security and compliance requirements with the gateway and acquiring provider.

11. Direct KNET vs MyFatoorah: Which Should You Choose?#

Choose direct KNET integration when:#

• Your business primarily serves customers in Kuwait.
• KNET is the main payment requirement.
• You have the required acquiring-bank or provider relationship.
• You can manage the provider-specific onboarding, testing, and maintenance.
• You need an integration tailored to the available KNET services.

Choose MyFatoorah when:#

• You need KNET alongside other supported payment methods.
• You prefer a unified gateway API.
• Your merchant account supports the methods and markets you need.
• Hosted checkout, payment links, or other gateway services fit your workflow.
• You want to manage supported payment methods through one gateway integration.

Before making a decision, compare merchant eligibility, transaction fees, settlement terms, refund capabilities, supported currencies, technical documentation, and support arrangements. These can vary by account and agreement.

12. Production Readiness Checklist#

Before launching either integration, verify the complete transaction lifecycle rather than testing only whether the payment page opens.

• Sandbox credentials and endpoints work.
• Live credentials and endpoints are independently verified.
• The intended payment methods are enabled for the merchant.
• The cart total matches the gateway invoice amount.
• Currency and decimal conversion are correct.
• Payment-session identifiers are stored correctly.
• Successful transactions are verified server-side.
• Failed and cancelled payments do not create paid orders.
• Missing or invalid cart references are handled safely.
• Duplicate callbacks do not cause duplicate processing.
• Refund handling is tested where supported.
• Logs and reconciliation records are sufficient for troubleshooting.
• Production checkout and merchant activation have been verified.

Final Verdict#

Direct KNET integration and MyFatoorah serve related but different purposes.

Direct KNET can be suitable for businesses whose payment requirements are focused on Kuwait and KNET. MyFatoorah can be a better fit for businesses that need access to multiple supported payment methods through a unified gateway platform.

However, the choice of provider is only one part of building a reliable payment experience. The quality of the implementation depends on correct credentials, consistent currency handling, secure payment verification, reliable session and cart mapping, and proper order-state management.

My experience integrating MyFatoorah with Medusa v2 and Next.js reinforced an important engineering lesson: a payment integration is not complete simply because an API returns payment methods or a customer reaches a success page. It must also verify the transaction, preserve the relationship between the payment and the order, and behave correctly when authentication, callbacks, or checkout processing fail.

For any e-commerce business preparing to launch, end-to-end testing in the intended production environment is the final step toward establishing that the payment flow is ready for customers.