VibeFox Flow for Adobe Commerce — Ayuda

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, with the cURL and JSON extensions.

Currency: the order currency must be the Chilean peso (CLP) or the US dollar (USD). For other currencies the payment method is hidden at checkout. Flow charges CLP in whole pesos, so for CLP the order total must be a whole number of pesos (see Checkout).

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 addresses of your store must be reachable from the internet, without password protection or a firewall blocking Flow.

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-flow-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/FlowPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_FlowPayment 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 Flow 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 the sandbox API Key and Secret Key, set Enable to Yes, click Save Config and place a test order. To accept real payments, fill in the live keys and set Sandbox Mode to No.

The module adds the Flow 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 Flow payment attempts, their events and the refunds. Every 5 minutes the Magento cron checks the open Flow payments and refunds, so the Magento cron must be running.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > Flow 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. The fields form one list; below they are grouped by purpose in the order they appear.

If a value is wrong, Magento shows an error and nothing on the page is saved: Flow title is required and must not exceed 128 characters., Sort order must be a whole number., or Order total must be a number, 0 or greater. for Minimum Order Total and Maximum Order Total (use a point as the decimal separator, for example 9.99). When Enable is Yes in the Default Config and the keys of the current mode are missing, the page shows Flow is enabled but the selected environment credentials are missing. after saving. Flow is then hidden at checkout.

General

Enable: shows or hides Flow at checkout. It is shown only when both keys 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: Flow. Required, at most 128 characters.

Description: shown in the payment method list at checkout, when the customer selects Flow. 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 keys

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: Yes. Set it to No and fill in the live keys to accept real payments. While it is on, customers see TEST MODE — no real money is charged. under the payment method. Confirmations and refunds always use the mode the payment was made 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 in sandbox mode.

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

Live Secret Key: the Secret Key of your www.flow.cl account. It is used to sign every request in live mode. Keep it private.

Magento stores the keys encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved key, clear the field and click Save Config. Spaces around a pasted key are removed.

Conditions

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

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

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

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

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

Advanced

Debug Log: writes Flow requests and confirmations to var/log/flw_p_debug.log.php in the Magento folder. The file cannot be opened from the web, and it is rotated at 5 MB. Keys, tokens and customer data are not logged. Errors are always logged, even while 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 Flow payment and refund records always stay. Default: No.

Flow addresses

Below the settings the page shows Flow hosted checkout. Confirmation and refund callbacks retrieve signed server status. and the three addresses of the default store view that the module sends to Flow with every payment and refund. Nothing has to be entered in the Flow account. They look like this:

Each payment uses the addresses of the store view of its order. 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 using the keys of the mode the payment was created in, and applies only Flow's answer. A token that this store did not create is rejected without asking Flow. Without the confirmation, the order is confirmed when the customer returns from Flow or by the scheduled check of the Magento cron.

Log

The last row of the group shows the size and the latest entries of the log, or The log is empty. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Flow) and sees the description and the note You will be redirected to Flow. 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 creates a Flow payment for the order total in the order currency, with the subject Order # and the order number, 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.

After paying, the customer returns to your store. The order is marked paid only after Flow confirms it: by the confirmation, by a signed status request when the customer returns, or by the scheduled check. Magento then creates the invoice with the Flow order number as the transaction ID and sends the order e-mail. The customer sees the standard order success page. A customer who comes back in another browser lands on the home page.

If the customer generated a Servipag or Multicaja payment coupon, the order stays in Pending Payment, the coupon method is added to the payment information, the order e-mail is sent and the customer sees Your cash coupon is pending. Complete payment with the selected provider. When Flow confirms the coupon payment, the order is invoiced and the order e-mail is sent again. If the payment is still being processed, or Flow cannot be reached, the customer sees Your payment is being confirmed. Please check again. with a Check again link. If the amount did not match, the message is Your Flow payment needs manual review. Please contact the store. These pages are plain pages without the store theme.

If the payment was rejected, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Your Flow payment was rejected. Please try again or choose another method. If the customer left the Flow page without paying, the message is The Flow payment was not completed. Please try again or choose another method. Every new attempt creates a new Flow payment. Before that, the previous Flow payments of the same cart are checked again with Flow, so a cart cannot be paid twice.

If Flow refuses to start the payment, for example because the keys are wrong or a CLP order total has cents, the order is cancelled, the cart is restored and the customer sees The Flow payment was not completed. Please try again or choose another method. If the result of the request is uncertain (for example, Flow did not answer) or an earlier payment of the cart is still pending, the order stays in Pending Payment and the customer sees Flow could not start or an earlier payment is still pending. Contact the store before retrying. Turn on Debug Log to see the reason.

A CLP order total must be a whole number of pesos, because Flow charges whole pesos. Magento calculates totals with two decimals, so cents can appear, for example when prices are converted from another base currency or a tax percentage is added. Such an order cannot be paid with Flow. Use whole peso prices.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), the Flow payment page is not closed. If the customer still pays it, the order stays Canceled and gets a note asking for a manual review. Set the lifetime long enough for cash coupons.

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

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Flow, but Flow has not confirmed the payment yet, or a cash coupon has not been paid. There is no invoice.

Processing: Flow reported the payment as paid and the amount and currency match. The invoice is created with the Flow order number as the transaction ID, and a note shows the Flow order number, the payment method, the mode and how it was confirmed.

