Telr Hosted Payment Pages — setup and reference

Module and release scope

This guide covers Telr Hosted Payment Pages 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 = Test transactions, live = Live transactions
store_id — Store ID	text	Yes	Use the account-specific value described below.
auth_key — Hosted payment page authentication key	secret	Yes	Use the account-specific value described below.
probe_order_ref — Order reference for connection test	text	Yes	Use an existing order reference from this Telr store, for example a test order created in the Telr dashboard. Test only reads its status and never charges it.
currencies — Enabled invoice currencies	text	Yes	Default: "AED" Comma-separated two-decimal currencies enabled by Telr for this store. No invoice conversion.

Uses the documented HPP order.json flow, independent of Telr's direct card or mobile SDK APIs.

Account setup

Retrieve your store ID and Hosted Payment Page authentication key from the Telr merchant dashboard. Ensure the store permits HPP order creation and order-status checks. Choose Test or Live; the module sends the HPP order's test flag explicitly. The only API and hosted-payment host is secure.telr.com.

For Test connection, enter an existing order reference belonging to this store, such as an order created in the Telr test/dashboard facilities. The test reads its status; it does not create an order or authorize a payment. An order reference from another store, an authentication error or an unconfirmed response cannot verify the connection. The reference remains configuration metadata only and never changes a customer invoice.

Enable only currencies approved for this store: AED, SAR, QAR, USD, EUR, GBP, INR, EGP, AUD or CAD. Regional account approvals and local methods are controlled by Telr. Three-decimal currencies are excluded. The hosted page collects further billing details requested by the merchant's Telr configuration.

Return and confirmation

Checkout posts method=create to /gateway/order.json, with a unique cart/attempt ID, exact decimal amount and matching extra metadata. The returned order reference must match the official hosted URL's o parameter. The application provides its signed return URL for authorized, declined and canceled outcomes. Keep Telr’s optional transaction-detail-on-return feature disabled; it is unnecessary and can put customer/card information into URLs. The saved checkout order reference is sufficient.

The return itself cannot prove settlement. An authenticated method=check must confirm the same order/environment, paid status code 3, an approved sale transaction and exact attempt/amount/currency metadata. On-hold authorizations, preauthorizations, refunds and mismatches do not settle invoices. Staff can repeat this check using reconciliation. This HPP implementation does not process arbitrary Telr transaction webhooks or require a webhook signing key; it uses browser return plus authenticated checks. Closing the browser leaves the attempt for reconciliation rather than declaring it unpaid.

Provider documentation

• HPP flow
• Create session
• Read-only order-status check
• Optional return details
• Extra metadata and paid-order example

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.