Amazon Payment Services Hosted Checkout — setup and reference

Module and release scope

This guide covers Amazon Payment Services 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
merchant_identifier — Merchant identifier	text	Yes	Use the account-specific value described below.
access_code — Access code	secret	Yes	Use the account-specific value described below.
request_phrase — SHA request phrase	secret	Yes	Use the account-specific value described below.
response_phrase — SHA response phrase	secret	Yes	Use the account-specific value described below.
sha_type — SHA algorithm	select	Yes	Default: "sha256" Choices: sha256 = SHA-256, sha512 = SHA-512
currencies — Enabled invoice currencies	text	Yes	Default: "AED" Only two-decimal currencies approved for this merchant. Three-decimal KWD, BHD, JOD and OMR are excluded.
test_reference — Existing merchant reference for connection test	text	No	Optional existing payment reference for a read-only CHECK_STATUS authentication test. No charge is created.

This module is Amazon Payment Services (PayFort) for approved MENA merchants, distinct from the separate Amazon Pay wallet API. It submits a PURCHASE to the APS hosted page, where approved card and local methods are selected by the provider. It supports approved two-decimal AED, SAR, EGP, QAR, USD, EUR and GBP invoices. Three-decimal KWD, BHD, JOD and OMR are excluded; no currency conversion occurs.

1. Obtain merchant identifier, access code, SHA request phrase and SHA response phrase under the provider's security settings. Configure the same SHA-256 or SHA-512 algorithm in both systems.
2. Configure the provider notification/webhook URL to the exact callback URL shown by EmailaBiller, and allow the return domain as required by APS. One central callback can serve all storefront domains.
3. Without an existing reference, Test honestly validates configuration locally and reports authentication_confirmed: false. To test authentication without charging, enter an existing merchant reference: Test uses read-only CHECK_STATUS and validates the signed response.
4. Complete a sandbox PURCHASE, then verify its callback and invoice allocation before live enablement.

A valid signed PURCHASE callback must include the merchant, original attempt, amount and currency. The module independently sends a signed CHECK_STATUS query and verifies the response signature, current transaction reference, completed purchase/capture code, matching captured amount and zero refunded amount. Authorization-only, partial captures, refunds, changed money, forged callbacks and unsigned API responses cannot settle. Browser POST returns use the same verification. A fresh status response without the original signed currency-bearing callback is insufficient for reconciliation, so this package does not advertise a standalone staff reconciliation action.

Official references: Hosted Checkout, CHECK_STATUS API, Signature calculation.

Install this signed package under System → Payment gateways → Install module. New installations are disabled. Create a separate connection, enter your own merchant credentials, run Test, and explicitly enable that connection after completing sandbox checkout and callback testing. No merchant credentials or business settings are included in this package.

The module uses verified HTTPS with fixed official provider endpoints, no redirects or automatic API retries, bounded uncompressed responses, exact two-decimal invoice accounting, and credential-safe errors. Network timeouts leave payment under review: inspect the provider before retrying. Provider methods depend on merchant approval, payer location, currency and device; installing this module does not promise every payment method. The module never collects card numbers, expiry dates or CVV.