WooCommerce plugin

Install and configure EFT Pay for WooCommerce, maintained by EFT Corp, to accept payments through secure hosted checkout. This guide takes you from merchant approval and sandbox setup through testing, production activation and day-to-day payment reconciliation.

The plugin connects WordPress directly to EFT Pay. It creates a payment for the WooCommerce order, sends the customer to hosted checkout, verifies the result and updates the order. Payment details are entered on hosted checkout; the EFT Pay plugin does not collect full card numbers or CVV in WordPress. You do not need to build a payment API integration or run a separate payment service.

This guide applies to the 1.0.0 candidate. The plugin supports one-time positive ZAR payments, WooCommerce Classic Checkout, Checkout Blocks and High-Performance Order Storage (HPOS). It imposes no R100,000 transaction ceiling. Provider and merchant-account limits still apply, and amounts must retain exact cents.

This source guide is being updated for the 1.0.0 release candidate. It does not
announce a public release, WordPress.org approval or a published production update
service. Obtain the approved package from EFT Pay; software updates and payment
Sandbox/Live settings are separate choices. The current staff QA package is
eft-pay-1.0.0-qa-candidate.zip, not a general merchant release.

The separate WordPress.org submission candidate uses native WordPress updates and text
payment-method labels while logo redistribution rights are being confirmed. All payment
methods remain configurable; removing artwork does not remove a payment option. The final
manual pipeline stage builds and checks that ZIP for review. It does not announce directory
approval, submit the plugin or deploy production payments.

Before you start

Complete merchant onboarding with the EFT Pay team first: join, submit your merchant application and verification documents, complete approval, and obtain your merchant connection details. Installing the plugin does not create or approve a merchant account.

You will need:

• WordPress 6.7 or later, WooCommerce 9.0 or later and PHP 8.1 or later with OpenSSL support.
• An installed, active WooCommerce store with its currency set to South African rand (ZAR).
• A publicly reachable HTTPS website with a trusted certificate. This is required for new payments in both Sandbox and Live; an HTTP localhost store cannot start hosted payments.
• The approved EFT Pay plugin ZIP, named eft-pay-<version>.zip.
• Environment-specific merchant configuration JSON, an EFT Pay API username and password, and an ACTIVE ZAR wallet owned by the approved merchant organisation.
• Signing keys are optional configuration fields. Add the outbound key if you want signed notifications; supply the API request key when your tenant requires signed API requests.
• A reliable WordPress cron runner so WooCommerce Action Scheduler can confirm payments even after customers close the browser.

Obtain the approved ZIP, merchant configuration and credentials from the EFT Pay team. Keep the JSON and credentials private; the JSON may contain signing secrets. Use merchant-scoped API credentials for each store. Sandbox and production have separate credentials and signing keys.

The current plugin does not initiate refunds from WooCommerce, save cards, process subscriptions or automate settlement. Agree refunds, settlement, fees and support arrangements with EFT Pay as part of onboarding.

Install the plugin

1. Back up the store before installing or updating a payment plugin.
2. In WordPress admin, open Plugins → Add Plugin → Upload Plugin.
3. Select the approved eft-pay-<version>.zip, click Install Now, then Activate Plugin. WooCommerce must also be active.
4. Open WooCommerce → Settings → Payments → EFT Pay.

The settings contain three tabs:

The plugin uses the eft-pay folder and eft-pay.php entry point. The staff QA plugin name is EFT Pay; the WordPress.org submission candidate is EFT Corp – EFT Pay for WooCommerce. You do not need Node.js, Docker or the QA deployment helper on a merchant store.

When upgrading from an older installation, upload the approved ZIP and activate EFT Pay. WordPress may list the previous installation separately because the folder name changed. Activation disables the previous site-level plugin; if both remain active, deactivate the previous installation before testing. Existing encrypted merchant profiles and payment records remain readable. Do not delete their settings or order metadata.

Connect your sandbox merchant

1. Under Payment environment, select Sandbox to edit that profile. Note the active environment shown in the header; selecting a profile does not activate it.
2. Open Merchant connection and paste the complete sandbox JSON into Merchant configuration.
3. Enter the EFT Pay username and EFT Pay password supplied for this sandbox merchant.
4. Click Save changes.
5. Click Test EFT Pay connection. Resolve any errors before enabling checkout.

The connection test checks public HTTPS and verifies API access to an ACTIVE ZAR wallet belonging to the configured merchant organisation. An outbound signing key is optional. It does not create a payment or prove that your website can receive notifications.

The JSON and password fields are blank when you reopen settings. This is intentional: saved secrets are not displayed. Leaving either field blank preserves its saved value. The saved summary shows Merchant ID and Settlement account without displaying the pasted security details.

Merchant configuration JSON

