Skip to main content

eWAY Rapid Payment

eWAY Rapid is a popular payment gateway for businesses in Australia, New Zealand, and the United Kingdom. This plugin connects your J2Commerce store to the eWAY Rapid 3.1 API so customers can pay by credit or debit card at checkout.

You can choose between a fully hosted payment page (recommended for simplicity and lowest PCI scope) or an on-site card form that submits directly to eWAY. Both modes use the same API credentials and support sandbox testing before you go live.

Add-on required

The eWAY Rapid plugin is a separate add-on available from the J2Commerce Extensions Store. It is not included with the core J2Commerce component.

Requirements​

Before installing, confirm that your environment meets these requirements:

  • J2Commerce 6 installed and active on your Joomla site
  • An active eWAY merchant account (Australia, New Zealand, or United Kingdom)
  • HTTPS enabled on your site — eWAY rejects callback URLs that are not TLS-secured
  • Your server must be able to make outbound HTTPS connections to api.ewaypayments.com (live) or api.sandbox.ewaypayments.com (sandbox)

Getting Your API Credentials​

eWAY issues a separate API Key and API Password for each merchant account. These are different from your MYeWAY login credentials.

  1. Log in to your eWAY merchant portal at my.eway.io.
  2. Go to My Account -> API Key.
  3. Copy the API Key value — it looks like a long alphanumeric string.
  4. Copy the API Password associated with that key.
  5. Keep both values handy. You will paste them into the plugin settings.

For sandbox testing, eWAY provides a separate sandbox merchant account with its own API Key and Password. Log in to sandbox.myeway.io to generate sandbox credentials.

Installation​

The eWAY Rapid plugin is not included with J2Commerce. Purchase and install it as a separate add-on.

  1. Purchase the plugin from the J2Commerce Extensions Store and download the zip file.
  2. In your Joomla admin, go to System -> Install -> Extensions.
  3. Upload the payment_ewayrapid.zip file using the drag-and-drop area or the Browse for file button.
  4. The plugin installs and enables itself automatically.

After installation, navigate to J2Commerce -> Payments -> Payment Methods to confirm the plugin appears in the list. If it shows as disabled, click the toggle in the Enabled column to enable it.

Configuration​

tip

Click the Toggle Inline Help button in the toolbar and the app will show a description below each field as you configure it.

Go to J2Commerce -> Payments -> Payment Methods and click eWAY Rapid (or the edit icon next to it) to open the settings.

Display Settings​

FieldDescriptionRecommended
Display NameThe label shown to customers at checkoutCredit / Debit Card or eWAY
Display ImageOptional logo shown next to the payment nameUpload an eWAY or card logo

Credentials​

FieldDescription
API KeyYour eWAY Rapid API Key from MYeWAY (My Account > API Key)
API PasswordThe API Password paired with your API Key

Paste your credentials exactly as they appear in MYeWAY. The password field is masked for security.

Sandbox Mode​

FieldOptionsDescription
Use SandboxYes / NoWhen set to Yes, all transactions are sent to api.sandbox.ewaypayments.com instead of the live gateway. Set to No for a production store.

Always enable sandbox mode first to test your setup before accepting real payments.

Integration Method​

FieldOptions
Integration MethodShared Page (hosted) / Transparent Redirect (on-site form)

This is the most important choice in the plugin. See Choosing an Integration Method below for a full explanation. The default is Shared Page (hosted).

Transaction Mode​

FieldOptionsDescription
Transaction ModeSale / AuthorisationSale captures funds immediately when the customer pays. Authorisation places a hold on the funds and requires you to manually capture the payment later in MYeWAY.

Most stores use Sale. Use Authorisation only if you need to review orders before charging the card (for example, made-to-order goods).

Payment Button​

FieldDescriptionDefault
Payment Button TextText shown on the checkout buttonPlace Order

Order Statuses​

These settings control which J2Commerce order status is applied based on the payment result.

FieldDescriptionDefault Status
Paid Order StatusApplied when eWAY confirms the payment was approvedConfirmed (1)
Pending Order StatusApplied when the payment is accepted but awaiting final settlementPending (4)
Failed Order StatusApplied when eWAY declines or rejects the paymentFailed (3)

The defaults match the standard J2Commerce order status IDs. Only change these if you have renamed or reordered your statuses.

