VibeFox EveryPay 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.

EveryPay account: you need the API username, the API secret and the processing account name of your e-shop. They are shown in the EveryPay Merchant Portal, in the e-shop settings. The demo portal (test mode) and the live portal have separate credentials. The payment methods the customer can use (cards, Apple Pay, Google Pay, bank links) are the ones enabled for your EveryPay account.

Currency: one processing account charges one currency. The account name starts with its currency code, for example EUR3D1 charges euros. EveryPay is offered only when the customer pays in that currency.

Public website: the callback URL of your store must be reachable from the internet, not blocked by basic authentication or a firewall.

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_everypay_payment-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_everypay_payment.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_everypay_payment-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 EveryPay Payment 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 the test API username, the test API secret and the processing account name from the demo portal. Copy the Callback notification URL into the Merchant Portal (see Configuration).

5. Turn on Enable/Disable and click Save. Place a test order in test mode, then enter the live credentials and turn off Test Mode.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_everypay_payment.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 EveryPay Payment, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the EveryPay credentials and the callback as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the callback URL is different (see Payment notifications (callback)).

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

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox EveryPay Payment > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page shows Test mode is on: payments go to the EveryPay demo environment, no real money is charged. while test mode is on. It warns you when the payment method is enabled but the API username, API secret or processing account of the current mode is missing (the payment method is then hidden at checkout), and when the currency of the processing account differs from the default currency of your store. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must be at most 128 characters, Sort Order must be a whole number, Total a number not below zero, and the geo zone and order statuses must exist. Otherwise an error names the field and nothing is saved. Spaces and line breaks in the usernames, secrets and account name are removed.

EveryPay

Enable/Disable: Enable EveryPay 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. Up to 128 characters; if left empty, customers see EveryPay. Default: EveryPay.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay securely by card or bank link on the EveryPay payment page.

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

Geo Zone: offer EveryPay 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 EveryPay is offered. Leave it empty to offer EveryPay for any total.

EveryPay account

The API username, API secret and processing account name are shown in the EveryPay Merchant Portal (e-shop settings): the demo portal for test mode, the live portal for live payments (the section links to both). Test and live environments have separate credentials.

Test Mode: payments go to the EveryPay demo environment with the test credentials; no real money is charged. Default: on. Turn it off to take real payments with the live credentials. While it is on, customers see TEST MODE: EveryPay demo environment, no real money is charged. at the Confirm Order step.

Test API Username: the API username of the demo environment.

Test API Secret: the API secret of the demo environment.

Live API Username: the API username of the live environment.

Live API Secret: the API secret of the live environment.

Processing Account Name: your EveryPay processing account, for example EUR3D1. The account defines the charged currency: the payment method is offered only for orders in that currency.

Saved API secrets 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 secret, tick Clear the saved API secret on save under the field and click Save.

Payment notifications (callback)

The callback tells your store that a payment has been finalised, so orders are confirmed even if the customer closes the browser. Copy the URL shown in Callback notification URL into the Callback notification URL of your e-shop in the EveryPay Merchant Portal, in the demo portal and in the live portal. On OpenCart 3 the URL looks like https://your-store/index.php?route=extension/payment/wcp_everypay_payment/callback, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_everypay_payment/payment/wcp_everypay_payment.callback. It is built from the storefront address of your OpenCart installation. Copy the URL exactly as the settings show it.