The simplest approved configuration contains your merchant IDs. Both signing-key fields can be omitted:

{
  "schemaVersion": 1,
  "environment": "sandbox",
  "tenantId": "123456",
  "organisationId": "123457",
  "walletId": "123458"
}

These are example values, not working credentials. Paste the configuration supplied for your merchant instead.

If you use signing keys, ask EFT Pay or your authorised tenant administrator for them. A WordPress application password, API login password or randomly generated store secret is not a substitute. Running without an API signing key works only when the tenant permits unsigned API requests; otherwise use a matching imported, saved or server-managed key. The plugin cannot override the provider's API requirements. The plugin supports HMAC v1 notification signatures; RSA v2 requires a different integration.

Do not add username, password, callback URLs, API addresses or payment confirmation settings to the JSON. Keep username and password in their separate fields. The plugin generates its own callback and uses fixed API addresses for each environment.

For configuration exporters, use positive decimal ID strings of up to 18 digits, without leading zeros. JSON is limited to 8,192 bytes. When supplied, signing keys must be nonempty strings of at most 1,024 bytes each, or null; empty strings are invalid. Unsupported fields, versions or environments are rejected. For keys stored through the JSON import, null clears a key; omitting a key preserves it only when the merchant identifiers are unchanged. Changing merchant identifiers clears omitted keys. Server-managed keys remain authoritative: omit their JSON fields to use them; a conflicting import is rejected. Do not replace merchant identifiers while orders still need reconciliation.

Confirm automatic order updates

Open Order updates and review Payment confirmation. A public HTTPS store without an outbound key shows Status checks active; Notification security shows Optional — using payment status checks. Direct authenticated API checks run on customer return, the admin order action and Action Scheduler jobs about every 60 seconds. New payments omit callbackUrl, and callbacks without a valid signing key are rejected.

Configure a reliable WordPress cron runner with your host. Scheduled checks must confirm payments after the customer closes the browser, even when the store has little traffic. Last verified notification remains empty until actual signed delivery; a status check never creates that receipt. There is no confirmation-mode selector: key availability determines whether notifications are requested.

If you configure the approved outbound key, signed notifications become the primary trigger with status checks as backup:

1. Add the approved outbound key in merchant configuration or through your server administrator, then confirm Notification security shows Configured.
2. Confirm Store connection shows Configured and the website is publicly reachable over HTTPS.
3. Copy the exact Notification URL displayed by the plugin. WordPress may generate a path-style or query-style URL; use the displayed value rather than constructing one yourself.
4. Ensure the endpoint accepts external POST requests without a WordPress login, HTTP Basic authentication or a browser security challenge. Firewalls and security plugins must preserve the original request body and Eclipse-Signature header.
5. Keep server time accurate so fresh signed notifications can be verified.

The plugin includes this URL on new hosted payments only when an outbound key is configured. You do not need to write a webhook handler. Typical callback paths are:

Sandbox: /wp-json/eftpay/v1/notify
Live:    /wp-json/eftpay/v1/notify/production

Configured confirms that a key is present and the generated URL passes the plugin's HTTPS checks. It does not prove public reachability or notification delivery. Last verified notification appears only after the plugin verifies a signed notification, maps it to an order and checks the payment directly with EFT Pay. Always check the payment result and order status as well; a verified notification can describe a payment that is still pending.

The callback route authenticates the provider using its signature. Keep that verification in place when allowing traffic through your firewall.

Enable payment methods

1. Open Payment methods in the Sandbox profile.
2. Turn on Enable EFT Pay sandbox checkout.
3. Select the payment options approved for your merchant.
4. Click Save changes.
5. If another environment is active, click Switch to sandbox. Confirm the header says Sandbox active before placing a test order.

The plugin brand is EFT Pay. Scan to Pay remains the official QR product name. The staff QA package displays its original logo; the WordPress.org candidate uses a text label. The eleven choices can be configured individually:

Only selected methods appear in WooCommerce checkout. Turning off the master checkout switch hides EFT Pay methods while retaining your selections; selecting no methods hides them all. Methods are configured separately for Sandbox and Live.

Enabling a method in WordPress does not provision it with the payment provider. Merchant approval, hosted-checkout configuration and device or wallet compatibility still apply. The plugin requests the selected method as the hosted checkout's default; customers may be able to choose another supported method there.

Understand the customer journey

1. The customer chooses an EFT Pay payment method in WooCommerce and places the order.
2. The plugin creates a hosted payment for that order, amount and merchant wallet.
3. The customer is redirected to hosted checkout to authorise payment.
4. Direct API status checks retrieve the authoritative payment and check the order, merchant, wallet, amount and currency. When an outbound key is configured, a signed EFT Pay notification also triggers that check after signature verification.
5. Only a verified successful payment completes the WooCommerce payment. WooCommerce applies its normal stock, paid-date and Processing or Completed status behaviour.
6. The customer returns to the store's order confirmation page. If confirmation is delayed, the return page checks automatically for up to one minute, then offers a safe recheck.

