Connecting a payment gateway

Online payment lets a subscriber or a reseller top up a wallet with a card, a mobile wallet, or cash against a reference code.

Before you start

You need three things:

1. A merchant account with at least one provider. We do not resell payment processing: you sign your own agreement and the money lands in your own account.
2. A publicly reachable instance. Providers call back over the internet. If the instance has no public address configured, the gateway settings page says so and no gateway can be used.
3. The settings permission to configure a gateway, and separately the self-deposit permission if a manager should be able to top up their own wallet.

The five providers

SAS-Pay, Fawry, EasyKash, Paymob and Kashier. SAS-Pay fronts several of the others behind one account and is the quickest to switch on; the direct integrations exist because a direct account avoids the added fee and the daily invoice cap that a fronting account carries.

Several can be enabled at once, and the buyer then picks one.

Each provider declares which payment methods it can take — card, mobile wallet, or a cash reference code — and you can narrow that further per gateway. Turn every method off and the gateway disappears from the payment page rather than appearing as a button that cannot be pressed.

Configure a gateway

Under Settings → Payment Gateways, pick a provider and fill in its fields. Secrets are encrypted before they reach the database and are never sent back to the browser: re-opening the form shows you which secrets are set, not their values. Leave a secret blank to keep the stored one.

Then press Test. It makes a real create-payment call with a nominal amount and records the exact result. It writes no transaction and charges nobody. A gateway that has never passed its test will still run, but you are flying blind.

Two optional fields hold the provider's fee, as a percentage and as a flat amount. They are what you tell us your provider charges, so the payment page can show the buyer the total before they commit. Leave them blank and no fee line is shown at all — we do not guess, and a wrong guess reads as a promise.

The three URLs

Each configured gateway shows three addresses to paste into the provider's dashboard: one callback and two redirects.

Only the callback confirms a payment. The redirects decide where the buyer's browser lands afterwards, and nothing more — somebody who types the success address by hand is not credited, because the page re-reads the real status from our own records.

Both redirects send the browser to your tenant's own address, not the instance's. A session lives on one host, so landing a buyer on the instance address would show them a sign-in screen for an account they are already signed in to.

How a payment is confirmed

Two independent paths settle every payment: the provider's callback, and a poller that asks the provider about transactions that have not settled. Either one can complete a payment, and a unique constraint on the provider's own reference makes a double credit impossible even when both arrive.

The gateway transaction console shows every attempt with its state, so support can answer "did this payment arrive" without opening the provider's dashboard.

If it did not work

• The buyer paid but the wallet was not credited. Look at the transaction console. If the provider never called back, check the callback address in their dashboard; the poller will usually settle it within its next cycle.
• The provider rejects the payment immediately. A test credential paired with a live integration identifier is the usual cause, and it produces an error that reads as if the integration does not exist.
• The gateway does not appear to the buyer. Every payment method is turned off for it, or the instance has no public address configured.