The callback carries only the payment references. The extension never trusts it by itself: it asks the EveryPay API for the payment status with the credentials of the mode the payment was made in. A callback for a payment that this store did not create is rejected without any request to EveryPay. The callback also works while the store is in maintenance mode, because OpenCart 3 lets payment extension requests through and the extension adds a startup action for it on OpenCart 4 (also for the customer's return). Without the callback, an order gets its status when the customer comes back to the store or when you click Check EveryPay payment status on the order page.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only after EveryPay has confirmed the payment through its API. Each field below lists your OpenCart order statuses.

Order Status After Payment: the order status set after a verified settled or authorised payment. Default: Processing.

Manual Review Status: the payment was made, but the amount or currency differs from the order, the order was cancelled meanwhile or it uses another payment method. A note explains why, and the order is not marked as paid. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Cancelled Order Status: a payment that arrives for an order with this status is put on manual review instead of paying the order. Default: Canceled.

Advanced

Debug log: logs payment events to wc_evp_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 wc_evp_debug.old.log.php. Errors and warnings are always logged. API secrets, e-mails and card data are never logged. Default: off.

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

Delete data on uninstall: when on, uninstalling the extension deletes the gateway settings and the log. EveryPay payment data of orders is always kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. API secrets are not exported.

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

Checkout

At the Payment Method step the customer chooses the payment method (by default EveryPay). At the Confirm Order step the customer sees your description and the note You will be redirected to the secure EveryPay payment page. 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 creates a one-off EveryPay payment for the order total in the order currency, with the customer's e-mail and the payment address, and sends the customer to the EveryPay payment page. The page language follows the customer's store language (English, Estonian, Russian, Latvian, Lithuanian, Finnish or German; otherwise English). There the customer pays with one of the methods enabled for your EveryPay account.

After paying, the customer returns to your store. The order is marked paid only after EveryPay confirms it: the extension asks the EveryPay API for the payment status on the return and on the callback. 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. If EveryPay is still processing the payment, or its API cannot be reached at that moment, a Payment confirmation page shows Your payment is being confirmed by EveryPay. You will receive an e-mail as soon as the order is confirmed. and a Check again button; the callback sets the order status as soon as EveryPay confirms the payment.

If the payment failed, the customer is back at checkout with Your EveryPay payment was not successful. Please try again or choose another payment method. If the customer left the payment page without paying, the message is The EveryPay payment was not completed. You can try again or choose another payment method. The cart is kept, and the order stays without a status. On OpenCart 4 these messages are shown above the checkout page.

OpenCart 3 creates a new order each time the Confirm Order step is shown; OpenCart 4 updates the order of the checkout, so a new attempt pays the same order with a new EveryPay payment. EveryPay cannot cancel a payment once it is created. So before a new payment the extension checks the open attempts of this order and of other orders of the same cart with the EveryPay API. If one of them is already paid, or another order of the same cart is already paid, the customer goes to the success page without a second payment. Every attempt is remembered, so a payment made with an older link is still recognised. If the customer still pays a second order of the same cart (for example, from two open browser tabs), that order gets no status, the customer sees the order success page, and the paid order gets a note asking you to refund the second payment in the EveryPay Merchant Portal.

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. Please confirm the order again., 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 is already paid. Please confirm the order again: the cart will be paid with a new order. A paid order is never shown as paid for a different cart.

If EveryPay cannot start the payment, the customer stays at the Confirm Order step with a short message above the button, for example EveryPay is temporarily unavailable. Please try again in a moment or choose another payment method. The details are in the log.

The extension takes one-time payments only. It has no refunds or capture from the store, no saved cards or one-click payments, no subscriptions or recurring payments, no embedded card fields and no multi-currency.

Orders

Order statuses

No status (missing order): the customer was sent to EveryPay and has not paid, the payment failed or was abandoned, or EveryPay has not confirmed the payment yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): EveryPay reported the payment as settled or authorised. A note shows the amount, the currency and the payment reference. For an authorised payment the note says the funds are reserved: if your account does not capture automatically, capture the payment in the EveryPay Merchant Portal. When it is settled later, one note says so.

Manual Review Status (default Pending): the payment needs manual review. The paid amount or currency differs from the order, the order had Cancelled Order Status before the payment arrived, or the order uses another payment method now. The note explains it and says the order was not marked as paid. Check the payment in the Merchant Portal and fulfil or refund it manually. Later callbacks for this payment do not complete the order automatically; a correct payment of another attempt of the same order still pays it.