The customer does not need to keep the browser open when WordPress cron runs scheduled checks reliably. Configured signed notifications can also update the order. A browser redirect, screenshot or unverified success message cannot mark an order paid.

Test the complete sandbox flow

Use a publicly reachable HTTPS test store, fictional customer details and payment-provider-approved test values. The selected EFT Pay panel should show the red Sandbox test mode notice: No real money will be deducted. Use test payment details only.

For Bank card, the official hosted-checkout sandbox instructions specify:

Use this card only in Sandbox. Ask EFT Pay for the test scenarios and supported devices required for the other methods; the test card is not a universal Apple Pay, bank-transfer or QR test credential.

For your first test, add a test product to the cart, proceed to checkout, enter fictional billing details, choose Bank card and place the order. Complete the hosted payment using the sandbox card above, then inspect the matching order in WordPress admin.

Complete these checks before launch:

Check the order's status and EFT Pay Information together. With an outbound key, also check Last verified notification for real signed delivery. A successful connection test alone is not an end-to-end test. Confirm Action Scheduler runs reliably when the store has little visitor traffic.

Activate production payments

Obtain production merchant approval and production credentials before switching. Signing-key fields can be omitted; obtain the production keys if using notifications or if the tenant requires signed API requests. Do not reuse the sandbox configuration.

1. Under Payment environment, select Live. A new Live profile starts separately, with payment methods off; an existing profile retains its saved settings.
2. In Merchant connection, import your approved production JSON with "environment": "production". Enter the production EFT Pay username and password, then Save changes.
3. Test the connection and confirm the production wallet belongs to your merchant and is ACTIVE/ZAR.
4. Under Order updates, confirm Payment confirmation shows Status checks active or Configured and the public HTTPS store connection is ready. If using notifications, the displayed production notification URL differs from Sandbox.
5. Under Payment methods, enable Live checkout and select only the methods provisioned for your production merchant. Save the settings.
6. Click Activate live payments. The plugin validates the configuration and merchant wallet before switching. A failed activation leaves the previously active profile unchanged.
7. Confirm the header says Live active. A fresh checkout should no longer display a sandbox notice. Complete an agreed, controlled production acceptance test before opening payments to all customers.

Live payments charge real money. Selecting Live or clicking Save changes does not activate it; use the explicit Activate live payments action. Activation checks setup and wallet access, not delivery of a real notification or success on every payment method.

Existing orders retain their original environment. Keep both profiles and their original merchant credentials available while those orders need reconciliation. To switch new orders back to Sandbox, select Sandbox and click Switch to sandbox. Refresh checkout after a switch; a stale checkout must not silently use a different environment.

Review and reconcile orders

Open a WooCommerce order to view EFT Pay Information. The panel shows the original Sandbox/Live environment, verification status, checkout choice and received EFT Pay payment ID when available. Expand Payment details or Hosted checkout & attempts for further verified details and payment history.

The hosted checkout ID, outgoing payment attempt ID and received merchant payment ID identify different records. Receipt details can arrive later than payment confirmation. Missing optional receipt details do not automatically mean that a verified payment failed.

To refresh, select Check EFT Pay payment under Order actions and run the action. It checks the existing payment; it does not create a new payment or repeat fulfilment. Do not manually mark an order paid solely because the customer saw a success screen.

An uncertain or timed-out creation must be reconciled before trying again. Do not delete its payment records or create a replacement order to force another payment. Escalate review-held, mismatched or post-payment reversal results to EFT Pay before deciding how to fulfil or refund.

Troubleshooting

For help, use the support guide or the Scan to Pay help centre. Include the site URL, plugin/WordPress/WooCommerce/PHP versions, Sandbox or Live, order number, available payment IDs, amount, timestamp with timezone, the displayed EFT-… support reference and reproduction steps. Redact customer information and secrets from screenshots. Never share your configuration JSON, passwords, signing keys, full card number, CVV, PIN or private hosted/return links in a support ticket.

Maintain the installation

When an approved newer EFT Pay ZIP is supplied, upload it through WordPress to update. For an existing eft-pay installation, choose to replace its version. For a pre-0.12.0 installation, follow the folder-transition instructions under Install the plugin. Back up first and test the release on a staging store. Existing settings, order payment records and old callback routes remain supported; do not delete them during an update.

