How to Integrate Saudi Payment Gateways: HyperPay, Tap, and Moyasar

Saudi payment gateway integration in 2026 comes down to three real choices, HyperPay, Tap, and Moyasar, each offering a REST API plus a hosted or widget-based checkout, and each supporting Mada, the Kingdom’s domestic card scheme, alongside Visa and Mastercard. All three operate under SAMA’s licensing regime for payment service providers, which means the integration choice affects compliance posture as well as code.

This guide is part of the developer-focused training content on Skillvotech’s KSA site, walking through the actual integration pattern for each gateway, how webhook confirmation works once a payment settles, and the Mada and PCI-DSS considerations that apply regardless of which one a project picks. It assumes a working knowledge of REST APIs and server-side request handling.

HyperPay Integration: COPYandPay Widget vs Server-to-Server

HyperPay, headquartered in Riyadh, offers two integration paths from its own integration guide: a JavaScript widget called COPYandPay, and a direct Server-to-Server API. The widget path sends card data straight from the shopper’s browser to HyperPay, which keeps raw card numbers off the merchant’s own server entirely.

COPYandPay works by having the backend first request a checkout ID from HyperPay’s API, then embedding that ID in a small JavaScript snippet on the payment page. The widget renders its own card form and handles submission directly, so the merchant page never touches the card number, only the resulting transaction status. This is the faster integration path and the one most Saudi ecommerce teams start with.

The Server-to-Server option gives the backend full control over the payment form’s look and flow, at the cost of the merchant’s own server briefly handling card data before forwarding it, which pulls the integration into a stricter PCI-DSS scope (see the compliance section below). HyperPay’s own documentation notes that production credentials go through a verification process before a live merchant account activates, so budget lead time for that step separately from the coding work itself.

Tap Payments Integration: Charges, Authorization, and Capture

Tap Payments runs a self-serve REST API, documented at developers.tap.company, that a developer can start integrating against immediately after generating API keys from the dashboard, with no formal application step before sandbox access. The core flow is a charge request: the backend sends the amount, currency, and a redirect URL to Tap’s charges endpoint, then redirects the customer to Tap’s hosted payment page to enter card details.

Tap also supports a separate authorize-then-capture flow, useful when a business needs to hold funds before confirming a sale, a common pattern for pre-orders or delayed-fulfillment retail. Saved-card tokens, refunds, and multi-party payouts sit behind the same API, which matters for a marketplace or platform business splitting a single payment across multiple sellers.

Beyond cards and Mada, Tap’s Saudi integration surface includes Tamara and Tabby, the two buy-now-pay-later providers most Saudi shoppers already expect at checkout. A team scoping a Tap integration should confirm early whether BNPL support is in scope for this project, since it changes the checkout UI requirements, not just the backend call.

Moyasar Integration: Hosted Checkout, SDKs, and Sandbox Testing

Moyasar, founded in 2015 and operating under SAMA supervision, publishes its full developer documentation at docs.moyasar.com, including a dedicated basic-integration guide. It offers three integration depths: hosted checkout pages that need almost no frontend work, in-app SDKs for native mobile checkout, and a direct API for teams that want to build their own payment form.

The direct API path follows the same general shape as the other two gateways: the backend creates a payment resource server-side, carrying the amount, currency, and a source (the tokenized card or Mada details), then reads back the resulting payment status. Moyasar’s sandbox environment lets a team run that full flow, including declined and 3-D Secure test cases, before any production credentials are involved, which is the right place to catch integration bugs rather than in a live checkout.

Because Moyasar operates under direct SAMA supervision as a licensed payment infrastructure provider, teams working in regulated sectors such as banking-adjacent fintech sometimes default to it specifically for that regulatory posture, worth confirming against the project’s own compliance requirements rather than assuming it applies automatically.

Handling Webhooks: The Step Most Integrations Get Wrong

A webhook is the payment gateway calling back to the merchant’s own server once a transaction’s final state is known, and skipping proper webhook handling is the most common integration mistake across all three gateways. Relying only on the browser redirect after checkout to mark an order as paid misses the case where a customer closes the tab before the redirect completes, a transaction the merchant never learns settled.

Verify the Webhook Signature Before Trusting the Payload

