PayFast South Africa Hosted Payments — setup and reference

Module and release scope

This guide covers PayFast South Africa Hosted Payments 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_id — Merchant ID	text	Yes	Use the account-specific value described below.
merchant_key — Merchant key	secret	Yes	Use the account-specific value described below.
passphrase — Security passphrase	secret	Yes	Set the identical passphrase in the PayFast merchant dashboard. Required here for signed payment notifications.
currencies — Invoice currency	select	Yes	Default: "ZAR" Choices: ZAR = ZAR

This package integrates PayFast South Africa, not the unrelated Pakistani service with a similar name. Only ZAR invoices of at least ZAR 5.00 are supported. Customers are sent directly to PayFast's hosted payment page with the methods enabled for the merchant. No recurring subscription or tokenized charge is created.

1. Enter the merchant ID, merchant key and security passphrase from the chosen PayFast environment. Set the exact same passphrase in the provider dashboard.
2. Ensure API access and any outbound IP allowlist permit signed read-only API calls. Test sends a signed API ping with the sandbox testing flag when appropriate and verifies the documented API V1 sandbox or Payfast API live response.
3. The form automatically sends EmailaBiller's displayed callback URL as notify_url. Permit POST Instant Transaction Notifications (ITNs) to that exact URL; do not route it through a login page.
4. Complete a sandbox payment and confirm a valid ITN arrives. Browser redirects deliberately keep the invoice awaiting confirmation until ITN verification succeeds.

Notifications must pass the official ordered MD5/passphrase signature check using all returned fields including empty values, exact whitespace and the documented stripslashes normalization, configured merchant ID, original invoice/reference binding and exact amount checks. The complete notification fields are then submitted to the official /eng/query/validate endpoint and must receive exactly VALID. A browser status, local signature alone or a provider INVALID response cannot mark an invoice paid. Staff cannot infer a successful payment from a return URL; inspect missing ITNs in the provider dashboard and resend them.

Official references: PayFast custom hosted integration and ITN validation, PayFast API authentication, Official PHP SDK.

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.