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

Currency: Chilean peso (CLP) or US dollar (USD). For other checkout currencies the payment method is hidden at checkout. For CLP set the decimal places of the CLP currency to 0 in System > Localisation > Currencies, because Flow charges whole pesos.

Flow account: you need the API Key and Secret Key of your Flow account, in Flow under Mis datos, Datos técnicos. For tests, create a separate sandbox account at sandbox.flow.cl and use its keys. Sandbox and live keys are different. Nothing needs to be configured in the Flow account.

Public website: the confirmation, return and refund URLs of your store must be reachable from the internet, without password protection or a firewall blocking Flow. Maintenance mode of the store does not block them.

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_flow_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_flow_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_flow_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 Flow 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 the sandbox API Key and Secret Key, turn on Enable / Disable, click Save and place a test order.

5. To accept real payments, fill in the live keys, turn off Sandbox mode and click Save.

OpenCart 4

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

4. Enter the license key and the Flow keys as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the Flow URLs are different (see Flow URLs); they are sent with every payment, so nothing has to be changed in the Flow account.

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 Flow Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page warns you when the keys of the current mode are empty (Flow is then hidden at checkout), when the default currency of the store is not CLP or USD, and when the CLP currency has decimal places (set them to 0 so that prices, totals and refunds match exactly). In sandbox mode it shows Sandbox mode — payments go to sandbox.flow.cl, no real money is charged. 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 empty or a whole number, Total must be empty or a number of 0 or more, and the selected geo zone and order statuses must exist. Otherwise nothing is saved and the page shows what to correct.

Flow.cl

Enable / Disable: Enable Flow.cl payments turns the payment method on or off. Default: off.

Title: the payment method name the customer sees at checkout. It is also the payment method name stored in the order. Default: Flow. Required, up to 128 characters.

Description: the payment method description shown on the Confirm Order step, above the confirm button. Default: Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.

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

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

Flow API credentials

Copy the API Key and Secret Key from your Flow account (Mis datos, Datos técnicos): live keys at www.flow.cl, sandbox keys at sandbox.flow.cl (a separate sandbox account). Sandbox mode uses only the sandbox keys, live mode only the live keys.

Sandbox mode: uses the Flow sandbox (sandbox.flow.cl) and the sandbox keys. No real money is charged in sandbox mode. Default: on. Turn it off and fill in the live keys to accept real payments. Refunds always use the environment the order was paid in. While it is on, customers see SANDBOX MODE — Payments go to the Flow sandbox. No real charges. at the Confirm Order step.

Sandbox API Key: the API Key of your sandbox.flow.cl account.

Sandbox Secret Key: the Secret Key of your sandbox.flow.cl account. It is used to sign every request.

Live API Key: the API Key of your www.flow.cl account.

Live Secret Key: the Secret Key of your www.flow.cl account. Keep it private.

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

Notifications

The extension sends three URLs to Flow with every payment and refund, so nothing has to be configured in the Flow account. The Flow URLs field of this section lists them for reference. They are built from the storefront address of your OpenCart installation and look like this:

On OpenCart 4 the method follows a dot: https://your-store/index.php?route=extension/wcp_flow_gateway/payment/wcp_flow_gateway.confirmation, ….back and ….refundCallback.

The confirmation carries only a payment token. The extension looks the token up among the payments it created, asks Flow for the payment status with a signed request in the environment the payment was created in, and applies only Flow's answer. A payment that this store did not create is rejected without asking Flow. Without the confirmation, the order gets its status when the customer returns from Flow.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only after Flow has reported the payment, by the confirmation or the customer's return. The status is always read from Flow with a signed request. Each field below lists your OpenCart order statuses.

Order Status After Payment: the status set after a verified Flow payment. Default: Processing.

Awaiting Flow Payment Status: the customer generated a cash payment coupon (Servipag, Multicaja and similar). The money arrives later, and Flow confirms it. Default: Pending.

