Saudi & Levant Payment Gateway Connector (HyperPay)

The problem this solves

If you sell in Saudi Arabia you are dealing with Mada, the domestic debit scheme that carries a large share of card transactions in the kingdom and behaves differently from international card brands in its fee structure, its settlement timing and its refund handling. If you also sell into the UAE, Egypt or Jordan you are dealing with different currencies, different acquiring banks and different settlement cycles. The gateway your bank put you on is licensed by the regional regulator and works fine for taking money — but it has no connection to NetSuite whatsoever.

So the payment happens outside the ERP. Someone exports a transaction report from the gateway portal, matches it against open invoices by eye or by reference number, keys Customer Payments into NetSuite, and hopes nothing was missed. Refunds get processed in the portal and forgotten in NetSuite. Settlement batches arrive at the bank net of merchant discount rate and per-transaction fees, so the bank statement never matches the sum of the payments recorded. Multi-currency makes it worse, because the amount authorized, the amount settled and the amount that hits the account can each be a different figure.

NetSuite has no native path to this gateway. There is no SuiteApp for it, and the standard payment-processing framework does not cover it.

What ECOSIRE builds

ECOSIRE builds a NetSuite customization that connects your gateway account to your NetSuite account directly, delivered as an unmanaged bundle or SDF project you own. This is built to order against your merchant configuration, your subsidiaries and your chart of accounts — nothing is pre-built.

Payment capture and posting

A RESTlet receives payment notifications from the gateway. Every notification is verified against the gateway's signature or checksum scheme before anything posts, and the raw payload is stored on a custom transaction-log record. A Map/Reduce script then locates the target transaction — typically an open Invoice or a Sales Order awaiting payment — using a reference written into the payment request, and creates the appropriate NetSuite record.

Where the payment settles an existing invoice, a Customer Payment is created and applied. Where it is taken before invoicing, a Customer Deposit is created against the Sales Order so the deposit is applied automatically when the invoice is raised. Where the payment cannot be matched, it is routed to an unapplied-payments queue with the full gateway payload attached, rather than being force-applied to the wrong customer.

Mada, card brands and payment-method mapping

A custom record maps each gateway payment brand — Mada, international card brands, and any wallet or local method you have enabled — to a NetSuite Payment Method and a GL account. This matters because Mada and international card transactions carry different merchant discount rates and often settle on different cycles, and you need them separable in the ledger. Card metadata that is safe to store — brand, last four digits, authorization code, gateway transaction ID — is written to custom fields on the payment record for audit and dispute handling. No card numbers or CVV data are stored in NetSuite at any point; the integration is built so that cardholder data never enters your NetSuite account.

Refunds, voids and chargebacks

Refunds initiated in NetSuite drive the gateway rather than the other way round. A Customer Refund or Credit Memo triggers a refund call to the gateway through a Suitelet-driven action, and the gateway response is written back so NetSuite and the gateway agree on state. Partial refunds are supported against the original authorization. Refunds initiated in the gateway portal are picked up by the reconciliation script and raised in NetSuite so the two systems converge. Chargebacks and reversals are logged and flagged for finance review rather than posting silently.

Settlement reconciliation and multi-currency

A Scheduled script imports settlement batches. Each batch is created as a custom settlement record listing its constituent transactions, the gross amount, the merchant discount rate, per-transaction fees and the net amount deposited. Fees post to a dedicated expense account through a mapping table, and the net figure clears against a gateway clearing account so the bank deposit reconciles as one line. For OneWorld accounts, each merchant configuration is bound to a subsidiary and a currency, so a Saudi merchant account posts to the Saudi subsidiary in SAR while an Egyptian or Jordanian account posts to its own subsidiary in its own currency, with exchange differences handled by NetSuite's standard revaluation.

Roles, security and logging

A dedicated integration role is created with only the permissions the scripts require, and inbound calls use token-based authentication. Every request and response is logged to a custom record with a retention policy you set. A saved search surfaces failed, unmatched and pending transactions so finance has one place to look each morning.

Who this is for

Merchants already running NetSuite who take card and Mada payments in Saudi Arabia, and typically also in the UAE, Egypt or Jordan. It fits companies whose finance team is currently keying payments from a gateway portal export and whose bank reconciliation is complicated by merchant fees deducted before deposit.

It is not a hosted checkout page and it is not a substitute for a merchant agreement — you bring your own gateway account and your own acquiring relationship.

How delivery works

Scoping call. We review your merchant configurations, the payment brands you accept, your subsidiaries and currencies, how you want fees and clearing accounts structured, and whether payments arrive against invoices, sales orders or both.

Fixed quote. A written scope and a fixed price are agreed before development starts. The listed price covers a standard single-merchant, single-subsidiary build; additional merchant accounts, subsidiaries or a bespoke reconciliation treatment are quoted explicitly.

Build. Typical lead time is one working week. Development uses SuiteScript 2.1 — RESTlets for inbound notifications, Map/Reduce for batch posting and reconciliation, Scheduled scripts for settlement import, User Event scripts for transaction guards — with SuiteFlow used for approval and exception routing.

Install in test, then production. The bundle is installed in your sandbox and tested against the gateway's test environment, including a full settlement cycle, a partial refund and a deliberately unmatchable payment to prove the exception path. It moves to production only after you have reconciled a test settlement batch end to end.

Support. A support window follows go-live, covering defect fixes and gateway API changes announced during that period. You receive the full source and can maintain it yourself afterwards.