VibeFox Flow for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
Currency: Chilean peso (CLP) or US dollar (USD). For carts in other currencies the payment method is hidden at checkout. For CLP set the precision of the CLP currency to 0 in International > Localization > 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 shop must be reachable from the internet, without password protection or a firewall blocking Flow. Maintenance mode of the shop does not block them.
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 Flow 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 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 and turn off Sandbox mode.
On install the module creates two order statuses, Awaiting Flow payment and Flow 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 Flow Gateway > Configure. Each section with fields has its own Save button, which saves the whole page. Above the fields 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 shop is not CLP or USD, and when the CLP currency has decimals (set its precision 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.
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.
Description: the text shown under the payment method at checkout. Default: Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.
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 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.
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.
Clear saved keys: tick a key and click Save to remove it. An empty field keeps the saved value.
Notifications
The module 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. With friendly URLs they look like this:
The confirmation carries only a payment token. The module 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 shop did not create is rejected without asking Flow. Without the confirmation, the order is created when the customer returns from Flow.
Advanced
Debug log: writes API calls and notifications to logs/flw_p_debug.log.php in the module folder. The file cannot be opened from the web. Keys 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 module removes its settings and the log. Flow data saved on orders is kept. Default: off.
Checkout
At the payment step the customer chooses the payment method (by default Flow) and sees the description. In sandbox mode it shows SANDBOX MODE — Payments go to the Flow sandbox. No real charges. After confirming, the module creates a Flow payment for the cart total in the cart currency, with the subject Cart # plus the cart number and the shop 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. No order exists yet at this point.
After paying, the customer returns to your shop. 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 is then created and the customer sees the standard order confirmation page with Your payment with Flow has been received. If the customer generated a Servipag or Multicaja coupon, the order is created in Awaiting Flow payment and the page shows Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. If the payment of a coupon order later fails or is cancelled, the page shows Your Flow payment was not completed. Please contact us about this order. If the amount did not match, the page shows Your Flow payment was received and is being reviewed by the shop.
If Flow cannot be reached when the customer comes back, or another request is creating the order at that moment, a Payment confirmation page asks the customer not to pay again and offers Check again and Back to checkout.
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. 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 result could not be checked, 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, and every new attempt creates a new Flow payment bound to the cart.
If Flow cannot start the payment, the customer stays at checkout with a short message, for example Could not connect to Flow. Please try again in a moment. The details are in the log.
If a voucher in the cart stops being valid between the payment and its confirmation, PrestaShop removes it from the order. The order then goes to Flow payment on hold with a note, because the customer paid the price with the discount.
The module takes one-time payments only. It has no saved cards, subscriptions, recurring charges or payment links and does not preselect a Flow payment method. Flow cannot cancel an already created payment link: if a customer pays an old link after the cart was already paid, the order gets a note asking you to refund the duplicate in Flow.
Orders and refunds
Order statuses
No order yet: the customer was sent to Flow and has not paid, or Flow has not confirmed the payment yet. Only the cart exists.
Payment accepted: Flow reported the payment as paid and the amount and currency match. The payment is recorded with the Flow order number as the transaction ID, and a note shows the amount, the Flow order number and the payment method.
Awaiting Flow payment: the customer generated a Servipag or Multicaja payment coupon. The order moves to Payment accepted when Flow confirms the payment.
Flow payment on hold: Flow reported a different amount or currency than the order total (for example, the cart was changed after the payment started), a voucher was removed, 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 error: Flow rejected the coupon payment of an awaiting order.
Canceled: the coupon payment of an awaiting order was annulled in Flow.
Refunded: the payment was fully refunded through the module.
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.
Flow payment block
The order page shows a Flow payment block with the Flow order number and payment method, the commerceOrder reference, the payment status, the amount paid and refunded, a Sandbox badge for sandbox payments, the refund history and the Flow notes of the order.
Refunds
In the Flow payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, 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 edit orders. 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 block 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. 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. The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Flow. Refunds created in the Flow dashboard are not imported into PrestaShop.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Flow Gateway is the first block on Modules > Module Manager > VibeFox Flow 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-flow 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, 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. 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
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 cart currency is CLP or USD. 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 Flow confirmation does not reach your shop 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 module page.
Confirmation answers Payment does not belong to the order: the token is not a payment this shop 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 created 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 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 cart total rounds to zero in the cart currency.
The customer paid, but the order is Awaiting Flow payment or Flow payment on hold: read the notes in the Flow payment block. 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 precision to 0.
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 README lists the hooks actionWcpFlowSupportedCurrencies (currencies the payment method is offered for) and actionWcpFlowPaymentSubject (the payment subject sent to Flow).
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox Flow Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the module settings and the log are removed. If it is off, all settings are kept for a later re-install. The Flow payment and refund records and the order statuses Awaiting Flow payment and Flow 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.
Flow is a trademark of its respective owner. This module is not affiliated with or endorsed by Flow.