Flow Payment On Hold Status: paid, but the amount or currency differs from the order, or the money arrived for a cancelled order. A note explains why; check the payment manually. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Payment Rejected Status: an order awaiting a coupon payment whose Flow payment was rejected. Default: Failed.

Payment Annulled Status: an order awaiting a coupon payment whose Flow payment was cancelled (annulled). Default: Canceled.

Refunded Status: set after the payment is fully refunded from the order page. Default: Refunded.

Advanced

Debug log: writes API calls and notifications to flw_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 flw_p_debug.old.log.php. Keys, signatures and customer data are never logged. Errors are always logged, even while it is off. 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 removes its settings and the log. Flow data saved on orders is kept. Default: off.

Import / Export

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

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

Checkout

At the Payment Method step the customer chooses the payment method (by default Flow). At the Confirm Order step the customer sees your description and the note You will be redirected to Flow to complete the payment. 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 Flow payment for the order total in the order currency, with the subject Order # plus the order number and the store name, and sends the customer to the Flow payment page. The customer's e-mail is passed to Flow. There the customer chooses a payment method enabled in your Flow account. The order gets the note Flow payment started with the amount, the Flow order number and the environment.

After paying, the customer returns to your store. The order is marked paid only after Flow confirms it: by the confirmation or by a signed status request when the customer returns. 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 the customer generated a Servipag or Multicaja coupon, the order gets Awaiting Flow Payment Status and the page also shows Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. If the amount did not match, the page shows Your Flow payment was received and is being reviewed by the store.

If Flow cannot be reached when the customer comes back, or another request is confirming the order at that moment, a Payment confirmation page shows We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly — please do not pay again. with a Check again button and a Back to checkout button.

If the payment was rejected, the customer is back at checkout with Your Flow payment was rejected. Please try again or choose another payment method. The order stays without a status. If the customer left the Flow page without paying, the message is The Flow payment was not completed. You can try again or choose another payment method. If the return could not be matched to a payment, the message is We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly; otherwise please try again. The cart is kept. 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 pays the same order with a new Flow payment. Flow cannot cancel a payment that was already started. So before a new payment, the open Flow payments of this order and of other orders of the same cart from the last two days are checked with Flow. If one turns out to be paid or has a coupon, the customer goes to the success page instead of paying again. If another order of the same cart has already been paid with Flow, no new payment is started either. If the same cart is still paid twice, for example in two browser tabs, only the first payment gives its order a status: the other order stays without a status, and the paid order gets a note asking you to refund the second payment in your Flow account.

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 The Flow payment was not completed. You can try again or choose another payment method., and the next Confirm Order pays a new order of the cart. If that order is already paid or has a coupon but the cart has changed since, including a new quantity, the customer is sent back to the checkout, and the next Confirm Order pays the new cart with a new order. A paid order is never shown as paid for a different cart.

If Flow cannot start the payment, the customer stays at the Confirm Order step with a short message, for example Could not connect to Flow. Please try again in a moment. The details are in the log.

The extension takes one-time payments only. It has no saved cards, subscriptions, recurring charges or payment links and does not preselect a Flow payment method. If a customer pays an old Flow payment after the order was already paid, the order gets a note asking you to refund the duplicate in Flow.

Orders and refunds

Order statuses

No status (missing order): the customer was sent to Flow and has not paid, the payment was rejected or not completed, or Flow 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): Flow reported the payment as paid and the amount and currency match. A note shows the amount and the Flow order number.

Awaiting Flow Payment Status (default Pending): the customer generated a cash payment coupon. A note names the coupon type. The order moves to Order Status After Payment when Flow confirms the payment.

Flow Payment On Hold Status (default Pending): Flow reported a different amount or currency than the order total, or a payment arrived for an order that had been cancelled. The payment Flow took is recorded and the note explains it. Check the order and ship it or refund the payment.

