VibeFox eWAY for Adobe Commerce — 도움말

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4.

Currency: AUD, NZD, SGD, HKD or MYR. The payment is taken in the currency of the order, the currency the customer sees in the cart. For other currencies the payment method is hidden at checkout. If your base currency is different, the display currency and its exchange rate must be set up in Magento.

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.

Magento cron: the Magento cron should run. It picks up payments of customers who paid but did not come back to the store.

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

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-eway-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/EwayPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_EwayPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open eWAY Payment Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter your sandbox API key and password, keep Sandbox Mode at Yes, set Enable to Yes, click Save Config and place a test order in a supported currency. When you are ready, enter the live API key and password, set Sandbox Mode to No and click Save Config.

The module adds the Credit Card (eWAY) payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates three tables for the eWAY payment attempts, their events and refunds. No webhook or return URL has to be configured in eWAY.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > eWAY Payment Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: eWAY title is required and must not exceed 128 characters. for an empty title or one longer than 128 characters, Sort order must be a whole number., and Order total must be a number, 0 or greater. for Minimum Order Total and Maximum Order Total. Amounts use a point as the decimal separator, for example 9.99.

While Enable is Yes, Magento shows after saving eWAY: enter the API key and password of the selected environment. when the key or password of the current mode is missing (the payment method is then hidden at checkout), and eWAY: SANDBOX mode; no real payments. in sandbox mode. A row at the end of the group reminds you: eWAY Shared Page has no webhook. Results are verified through the eWAY API on return and by Magento cron after 60 minutes. Supported currencies: AUD, NZD, SGD, HKD, MYR. SANDBOX credentials and LIVE credentials are separate.

General

Enable: shows or hides eWAY at checkout. It is shown only when the API key and password of the current mode are set. Default: No.

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

Description: shown in the payment method list at checkout, under the method when the customer selects it. Default: Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

Sandbox Mode: sends new payments to the eWAY sandbox with the sandbox key and password. No real money is charged. Default: Yes. Set it to No to take live payments with the live key. While it is on, customers see TEST MODE — no real money is charged. under the payment method.

API credentials

The Rapid API key and password are in MyeWAY under Settings, API Key. Sandbox and live use different keys.

Sandbox API Key: the Rapid API key of your eWAY sandbox account.

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

Live API Key: the Rapid API key of your live eWAY account. Used when Sandbox Mode is No.

Live API Password: the Rapid API password of your live eWAY account. Used when Sandbox Mode is No.

Magento stores the keys and passwords encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved value, type a new value to change it. Spaces at the start and end are removed. To delete a saved value, clear the field and click Save Config.

A payment is always checked and refunded with the key and password of the mode it was made in. A payment started in sandbox mode is still checked with the sandbox key after you switch to live.

Orders

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

An approved amount or currency that does not match the order never invoices the order; it goes On Hold (see Orders and refunds).

Conditions

Payment from Applicable Countries: All Allowed Countries offers eWAY for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer eWAY only for billing addresses in these countries.

Minimum Order Total: offer eWAY only from this order total, in the base currency of your store. 0 or empty means no minimum. Default: 0.

Maximum Order Total: offer eWAY only up to this order total, in the base currency. 0 or empty means no maximum. Default: 0.

Sort Order: the position among the payment methods at checkout. A whole number.

Advanced

Debug Log: writes the eWAY API calls (payment pages, refunds) and their responses to var/log/eway_p_debug.log.php in the Magento folder. The file cannot be opened from the web; at 5 MB it is rotated. API keys, passwords, return tokens and customer e-mails are not logged. Errors are always logged, also when it is off. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The eWAY payment data of orders always stays. Default: No.

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

Checkout

At the payment step the customer chooses the payment method (by default Credit Card (eWAY)) and sees the description and the note You will be redirected to the eWAY payment page. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet.

The module then asks eWAY for a payment page for the order total in the order currency, with MG- and the order 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.

After paying, the customer returns to your store. The module does not trust the browser: it asks eWAY server-to-server for the result of the payment page of this order. The order is marked paid only after eWAY confirms it and the approved amount and currency match the order. Magento then creates the invoice with the eWAY transaction ID as the transaction ID, the order gets the status of Order Status on Success and the order e-mail is sent. The customer sees the standard order success page. A customer who comes back in another browser lands on the home page.

If eWAY cannot be asked at that moment, the customer sees Your payment is being confirmed. Please check again. with a Check again link. The order is confirmed when the customer checks again or by the Magento cron. If the payment needs a manual check (see Orders and refunds), the customer sees eWAY payment needs manual review. Please contact the store.

If the payment is declined, or the customer clicks Cancel on the eWAY page and eWAY confirms that nothing was paid, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with The eWAY payment was not completed. Please try again., followed by the eWAY reason for a declined payment, for example D4451 Insufficient Funds. The customer can pay again or choose another payment method.

If eWAY cannot create the payment page, the order is cancelled, the cart is restored and the customer sees eWAY could not start the payment. Please try again or choose another payment method. Before a new payment page is created for the same cart, the earlier pages of the cart are checked with eWAY. If one of them turns out to be paid, no second payment is started.

