WooCommerce plugin

Install and configure the EFT Pay WooCommerce plugin to accept payments through EFT Pay 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; your store does not collect card numbers or CVV. You do not need to build a payment API integration or run a separate payment service.

This guide applies to plugin version 0.11.7. The plugin supports one-time ZAR payments from R0.01 to R100,000.00, WooCommerce Classic Checkout, Checkout Blocks and High-Performance Order Storage (HPOS).

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.
• The outbound notification signing key and, if required for your tenant, the API request signing key.
• A working WordPress cron runner so WooCommerce Action Scheduler can perform backup payment checks.

Obtain the approved ZIP, merchant configuration and credentials from the EFT Pay team. Keep the JSON and credentials private; the JSON contains 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's internal folder remains scan-to-pay for upgrade compatibility. Its public name is EFT Pay. Keep that folder when installing an update; you do not need Node.js, Docker or the QA deployment helper on a merchant store.

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 (JSON).
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 the required notification setup and verifies API access to an ACTIVE ZAR wallet belonging to the configured merchant organisation. 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 merchant summary shows the saved identifiers.

Merchant configuration JSON

Your approved configuration uses this format:

{
  "schemaVersion": 1,
  "environment": "sandbox",
  "tenantId": "123456",
  "organisationId": "123457",
  "walletId": "123458",
  "webhookSigningKey": "REPLACE_WITH_APPROVED_OUTBOUND_KEY",
  "apiSigningKey": null
}

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

Ask EFT Pay or your authorised tenant administrator for the signing keys. A WordPress application password, API login password or randomly generated store secret is not a substitute. 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; signing keys must be nonempty strings of at most 1,024 bytes each, or null. Unsupported fields, versions or environments are rejected. Include both signing-key fields explicitly. 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; a conflicting import is rejected. Do not replace merchant identifiers while orders still need reconciliation.

Confirm notification setup

Open Order updates and review EFT Pay notifications. Notifications are always the primary confirmation method, with backup status checks for delayed results. There is no confirmation-mode selector.

1. Confirm Signing key shows Saved securely or that the key is server-managed.
2. Confirm HTTPS endpoint shows Configured.
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 when it creates each new hosted payment. You do not need to write a webhook handler. Typical callback paths are:

Sandbox: /wp-json/scantopay/v1/eclipse
Live:    /wp-json/scantopay/v1/eclipse/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 supports these individually configurable choices:

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. EFT Pay sends a signed notification to WordPress. The plugin verifies the signature, retrieves the authoritative payment and checks the order, merchant, wallet, amount and currency.
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 for the notification to update the order. A browser redirect, screenshot or unverified success message cannot mark an order paid. Notifications are supplemented by checks on customer return, the admin order action and scheduled recovery jobs.

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 Last verified notification, the order's status and EFT Pay Information together. 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, production credentials and production signing keys before switching. 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 the production signing key and public HTTPS endpoint are configured. 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, exact error and reproduction steps. Redact customer information and secrets from screenshots. Never share your configuration JSON, passwords, signing keys, full card number, CVV or PIN in a support ticket.

Maintain the installation

Update by uploading the approved newer EFT Pay ZIP and choosing to replace the existing version. Back up first and test the release on a staging store. Existing settings, order payment records and callback routes are retained; do not delete them during an update.

Exclude return URLs containing wc-api=stp_return and the /wp-json/scantopay/v1/order-status endpoint from page caches. Include WordPress's query-style equivalent, rest_route=/scantopay/v1/order-status, if your store uses it. Keep 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, a real signed notification confirms the matching order, duplicate and delayed results reconcile safely, and the correct environment is active.