Every one of the three gateways signs its webhook payloads so the receiving server can confirm the call actually came from the gateway and not a spoofed request. Skipping signature verification and processing the payload directly is a real fraud vector, since anyone who discovers the webhook URL can otherwise submit a fake “payment succeeded” event.

Make the Webhook Handler Idempotent

A gateway will retry a webhook delivery if the merchant’s server doesn’t respond quickly with a success code, which means the same event can arrive more than once. The handler needs to check whether it has already processed that specific transaction ID before updating order status again, or a retried webhook can double-fulfill an order.

Treat the Webhook as the Source of Truth, Not the Redirect

The browser redirect after checkout is for the customer’s experience, showing a confirmation page, not for confirming payment actually happened. Order status should update from the webhook event, with the redirect page only showing a “processing” state until that webhook lands, usually within seconds but not guaranteed to be instant.

Mada and PCI-DSS: What Every Integration Needs

Mada, Saudi Arabia’s domestic debit card scheme, isn’t optional for a Saudi-facing checkout. A large share of Saudi debit cards are Mada-only and won’t authorize through a Visa or Mastercard rail alone, so a gateway integration that skips Mada support will silently fail for a meaningful share of local customers, not just underperform.

• Confirm Mada is enabled on the merchant account, not just supported by the gateway generally, since some sandbox setups default it off.
• Test a real Mada card in sandbox before going live, since Mada’s authorization flow can behave differently from an international card in edge cases like 3-D Secure prompts.
• Keep raw card data out of application logs, a basic PCI-DSS requirement that’s easy to violate accidentally through a generic request-logging middleware that captures full POST bodies.
• Use the gateway’s hosted or widget checkout where the project allows it, since that keeps card data off the merchant’s own servers entirely and meaningfully reduces PCI-DSS scope compared to a direct Server-to-Server integration.

Sandbox to Live: Payment Gateway Integration Comes Down to This

Sandbox testing catches most integration bugs, but the two failures that only show up in production are webhook delivery under real network conditions and Mada authorization edge cases, so both deserve a dedicated go-live checklist, not just a final sandbox pass. The three gateways covered here share a common shape, backend creates the payment, webhook confirms it, but their specific integration depth and BNPL support differ enough to change which one fits a given project.

Teams building this without prior payment-integration experience typically underestimate the webhook and PCI-DSS work, not the checkout form itself, that’s where the real integration risk sits.

Frequently Asked Questions

Which gateway is easiest to integrate first?

HyperPay’s COPYandPay widget and Moyasar’s hosted checkout both need minimal frontend work, making either a faster first integration than a full Server-to-Server build.

Do I need a Server-to-Server integration, or is a hosted checkout enough?

A hosted or widget checkout is enough unless the project needs full control over the payment form’s design or a custom multi-step checkout flow.

Is Mada support automatic once I integrate one of these gateways?

No, confirm Mada is explicitly enabled on the merchant account and test it in sandbox, since some setups default it off even when the gateway supports it generally.

How is Moyasar different from Tap or HyperPay?

Moyasar operates under direct SAMA supervision as a licensed payment infrastructure provider, which some regulated-sector teams weigh alongside its hosted checkout, SDK, and API options.

What happens if I skip webhook signature verification?

A server that trusts unsigned webhook payloads can be tricked into marking a fake transaction as paid, since anyone who finds the webhook URL could submit a spoofed success event.

HyperPay Tap Moyasar Integration: The Practical Answer

All three gateways solve the same core problem, moving money through a Mada-compliant, SAMA-licensed channel, and the real integration decision comes down to how much frontend control a project needs versus how fast the team wants to ship. HyperPay and Moyasar’s widget and hosted paths get a standard checkout live fastest, Tap’s self-serve API and BNPL support suit a team that wants more control from day one.

Whichever gateway a project picks, the webhook handling and Mada testing described above aren’t optional extras, they’re the difference between a checkout that works in sandbox and one that reliably charges real Saudi customers. Building that judgment into a team’s own delivery process is part of what our backend and API development training at Skillvotech KSA covers.

Developers building their first Saudi-market integration often benefit from seeing this alongside the complete web developer roadmap for where API integration work fits into a broader Saudi web development career.