eWAY does not send server-to-server notifications for the Shared Page. If a customer pays and closes the browser, the Magento cron asks eWAY about the payment from 60 minutes after it was started, every 15 minutes, up to three times, and confirms the order.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). If eWAY later reports a payment for a cancelled order, the order is not invoiced: it stays Canceled and a note asks for a manual review.

The module works with the standard Magento checkout. It 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). eWAY is not offered for orders created in the Admin or for checkout with multiple addresses.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to eWAY, but the payment is not confirmed yet. There is no invoice.

Processing or Complete: eWAY approved the payment. The status follows Order Status on Success. The invoice is created with the eWAY transaction ID, and a note shows the transaction ID, the auth code, the response code and the mode (sandbox or live).

On Hold: eWAY approved a different amount or currency than the order (for example an approval for a partial amount, or the order total was changed), or the payment was approved after the order had changed. No invoice is created. The note says that the eWAY transaction needs manual review and why. Check the order and the transaction in MyeWAY, then fulfil the order or refund the payment in MyeWAY.

Canceled: the payment was declined or cancelled, the payment page could not be created, or the order was cancelled in Magento. A payment approved later for a cancelled order adds a note and leaves the order Canceled.

Closed: the payment was fully refunded with a credit memo.

If a second payment is approved for an order or a cart that is already paid, nothing is invoiced again. A note asks you to refund the duplicate through the gateway (in MyeWAY). The notes are order comments that the customer does not see.

eWAY payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title, the eWAY Transaction ID and the eWAY mode. The Information tab also shows the eWAY payment history: every payment attempt with its reference, environment, status, transaction, expected amount and reported amount, and the refunds made through eWAY with their transaction IDs. It is shown also when the module is disabled. The customer sees only the payment method title.

Refunds

Open the Invoices tab of the order, open the invoice and click Credit Memo. Choose the items and amounts and click Refund. The refund is sent to eWAY at once, in the order currency and in the mode the payment was made in (sandbox or live), so that mode's API key and password must be set. Full and partial refunds are supported, up to the amount eWAY actually charged minus the refunds already made. A full refund closes the order (Closed). A credit memo created from the order page offers only Refund Offline, which records the refund in Magento without sending money back.

If eWAY declines the refund, Magento shows eWAY refund was declined: with the eWAY codes and the credit memo is not created. If the answer of eWAY is unclear, for example after a timeout, Magento shows eWAY refund response is uncertain. Check the gateway before retrying.; the module does not send that refund again, and later online refunds of this payment show An eWAY refund result is uncertain. Check the gateway before retrying. Check the refund in MyeWAY and record it with Refund Offline.

Refunds made in MyeWAY are not synced back to Magento. Record them with a credit memo and Refund Offline.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — eWAY Payment Gateway is the first row of the eWAY Payment Gateway group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-eway and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 order is cancelled, the cart is restored and the customer sees eWAY could not start the payment. Please try again or choose another payment method. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

eWAY does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the API key and password of the current mode are set (the sandbox fields in sandbox mode, the live fields in live mode). Check that the currency of the cart is AUD, NZD, SGD, HKD or MYR and the order total is above zero. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: the customer did not return from eWAY, or eWAY could not be asked at that moment. eWAY sends no notifications for the Shared Page. Check that the Magento cron runs: it picks up the payment from 60 minutes after it was started. Check that the API key and password of the mode the payment was made in are still set. Check the transaction in MyeWAY and look at the Log field of the settings.

The customer sees eWAY could not start the payment: eWAY could not create the payment page (often invalid billing details or wrong API credentials), the currency is not supported, the module was disabled or the license is not active. The order of that attempt is cancelled. Look at the Log field.

The customer sees This cart has already been paid.: an earlier payment page of the same cart was paid. The customer is sent to the home page; the paid order is in the Admin.

The customer sees Invalid eWAY return: the return link does not belong to an order of this store. If the customer was charged, find the payment in MyeWAY.

The customer sees eWAY is busy. Please try again.: another request was processing the same cart at the same moment. The customer can try again in a moment.

The order is On Hold after payment: read the order notes (see Order statuses), check the transaction in MyeWAY, then fulfil the order or refund the payment.

Refund fails with eWAY credentials for this payment environment are not configured.: the order was paid in sandbox or live mode, and the API key and password of that mode are not set. Enter them and try again.

Refund fails with Refund exceeds the captured eWAY amount.: the amount is more than eWAY charged minus the refunds already made.

There is no Refund button on the credit memo: create the credit memo from the invoice, not from the order page. Orders without an invoice (for example On Hold) cannot be refunded online; refund them in MyeWAY.

For developers: the supported currencies can be extended with the Magento event eway_p_supported_currencies (transport currencies), if your eWAY account is enabled for more currencies, and the payment page request can be changed with eway_p_create_access_code_request (transport body and the order). The amount, currency, reference and return URLs cannot be changed.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_EwayPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_EwayPayment to remove the data, then bin/magento module:disable Vibefox_EwayPayment, delete the folder app/code/Vibefox/EwayPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The eWAY payment attempts, events and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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