info

NOTE: If the status you want isn't listed in the dropdown menu, you can create a new one by going to J2Commerce -> Setup -> Order Statuses

Surcharge (Optional)​

You can add a fee to orders paid with eWAY. Leave all three fields blank if you do not want to charge a surcharge.

FieldDescriptionExample
Surcharge NameLabel shown to the customer on the order summaryCredit Card Fee
Surcharge PercentAdditional percentage of the order subtotal1.5
Surcharge FixedFlat fee added on top of any percentage0.30
Surcharge Tax ClassTax profile applied to the surcharge amountSelect a tax profile or leave blank

If both a percentage and a fixed amount are entered, both are applied (for example, 1.5% + $0.30).

Availability Restrictions (Optional)​

Use these settings to limit when eWAY appears as a payment option.

FieldDescription
Geozone RestrictionOnly show eWAY to customers in the selected geozone. Leave blank to show to everyone.
Min SubtotalHide eWAY if the cart subtotal is below this amount. Leave blank for no minimum.
Max SubtotalHide eWAY if the cart subtotal is above this amount. Leave blank for no maximum.

Thank-You Article​

FieldDescription
Thank-You ArticleSelect a Joomla article to display on the order confirmation page after a successful payment. Useful for instructions, voucher codes, or next-step information.

Display Text​

These optional text areas let you show custom messages to the customer at different points in the checkout. Leave them blank to use the plugin's default messages.

FieldWhen it is shown
On SelectionWhen the customer selects eWAY as their payment method
Before PaymentOn the payment screen, before the card form or redirect button
After PaymentOn the confirmation page after a successful payment
On ErrorDisplayed alongside any payment error message
On CancelWhen the customer cancels on the eWAY hosted page

Dashboard Icon​

FieldDescriptionDefault
Show Dashboard IconDisplay a shortcut icon on the J2Commerce admin dashboardNo
Dashboard Icon LabelLabel for the shortcut (visible only when the icon is enabled)

Debug Logging​

FieldDescriptionDefault
Debug LoggingWrite gateway activity to the Joomla log file payment_ewayrapid.phpNo

Enable debug logging only while troubleshooting. The log records request and response activity but never stores card numbers or security codes.

Choosing an Integration Method​

The Integration Method setting determines how card details are collected at checkout. The choice affects both your customer experience and your PCI compliance obligations.

Shared Page (Hosted) — Recommended​

When a customer clicks Place Order, they are redirected to a payment page hosted by eWAY. They enter their card details there and are then returned to your site with the payment result.

Advantages:

  • Card data never reaches your server — eWAY handles it entirely
  • Lowest PCI scope (SAQ-A)
  • eWAY's hosted page is maintained and updated by eWAY

Best for: Most stores, especially those without a dedicated payment security programme.

Transparent Redirect (On-Site Form)​

The card form appears directly on your checkout page. When the customer submits, the card details are posted straight from their browser to eWAY — they do not pass through your server.

Advantages:

  • Customers stay on your site throughout the checkout
  • More control over the visual design of the card form

Considerations:

  • Your checkout page must be served over HTTPS at all times
  • PCI scope is still SAQ-A because card data does not hit your server, but your checkout page is in scope for regular security reviews

Best for: Stores where brand consistency and a seamless checkout experience are a priority.

Testing in Sandbox Mode​

eWAY provides a sandbox environment at api.sandbox.ewaypayments.com that accepts test transactions without charging real cards.

Setting Up Sandbox Testing​

  1. Create a sandbox merchant account at sandbox.myeway.io if you do not already have one.
  2. Generate sandbox API credentials from the sandbox MYeWAY portal (My Account > API Key).
  3. In the eWAY Rapid plugin settings, set Use Sandbox to Yes and enter your sandbox API Key and Password.
  4. Save the settings.

Running a Test Transaction​

  1. Add a product to the cart on your store's frontend.
  2. Proceed through checkout and select eWAY (or your configured display name) as the payment method.
  3. Use a test card number from eWAY's published sandbox test card documentation (available in the eWAY developer portal under "Test Card Numbers").
  4. Complete the payment and verify that the order status in J2Commerce matches your Paid Order Status setting.

