VibeFox eWAY for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later with the cURL extension.

Currency: AUD, NZD, SGD, HKD or MYR. For other checkout currencies the payment method is hidden at checkout. The payment is taken in the order currency.

eWAY account: you need an eWAY merchant account with Rapid API access and its Rapid API key and password, from MyeWAY under Settings, API Key. For testing you need an eWAY sandbox account with its own key and password. Sandbox and live keys are different. Nothing needs to be set up in MyeWAY: the return URL is sent with every payment.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_eway_payment_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_eway_payment_gateway.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_eway_payment_gateway-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox eWAY Payment Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the page and click Activate (see License key).

4. Enter your sandbox API key and password, keep Sandbox Mode on, turn on Enable/Disable, click Save and place a test order.

5. Enter your live API key and password, turn off Sandbox Mode and click Save.

6. Optionally add the cron URL shown on the settings page to the cron jobs of your server (see Configuration).

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_eway_payment_gateway.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox eWAY Payment Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the eWAY keys and the cron URL as in steps 3 to 6 for OpenCart 3. The settings page and its fields are the same in both versions. Only the cron URL is different (see Re-check of lost returns (cron)).

A new install starts with the payment method turned off and sandbox mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox eWAY Payment Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings a badge shows the mode: SANDBOX — payments go to the eWAY sandbox, no real money is charged. or LIVE — real payments are taken with the live API key. The page warns you when the API key and password of the current mode are missing (the payment method is then not shown at checkout) and when the default currency of the store is not supported by eWAY. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must have 1 to 128 characters, Sort Order must be a whole number, Total a number not below zero, and the selected geo zone and order statuses must exist. Otherwise nothing is saved and the page shows what to correct.

eWAY

Enable/Disable: Enable eWAY Payment Gateway turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Credit Card (eWAY). Required, up to 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

Sort Order: the position of eWAY among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer eWAY only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before eWAY is offered. Leave it empty to offer eWAY for any total.

API credentials

The Rapid API key and password are in MyeWAY under Settings, API Key. eWAY has guides for live and sandbox keys, linked in this section. Sandbox and live use different keys. Sandbox mode uses only the sandbox credentials, live mode only the live credentials.

Sandbox Mode: payments go to the eWAY sandbox with the sandbox key and password. No real money is charged. Default: on. Turn it off to take live payments with the live key. While it is on, customers see Test mode: no real payment is taken. at the Confirm Order step.

Live API Key: the Rapid API key of your live eWAY account.

Live API Password: the Rapid API password of your live eWAY account.

Sandbox API Key: the Rapid API key of your eWAY sandbox (partner/developer) account.

Sandbox API Password: the Rapid API password of your eWAY sandbox account.

Saved keys and passwords are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. To remove a saved value, tick Clear the saved value on save under the field and click Save.

Return URL: shows the return address of the extension. It is sent to eWAY automatically with every payment, together with the order and a random key of the payment attempt, so nothing has to be set up in MyeWAY. The result of a payment is always read from eWAY server-to-server.

Re-check of lost returns (cron): an optional cron URL, shown under the return URL. Call it from a server cron job every 15 minutes, for example with curl. If a customer pays and closes the browser before coming back to the store, the payment is asked from eWAY about 60 minutes after the customer was sent to eWAY, and the order is updated. If eWAY cannot be reached, the check is repeated up to three times. Keep this URL private: it contains a secret token created on install, and a call with a wrong token is answered with Forbidden. On OpenCart 4 the URL looks like https://your-store/index.php?route=extension/wcp_eway_payment_gateway/payment/wcp_eway_payment_gateway.cron&token=(token).

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after eWAY has confirmed the payment. Each field below lists your OpenCart order statuses.

Order Status on Success: the status set once eWAY confirms the payment. Default: Processing.

eWAY payment on hold status: the status for an approved payment that needs your review: the amount or currency does not match the order, the payment was approved after the customer pressed Cancel on the eWAY page, or the order already had another status. A note in the order history explains why. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Refunded order status: the status after the payment was refunded in full from the order page. Default: Refunded.

Advanced