On Hold: Flow reported a different amount or currency than the order total, or the order had changed. No invoice is created. The note says that the payment requires manual review. Check the payment in Flow, then fulfil the order or refund the payment with the form in Flow payment history.

Canceled: the customer did not complete the payment, Flow rejected or annulled it, the payment could not be started, or the order was cancelled in Magento. A payment that arrives for a cancelled order leaves it Canceled and adds a note asking for a manual review.

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

If a second payment arrives for an order that is already paid, the order is not changed. A note asks you to refund the duplicate payment and not to invoice twice. The notes are order comments that the customer does not see.

Flow payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, once known, Flow order (the Flow order number), Environment (sandbox or live) and Payment instructions (the method of a cash coupon). The Information tab also shows Flow payment history: every Flow payment attempt of the order with the mode, the Flow order number, the requested and the captured amount and the status, followed by the Refund history. It is shown for old orders too, also when the module is disabled.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The refund is requested from Flow for the credit memo total in the currency of the payment. Full and partial refunds are supported, up to the amount Flow actually charged minus the approved refunds. CLP refunds must be whole amounts. The refund is sent to the mode the payment was made in (sandbox or live), so that mode's keys must be set. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Flow.

If Flow approves the refund at once, Magento creates the credit memo with FLW-R- and the Flow refund number as the transaction ID, and a note says Money returned. A full refund closes the order. If Flow accepts the request but has not completed the refund yet, Magento shows Flow refund is created. No Credit Memo was committed. Its callback will reconcile approved refunds. (or pending) and the credit memo is not created. When Flow reports the refund as approved, by the refund callback or by the scheduled check, the module creates the credit memo itself with the same items and amounts and adds a note. If Flow rejects or cancels the refund, the note says Money NOT returned. and the amount can be refunded again. If Flow refuses the request, Magento shows Flow refund was refused or its response is uncertain. Check the gateway before retrying. and the credit memo is not created.

While a refund of the payment is waiting for Flow, or its result is uncertain, no other refund of that payment can be sent: Magento shows A Flow refund is pending or uncertain. Check its status before retrying. A refund whose request got no answer from Flow stays uncertain and blocks further online refunds of that payment. Check the refund in your Flow account and refund the rest there, then create a credit memo with Refund Offline. If the order was refunded in another way while a Flow refund was waiting, the credit memo is not created automatically. Create it with Refund Offline.

For a payment that needs manual review (On Hold after a mismatch, a payment for a cancelled order, a duplicate payment), the Flow payment history shows the form Refund actual captured amount without a native invoice. Enter the amount and click Request Flow refund. You need the right to create credit memos. The money is returned through Flow without a credit memo, and the result is shown as Flow refund status: and added to the notes. Refunds created in the Flow dashboard are not imported into Magento.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Flow Gateway is the first row of the Flow 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-flow 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, Flow 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 The Flow payment was not completed. Please try again or choose another 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

Flow does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that both keys of the current mode are filled in (sandbox keys in sandbox mode, live keys in live mode). Check that the order currency is CLP or USD. 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 Flow confirmation does not reach your store and the customer did not return. Check that the Confirmation URL shown on the settings page opens from the internet and is not blocked by password protection, a firewall or Magento maintenance mode, and that the Magento cron is running: the scheduled check confirms open payments every 5 minutes. Turn on Debug Log and look at the log at the bottom of the group.

The confirmation URL answers Retry or unknown payment: the token is not a payment this store created, the keys of the mode of the payment are missing, Flow could not be reached, or the order was being updated by another request at the same moment. Flow retries the confirmation, and the scheduled check confirms the payment later. The URL answers OK when the payment was processed.

The customer is back in the cart with The Flow payment was not completed: the customer left the Flow page, or Flow refused to start the payment. Turn on Debug Log and look at the log. Check the API Key and Secret Key of the current mode, that the customer's e-mail is valid and, for CLP, that the order total has no cents. The order of that attempt is cancelled.

The customer sees Flow could not start or an earlier payment is still pending: Flow did not answer, or an earlier Flow payment of the same cart is still open or uncertain. The order stays in Pending Payment. Check the payments of the order in your Flow account. The scheduled check confirms a paid payment.

Order is On Hold after payment: read the order notes and the Flow payment history (see Order statuses), then fulfil the order or refund the payment.

Refund fails with The original Flow environment credentials are missing: the payment was made in sandbox or live mode, and the keys of that mode are not set. Enter them and try again.

Refund fails with Flow refund amount must be exact in the captured currency: CLP refunds must be whole amounts. Change the credit memo amounts.

Refund fails with Refund exceeds the actual captured Flow amount: the refund is larger than the amount Flow charged minus the approved refunds.

Refund fails with The Flow order changed. Reload the Credit Memo before requesting a refund: the order was changed by another request after the credit memo page was opened. Open the credit memo again.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded with a credit memo; use the form in Flow payment history.

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.

For developers, the README lists the events flw_p_supported_currencies (currencies the payment method is offered for) and flw_p_payment_subject (the payment subject sent to Flow).

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_FlowPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_FlowPayment to remove the data, then bin/magento module:disable Vibefox_FlowPayment, delete the folder app/code/Vibefox/FlowPayment 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 Flow payment, event and refund records 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.

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