VibeFox eWAY for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Shop currency: AUD, NZD, SGD, HKD or MYR. For other cart currencies the payment method is hidden at checkout. The payment is taken in the cart 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 eWAY: the return URL is sent with every payment.

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

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox eWAY Payment Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure 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 Configure page to the cron jobs of your server (see Configuration).

On install the module creates the order status eWAY payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox eWAY Payment Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields 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 shop is not supported by eWAY.

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.

Description: the text shown under the payment method at checkout. Default: Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

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: 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. under the payment method.

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.

Clear saved credentials: tick a key or password and click Save to remove it. An empty field keeps the saved value.

Return URL / re-checks: no webhook or return URL has to be configured in eWAY, because the return URL is sent with every payment. This field shows an optional cron URL. Call it from a server cron job, for example every 15 minutes. If a customer pays and closes the browser before coming back to the shop, the payment is asked from eWAY about an hour later and the order is created. If eWAY cannot be reached, the check is repeated up to three times. Keep this URL secret: it contains a token, and a call with a wrong token is answered with Forbidden.

Orders

Order Status on Success: the order status once eWAY confirms the payment.

An approved amount or currency that does not match the order always goes to eWAY payment on hold.

Advanced

Debug log: writes API calls and payment results to logs/eway_p_debug.log.php in the module folder. The file cannot be opened from the web. 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 plugin data on uninstall: when on, uninstalling the module removes the gateway settings and the log. The eWAY payment data of orders and the order status eWAY payment on hold always stay. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Credit Card (eWAY)) and confirms. The module asks eWAY for a payment page for the cart total in the cart currency, with PS- and the cart number as invoice reference and the customer's billing 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. No order exists yet at this point.

After paying, the customer returns to your shop. The module does not trust the browser: it asks eWAY server-to-server for the result of the payment page this cart created. The order is marked paid only after eWAY confirms it and the approved amount and currency match the cart. The order is then created and the customer sees the standard order confirmation page with Your payment with eWAY has been received. For an order on hold the page 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 is created 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. If the customer clicks Cancel on the eWAY page, the module 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.

A customer can try again. Before a new payment page is created, the previous page of the cart is checked with eWAY. If it turns out to be paid already, the order is created instead of a second payment. If eWAY cannot create the payment page, the customer stays at checkout 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.

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 module 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 order yet: the customer was sent to eWAY and has not paid, cancelled, the payment was declined, or the result could not be fetched yet. Only the cart exists.

Payment accepted or Delivered: the payment was approved. The status follows Order Status on Success. The payment is recorded with the eWAY transaction ID, and a note shows the transaction ID, the auth code, the response and the mode (sandbox or live).

eWAY payment on hold: eWAY approved a different amount or currency than the cart (for example Approved for partial amount, or the cart was changed after the customer opened the payment page), the payment was approved after the customer had cancelled it on the eWAY page, or it was approved after the order had been cancelled. The payment is recorded with the amount eWAY took, and the note explains it. Check the order and fulfil it or refund the payment.

Refunded: the payment was fully refunded through the module.

If a second payment is approved for a cart that is already paid, the 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.

eWAY payment block

The order page shows an eWAY payment block with the transaction ID, the auth code, the eWAY response, the status, the mode and invoice reference, the amount paid and refunded, a Sandbox badge for sandbox payments, the refund history and the eWAY notes of the order.

Refunds

In the eWAY payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, 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 edit orders; access to the Modules pages is not needed. 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 block 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. A partial refund does not change the status. Refunds are available once eWAY has approved the payment.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through eWAY. Refunds made in MyeWAY are not synced back to PrestaShop. Update the order manually if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox eWAY Payment Gateway is the first block on Modules > Module Manager > VibeFox eWAY Payment Gateway > Configure, 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 shop. Below them are the line Product: presta-payment-eway and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module 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 cart currency is AUD, NZD, SGD, HKD or MYR. The settings page shows a warning when the credentials are missing. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created: 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 Return URL / re-checks: it picks up the payment about an hour later. Check the transaction in MyeWAY and look at the Log field on the module page.

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 We could not match this payment to an order: the return link does not belong to a cart of this shop, or eWAY approved a payment for another invoice reference. If the customer was charged, find the payment in MyeWAY.

The customer sees We could not check the status of your previous payment attempt: another request was processing the same cart. The customer can try again in a moment.

Order is eWAY payment on hold after payment: read the eWAY notes in the eWAY payment block (see Order statuses), then fulfil the order or refund the payment.

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 module README lists the hook actionWcpEwaySupportedCurrencies, if your eWAY account is enabled for more currencies.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox eWAY Payment Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete all plugin data on uninstall is on, the gateway settings and the log are removed. If it is off, all settings are kept for a later re-install. The eWAY payment data of orders and the order status eWAY payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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