What to Check​

  • The order appears in J2Commerce -> Sales -> Orders with the correct status
  • The order history note includes the eWAY transaction ID
  • Cancelling on the hosted page (Shared Page mode) returns the customer to your site and applies the cancellation message
  • Attempting a declined card number sets the order to your Failed Order Status

Going Live​

When you are satisfied with sandbox testing, switch to the live gateway:

  1. Log in to your live MYeWAY account and retrieve your live API Key and Password.
  2. In the eWAY Rapid plugin settings, set Use Sandbox to No.
  3. Replace the API Key and API Password with your live credentials.
  4. Save the settings.
  5. Place a real test order with a small amount to confirm end-to-end.
Before going live

Double-check that Use Sandbox is No and that you have entered your live credentials (not the sandbox ones). Sandbox and live credentials are different — entering sandbox credentials with the sandbox toggle off will cause authentication errors on every transaction.

What Changed From the J2Store Version​

If you previously used the eWAY Rapid plugin for J2Store v4, here is what has changed in the J2Commerce 6 version:

  • Native Joomla 6 MVC architecture — the plugin uses Joomla's event system and dependency injection instead of the older FOF 2 framework.
  • Native Joomla HTTP client — outbound API calls to eWAY now use Joomla's built-in HTTP transport (HttpFactory) instead of a bundled cURL library. This eliminates a source of cURL version incompatibilities.
  • No jQuery — all frontend JavaScript is vanilla ES6 with no jQuery dependency.
  • Hardened transaction logging — the debug log records gateway activity only. Card numbers, CVV codes, and other sensitive card data are never written to any log file.
  • Amount verification on return — when a customer returns from the eWAY hosted page, the plugin compares the amount reported by eWAY against the actual order total. A mismatch prevents the order from being confirmed. This guards against replay attacks where a valid token from a different transaction might otherwise be reused.
  • Idempotent status updates — if the confirmation page is refreshed after a successful payment, the plugin detects the order is already confirmed and does not trigger a second status update or notification email.

Troubleshooting​

"API Key and Password are not configured" error at checkout​

Cause: The API Key or API Password field is empty in the plugin settings.

Solution:

  1. Go to J2Commerce -> Payments -> Payment Methods and open the eWAY Rapid settings.
  2. Confirm both the API Key and API Password fields are filled in.
  3. If you are testing, check that you have entered your sandbox credentials and that Use Sandbox is set to Yes.
  4. Save and retry.

eWAY does not appear at checkout​

The payment method is hidden when one or more of the following conditions apply:

  • Geozone restriction: The customer's billing address is not in the selected geozone. To confirm this is the cause, temporarily clear the Geozone Restriction field and test again.
  • Subtotal below minimum: The cart subtotal is less than the Min Subtotal value.
  • Subtotal above maximum: The cart subtotal exceeds the Max Subtotal value.
  • Plugin disabled: Go to System -> Manage -> Extensions, search for payment_ewayrapid, and confirm it is enabled.

Orders stay in Pending status after payment​

Cause: eWAY returned a pending settlement response code rather than a final approval. This can happen with certain bank transfers or delayed processing scenarios.

What to do:

  1. Log in to MYeWAY and check the transaction status.
  2. Once eWAY settles the transaction, manually update the order status in J2Commerce -> Sales -> Orders to your confirmed status.
  3. If pending orders happen regularly, consider enabling Debug Logging, reproducing the issue, and checking the payment_ewayrapid.php log file in the Joomla logs directory for the exact response codes eWAY returned.

"Authentication failed (HTTP 401)" in the Joomla log​

Cause: The API Key or Password does not match the eWAY account, or you are using sandbox credentials with the live gateway (or vice versa).

Solution:

  1. Verify the Use Sandbox toggle matches the type of credentials you entered.
  2. Re-copy the credentials from MYeWAY — avoid trailing spaces.
  3. Confirm your eWAY account is active and the API key has not been regenerated since you last saved the plugin settings.

"The payment amount did not match the order total" error​

Cause: The amount returned by eWAY differs from the order total stored in J2Commerce by more than one cent. This is a security check that prevents malformed or replayed responses from being accepted.

What to do:

  1. Check whether there are any currency rounding issues in your store configuration.
  2. If the issue is consistent, enable Debug Logging and check the log for the expected and returned values to identify the discrepancy.