If a second payment is completed for an order that is already paid, the order is not changed. A note asks you to refund the duplicate payment in the EveryPay Merchant Portal. Notes are entries in the order History that the customer does not see.

VibeFox EveryPay Payment tab

In Sales > Orders open an order paid with EveryPay. At the bottom of the order page, next to History and Additional, the VibeFox EveryPay Payment tab shows EveryPay payments of this order: Payment reference, Order reference, Mode (test or live), Amount, EveryPay state, Result and Date of every attempt. Below them are the EveryPay notes of the order. The tab is shown to users who have access to the extension.

Check EveryPay payment status: the button in the tab reads the status of every EveryPay payment of the order from the API, newest first, with the credentials of its mode, applies the result as above and adds one note with the state of each payment. The tab then reloads. You need the right to modify orders (System > Users > User Groups); the right to modify the extension is not needed. Use it when a callback never arrived, for example to see a later capture or refund. A status set by this button is written like a manual status change in the admin, without the order e-mails and stock update of the checkout.

Refunds

Refunds and captures from the store are not supported. Refund in the EveryPay Merchant Portal, then update the order status in OpenCart. When EveryPay reports a payment as refunded or charged back, the extension only adds a note to the order; the order status is not changed. Product returns in Sales > Returns do not send money back through EveryPay.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox EveryPay Payment is the first block on Extensions > Extensions > Payments > VibeFox EveryPay Payment > 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-everypay 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, EveryPay 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.

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

EveryPay does not appear at checkout: check that the license is active, Enable/Disable is on, the API username, API secret and Processing Account Name of the current mode are set, and the customer pays in the currency of the processing account. The settings page shows a warning in these cases. 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 callback is not working. Check that the URL from Callback notification URL is set in the Merchant Portal of the mode you use (demo or live) and that it opens from the internet. The order also gets its status when the customer returns to the store after paying. Look at the Log field on the extension page: errors are always logged.

Callback answers Unknown payment, Unknown payment reference, Payment cannot be verified or Payment does not belong to this order: the payment was not created by this store or for this order, or the EveryPay answer does not match it. Nothing is changed.

Callback answers Missing or invalid payment_reference: the request carried no valid payment reference, for example when the URL is opened in a browser.

Callback answers Not configured: the credentials of the environment where the payment was created are missing, for example a test payment after the test credentials were removed. Enter them again; EveryPay retries the callback.

Callback answers Payment status unavailable, Busy, please retry or Processing error, please retry: the EveryPay API could not be reached, the order was being processed by another request at the same moment, or the processing failed. EveryPay retries the callback. The reason is in the log.

The customer sees This payment method is not available right now: the credentials or the processing account of the current mode are missing.

The customer sees EveryPay is temporarily unavailable or Unable to start the EveryPay payment: EveryPay refused the credentials or could not be reached. Check the API username and API secret of the current mode.

The customer sees This payment method does not support the order currency: the order currency differs from the currency of the processing account.

The customer stays on the Payment confirmation page: EveryPay has not finalised the payment yet. The order gets its status by the callback, or when the customer clicks Check again after EveryPay confirms the payment.

Order is in the review status: read the EveryPay notes in the VibeFox EveryPay Payment tab. The amount or currency differed, the order had been cancelled before the payment arrived, or it uses another payment method. Check the payment in the Merchant Portal and fulfil or refund it manually.

For developers: before the payment is created, the extension triggers the OpenCart events wc_evp_oneoff_request (change the payment request) and wc_evp_locale (change the payment page language).

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox EveryPay Payment. 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. On OpenCart 4 the event of the extension (the checkout message) and its startup action, which lets the callback and the customer's return through in maintenance mode, are removed too. If the Uninstall switch in Advanced is on, the other gateway settings (title, description, test mode, credentials, processing account, debug log) and the log are removed. If it is off, they are kept for a later re-install. The EveryPay payment data of orders is always kept, so late callbacks for old orders still work 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 EveryPay Payment in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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