Debug log: writes API calls and payment results to eway_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to eway_p_debug.old.log.php. Card data, keys, passwords, customer e-mails and access codes are not logged. Errors are always logged. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete all extension data on uninstall: when on, uninstalling the extension removes the gateway settings and the log. The eWAY payment and refund records of orders are always kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. API keys and passwords are not exported.

Import: paste previously exported JSON and click Import to restore the settings. Saved API keys and passwords are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Credit Card (eWAY)). At the Confirm Order step the customer sees your description and the note You will be redirected to the secure eWAY payment page to pay by card. OpenCart creates the order at this step, still without a status. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. When the customer clicks Confirm Order, the extension asks eWAY for a payment page for the order total in the order currency, with OC- and the order number as invoice reference and the customer's payment address and e-mail, and sends the customer to the eWAY Responsive Shared Page. There the customer pays by card. The payment is captured immediately.

After paying, the customer returns to your store. The extension does not trust the browser: it asks eWAY server-to-server for the result of the payment page this order created. The order is marked paid only after eWAY confirms it and the approved amount and currency match the order. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success page. For an order on hold the page also shows Your payment was received and is being reviewed by the store. We will contact you if anything is needed.

If eWAY cannot be asked at that moment, a Payment confirmation page shows We have not received the confirmation of your payment from eWAY yet. If you completed the payment, this order will be updated shortly — please do not pay again. with a Check again button and a Back to checkout button. The order gets its status when the customer checks again or when the cron URL runs.

If the payment is declined, the customer is back at checkout with the reason, for example Your payment was declined: D4451 Insufficient funds. Please try again or use a different payment method. The order stays without a status. If the customer clicks Cancel on the eWAY page, the extension first checks with eWAY that nothing was paid (for example in another tab). The customer then sees You cancelled the payment on the eWAY page. Your order has not been paid — you can try again. If the payment was not completed, the message is The payment was not completed. Please try again. The cart is kept in every case. On OpenCart 4 these messages are shown above the checkout page.

A customer can try again. OpenCart 3 creates a new order every time the Confirm Order step is shown, OpenCart 4 updates the order of the checkout, so a new attempt opens a new eWAY payment page for the same order. Before a new payment page is created, the previous pages of this order and of other orders of the same cart are checked with eWAY. If one turns out to be paid already, that payment is confirmed instead of a second one. If eWAY cannot be asked about them, the customer sees We could not check the status of your previous payment attempt. Please try again in a moment. If eWAY cannot create the payment page, the customer stays at the Confirm Order step with a short message, for example Payment error: Unable to connect to eWAY. Please try again. or eWAY could not start the payment with the eWAY error codes.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed without a payment meanwhile (for example you cancelled it), the customer is sent back to the checkout with Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., and the next Confirm Order pays a new order of the cart. If that order is already paid but the cart has changed since, including a new quantity, the message is Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. A paid order is never shown as paid for a different cart.

The return and cron URLs also work while the store is in maintenance mode, because OpenCart 3 lets payment extension requests through and the extension adds a startup action for them on OpenCart 4.

eWAY does not send server-to-server notifications for the Shared Page: the result is taken when the customer returns and by the cron URL. The extension has no card fields on your site, no saved cards or subscriptions, no authorise-only and capture, and does not evaluate Beagle fraud scores (transactions blocked by eWAY fraud rules are declined by eWAY itself).

Orders and refunds

Order statuses

No status (missing order): the customer was sent to eWAY and has not paid, cancelled, the payment was declined, or the result could not be fetched yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status on Success (default Processing): the payment was approved. A note shows the eWAY transaction ID, the auth code, the response and the mode (sandbox or live).

eWAY payment on hold status (default Pending): eWAY approved a different amount or currency than the order (for example Approved for partial amount), the payment was approved after the customer had cancelled it on the eWAY page, or it was approved for an order that you had already given a status, for example Canceled. The amount eWAY actually took is recorded, and the note explains it. Check the order and fulfil it or refund the payment.

Refunded order status (default Refunded): the payment was fully refunded through the extension.

If a second payment is approved for an order that is already paid, or for another order of the same cart, the paid order is not changed. A note asks you to refund the duplicate in MyeWAY. An approved payment for another invoice reference is never applied to the order.

Notes are entries in the order History that the customer does not see.

VibeFox eWAY Payment Gateway tab