Payment Rejected Status (default Failed): Flow rejected the coupon payment of an awaiting order.

Payment Annulled Status (default Canceled): the coupon payment of an awaiting order was annulled in Flow.

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

If another payment arrives for an order that is already paid, the order is not changed. A note asks you to refund the duplicate in your Flow account. A refunded order is never reopened.

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

VibeFox Flow Gateway tab

In Sales > Orders open an order paid with Flow. At the bottom of the order page, next to History and Additional, the VibeFox Flow Gateway tab shows the Flow order number with the payment method and a Sandbox label for sandbox payments, the commerceOrder reference (and the number of attempts), the payment Status, the amounts Paid / refunded, the refund form, the refund history and the Flow 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 Flow. Confirm the question Refund this amount via Flow? Flow e-mails the customer to complete the refund. Full and partial refunds are supported. You need the right to modify the extension (set in System > Users > User Groups). Refunds are limited to the amount Flow actually charged, so after an amount mismatch you can refund up to what the customer paid, not the order total. CLP refunds must be whole amounts. The refund is sent to the environment the payment was made in (sandbox or live), so that environment's keys must be set, and the customer needs a valid e-mail. If Flow refuses the refund, the tab shows the error and no refund is recorded. A successful request is added to the refund history and the notes with the Flow refund number and status. A full refund sets the order to Refunded 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 Flow has confirmed the payment.

Later status changes of the refund reported by Flow are added to the notes. If Flow rejects or cancels a refund afterwards, the note says that the money was not returned to the customer, and the amount can be refunded again. Product returns in Sales > Returns do not send money back through Flow. Refunds created in the Flow dashboard are not imported into OpenCart.

License key

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

Flow does not appear at checkout: check that the license is active, Enable / Disable is on, the keys of the current mode are filled in (sandbox keys in sandbox mode, live keys in live mode) and the checkout currency is CLP or USD. 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 Flow confirmation does not reach your store and the customer did not return. Check that the confirmation URL shown in Flow URLs opens from the internet and is not blocked by password protection or a firewall. Turn on Debug log and look at the Log field on the extension page.

Confirmation answers Payment does not belong to the order: the token is not a payment this store created, or Flow reported another reference for it. Nothing is changed.

Confirmation answers Gateway not configured: the keys of the environment of the payment are empty. Enter them again. Flow retries the confirmation.

Confirmation answers Flow API unavailable or Busy, retry: the status request to Flow failed, or the order was being confirmed by another request at the same moment. Flow retries the confirmation.

The customer sees Flow payments are not available at the moment: the keys are missing or Flow refused them. Check the API Key and Secret Key of the current mode.

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

The customer sees A valid billing email is required for Flow payments: Flow needs the customer's e-mail.

The customer sees The order total is too small to be paid with Flow: the order total rounds to zero in the order currency.

The customer paid, but the order is in the awaiting or on hold status: read the notes in the VibeFox Flow Gateway tab. The customer generated a cash coupon that is not paid yet, or the amount or currency reported by Flow does not match the order. CLP totals with decimals are rounded to whole pesos, so set the CLP decimal places to 0.

No refund form in the tab: the tab says why: the payment is not confirmed yet, it is fully refunded, your user group has no right to modify the extension, or the keys of the environment the payment was made in are empty.

Refund fails with a message about the sandbox or live keys: the order was paid in that environment, and its keys are empty. Enter them and try again.

Refund fails with Flow accepts CLP refunds in whole units only: enter a whole amount.

For developers, the extension triggers the OpenCart events wc_flw_supported_currencies (currencies the payment method is offered for) and wc_flw_payment_subject (the payment subject sent to Flow).

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Flow 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 Flow URLs through in maintenance mode). If Delete data on uninstall is on, the other settings (title, description, sandbox mode, keys, debug log switch) and the log are removed. If it is off, they are kept for a later re-install. The Flow 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 Flow Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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