Exclude return URLs containing wc-api=eft_return and the /wp-json/eftpay/v1/order-status endpoint from page caches. Include WordPress's query-style equivalent, rest_route=/eftpay/v1/order-status, if your store uses it. Keep old return/status URLs excluded as well while existing orders use them. Earlier /notifications callback variants and original notification URLs remain supported in their original environments; new payments use the displayed /notify address when an outbound key is configured. Keep configured notifications reachable and monitor scheduled actions. Protect WordPress admin, backups and API credentials. Saved secrets are encrypted using WordPress authentication salts; changing those salts requires re-entering the secrets.

The implementation is ready when the approved methods are visible, hosted checkout works, authoritative checks confirm the matching order even with the browser closed, delayed results reconcile safely, and the correct environment is active. If using notifications, verify real signed delivery and duplicate handling too.

Support and temporary diagnostics

Docs and Support links appear in the Plugins list. Merchant connection includes
Setup guide and FAQ and Contact EFT Pay support. The EFT Pay section in
WooCommerce → Status shows configuration/readiness values without credentials or order
information. Review the complete WooCommerce report before sharing it; other sections can
contain store details.

Diagnostic logging is off by default. If support requests it, open
Merchant connection → Troubleshooting, select Enable diagnostic logging, save,
reproduce the issue once and inspect the eft-pay source in WooCommerce → Status → Logs.
Turn it off when the investigation finishes. Events contain bounded references and permitted
status/identifier fields, not raw errors, passwords, card attributes, request bodies or
notification headers. Share reviewed entries through the private support channel.

Customers receive friendly translated messages with random support references. If payment
creation is uncertain, the message asks them not to pay again. Keep the existing order and
payment history while the result is investigated.

Privacy and retained payment records

Full card details and CVV are entered on hosted checkout. To create and verify payment,
the plugin sends the order number/description, amount, currency, payment references,
settlement account, preferred payment option and private payment return address. It includes
the notification address only when an outbound signing key is configured.
The private return address provides access to that order. It authenticates server-to-server
using the merchant credentials for the original payment environment.

WordPress retains the order and a limited payment history. When supplied and verified,
private order details can include transaction references, amount/fee/dates, authorisation
code, last four card digits, holder label, card type/brand and card issuer identification
digits. Full card numbers, CVV, reusable saved-card tokens and raw provider responses are
not retained by the plugin. Existing hosted links are retained for safe order recovery.
Limit order-management access and apply your store's order, log and backup retention process.
The plugin does not automatically erase its financial records or set a fixed retention period.

You can adapt this paragraph for your store policy:

We use EFT Pay, provided by EFT Corporation, to process payments on secure hosted checkout.
Our store shares the order number, amount, currency, payment references, settlement account
and private payment return address with the payment service. A notification address
is also shared when configured. Card details and CVV
are entered on hosted checkout; the EFT Pay plugin does not collect or store them in
WordPress. We keep orders and limited verified payment information for fulfilment,
reconciliation and support. This can include transaction references, payment dates,
authorisation code, last four card digits, holder label and card type/brand/issuer
identification digits, available only to authorised staff. Our retention policies apply
to these records and backups. See EFT Corporation's privacy policy.

Your merchant agreement governs fees, settlement and payment processing. The
EFT Corporation terms are a service
reference; the plugin does not replace your agreement or determine your retention period.

Deactivation, deletion and updates

Deactivation stops the plugin's pending background checks but keeps settings and orders.
Return and notification handlers are unavailable while it is inactive. Resolve or arrange
monitoring for outstanding payments before retiring it.

Deleting the plugin through WordPress removes saved current/legacy merchant configuration,
credentials saved in those settings, notification summaries and connection status; it
attempts to clear its diagnostic log source when supported. Orders, payment history and
payment/receipt ownership records deliberately remain. Provider transactions, backups and
externally managed server credentials are unaffected. In the staff QA package, the shipped
and unconfigured update channels' observation, verification-history and cached-release
state is cleared separately. The directory package creates no external update-channel state.
Reinstallation requires the correct merchant setup
again and is not a way to retry an uncertain payment.

The staff QA candidate supports an EFT-hosted signed update channel; this updater and its QA configuration are excluded from the WordPress.org submission candidate, which uses native directory updates once approved and published. The following external-updater details apply only to the staff QA package. Its bundled channel is QA;
production hosting/signing/publication is still a separate pending release step. Do not
expect a general public update service until EFT Pay announces it. The updater requests a
public release description/package using a fixed client identifier; it appends no installed
software versions, store identifiers, merchant credentials or order data. The host sees the
server IP and ordinary HTTP request information. Compatibility is checked locally.

The interface is translation-ready under the eft-pay text domain. Actual language
availability depends on supplied translation files; this guide does not promise translations
that have not been provided. The private return page keeps its translated copy local and
loads no theme analytics or unrelated scripts.