Module and release scope
This guide covers Tap Payments Hosted Checkout 1.0.0, Extension API 1, from the reviewed product source. Its declared core range is 1.3.6–1.3.99. Use the matching released core and signed provider package; a version label alone does not install the required contracts. Source availability does not mean the module is bundled in every currently downloadable product, installed on your server, enabled or certified for your merchant/server account. Nothing in this guide enables a provider or changes your existing connections.
Open System → Payment gateways (newer source may group these as Payments, Domain services or Hosting services). Install the reviewed signed package through Modules & addons or the integration workspace's Install tab, enable the module separately, add an account/connection, save its own credentials, run its stated Test and explicitly enable the connection. Saving or retesting disables the connection until you enable it again. Start with the provider's test environment where supported; otherwise use an isolated account or server.
Exact connection fields
These are the fields declared by this module. Secret values are entered privately and encrypted by the application. Defaults are configuration hints, not approved live merchant settings. Internal fields are populated by the module and are not operator-editable.
| Key / label | Type | Required | Default / guidance |
|---|---|---|---|
mode — Environment |
select | Yes | Default: "sandbox" Choices: sandbox = Sandbox, live = Live |
secret_key — Secret API key |
secret | Yes | Use the secret key for the selected environment, with charge creation and retrieval access. |
merchant_id — Merchant ID |
text | Yes | The merchant ID issued by Tap for this account. It is checked on captured payments. |
currencies — Enabled invoice currencies |
text | Yes | Default: "SAR" Comma-separated currencies approved by Tap: AED, SAR, QAR, USD, EUR, GBP or EGP. No invoice currency conversion. |
Uses Tap v2 Charges with source.id=src_all, so the hosted page displays the merchant's enabled payment methods rather than a fixed card-only form.
Account setup
Obtain a merchant secret API key and merchant ID from Tap's merchant/developer account. Choose Sandbox for sk_test_ keys and Live for sk_live_ keys. Grant charge creation, charge retrieval and charge-list access. Enter only approved currencies: AED, SAR, QAR, USD, EUR, GBP and EGP. Tap's regional onboarding and local methods vary; three-decimal currencies are excluded because the product ledger uses two decimals. Complete the customer's real billing name before checkout.
The connection test posts a read-only /v2/charges/list query for an unissued reference. It creates no charge. Checkout uses /v2/charges; success is accepted only from authenticated /v2/charges/{id} with CAPTURED, matching merchant/environment and matching attempt/amount metadata.
Webhook and return
The application passes its generated connection webhook URL as post.url and its signed customer return URL as redirect.url. Keep that webhook URL public over HTTPS; do not substitute a storefront homepage. Tap sends hashstring, validated with the same secret API key using Tap's documented ordered fields and fixed decimal amount. Even signed events trigger an authenticated charge read. A tap_id appended to the browser URL is checked only as a locator; it cannot authorize payment. Staff reconciliation repeats the authenticated read.
Provider documentation
- Charges and source IDs
- Read-only charge list
- Webhook hashstring verification
- Integration recommendations
Reviewed 21 October 2026.
Install and enable
Requires EmailaBiller 1.3.6 or newer within the 1.3 release line.
Upload the signed package through System → Payments → Install, verify its checksum/publisher and install it. New modules and connections remain disabled. Enable the module, create a connection, enter your own credentials, run Test, then enable that connection and assign it to the intended storefront. No merchant details, credentials, existing connections or business defaults ship in this package.
Payment safety
Customers enter payment details on the provider's HTTPS page. The application never collects a PAN, CVV or reusable card token. API destinations are fixed; returned checkout URLs must match the official provider hosts. Checkout creation is submitted once, without automatic retries. After a timeout, reconcile the original checkout before creating another.
A browser return supplies no payment authority. The module verifies settlement through authenticated reads, then the core checks the stored checkout, attempt, exact amount/currency and invoice. Pending payments, uncaptured authorisations, refunds, errors and identity mismatches do not produce payment credit. Provider transaction IDs produce stable event keys, so repeating a verified notification or reconciliation does not create a second ledger entry. Only two-decimal invoice currencies are supported; there is no exchange-rate calculation or invoice conversion.
Run php tests/gateway-middle-east.php for isolated mocked API/security checks. Tests do not contact a provider or use a live database. Before enabling production, complete the provider's merchant onboarding and exercise the intended methods using your merchant's sandbox facilities. Available cards, wallets and local methods depend on country, currency, account approval and shopper/device eligibility.