In Sales > Orders open an order paid with eWAY. At the bottom of the order page, next to History and Additional, the VibeFox eWAY Payment Gateway tab shows the eWAY transaction ID with a Sandbox or Live label, the Auth code, the eWAY Response, the Invoice reference, the payment Status, the amounts Paid / refunded, the refund form, the refund history and the eWAY notes of the order. The tab is shown to users who have access to the extension.

Refunds

In the tab enter the amount (the amount not refunded yet is filled in), optionally a Reason (optional), and click Refund via eWAY. Confirm the question Refund this amount through eWAY? This cannot be undone. Full and partial refunds are supported. You need the right to modify the extension (set in System > Users > User Groups). Refunds are made in the amount and currency eWAY charged, so after an approval for a partial amount you can refund up to what the customer actually paid, not the order total. The refund is sent in the environment the payment was made in (sandbox or live), so that environment's API key and password must be set. If eWAY declines the refund, the tab shows eWAY refund failed: with the eWAY codes and no refund is recorded. A successful refund is added to the refund history and the notes with the eWAY refund transaction ID. A full refund sets the order to Refunded order status without notifying the customer and without returning products to stock, like a manual status change. A partial refund does not change the status. Refunds are available once eWAY has approved the payment.

Product returns in Sales > Returns do not send money back through eWAY. Refunds made in MyeWAY are not synced back to OpenCart. Update the order manually if needed.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox eWAY Payment Gateway is the first block on Extensions > Extensions > Payments > VibeFox eWAY Payment Gateway > Edit, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: opencart-payment-eway and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, eWAY is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension always removes the license key and license status.

Troubleshooting

eWAY does not appear at checkout: check that the license is active, Enable/Disable is on, the API key and password of the current mode are set (sandbox fields in sandbox mode, live fields in live mode) and the checkout currency is AUD, NZD, SGD, HKD or MYR. The settings page shows a warning when the credentials are missing. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status: the customer did not return from eWAY, or eWAY could not be asked at that moment. eWAY sends no notifications for the Shared Page. Set up the cron URL from Re-check of lost returns (cron): it picks up the payment about an hour later. Check the transaction in MyeWAY and look at the Log field on the extension page.

The cron URL answers Forbidden: the token in the URL is wrong. Copy the URL exactly as the settings page shows it.

The customer sees This payment method is temporarily unavailable: the API key and password of the current mode are missing, or eWAY refused them. Check the credentials of the current mode.

The customer sees eWAY could not start the payment: eWAY returned error codes, shown in the message. Often the billing details are invalid.

The customer sees eWAY cannot take payments in a currency: the order currency is not one eWAY takes. Use AUD, NZD, SGD, HKD or MYR.

The customer sees We could not match this payment to an order: the return link does not belong to an order of this store, or eWAY approved a payment for another invoice reference. If the customer was charged, find the payment in MyeWAY.

The customer sees This payment method is not available: the checkout session no longer matches the order, or the payment method was turned off meanwhile. The customer reloads the checkout.

Order is in the on hold status after payment: read the eWAY notes in the VibeFox eWAY Payment Gateway tab (see Order statuses), then fulfil the order or refund the payment.

No refund form in the tab: the tab says why: no eWAY transaction ID was found for the order, it is fully refunded, your user group has no right to modify the extension, or the API credentials of the payment's mode are not set.

Refund fails with a message about the sandbox or live mode: the order was paid in that environment, and its API key and password are not set. Enter them and try again.

Refund fails with at most … can be refunded: the amount is more than eWAY charged minus the refunds already made.

For developers, the extension triggers the OpenCart events wcp_eway_payment_gateway_supported_currencies (if your eWAY account is enabled for more currencies) and wcp_eway_payment_gateway_create_access_code_request (the request body before the payment page is created).

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox eWAY Payment Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the return and cron URLs through in maintenance mode). If Delete all plugin data on uninstall is on, the other gateway settings (title, description, sandbox mode, API keys and passwords, debug log switch, cron token) and the log are removed. If it is off, they are kept for a later re-install. The eWAY payment and refund records are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox eWAY Payment Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

eWAY is a trademark of its respective owner. This extension is not affiliated with or endorsed by eWAY.