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

Currency: Colombian peso (COP). Wompi Colombia charges COP, and the payment method is hidden when the customer shops in another currency. If the base currency of your store is not COP, set up COP as a display currency with a currency rate, so that customers can pay in COP.

Wompi account: a Wompi Colombia merchant account. Each environment (sandbox and production) has four keys: public key, private key, events secret and integrity secret. You find them in the Wompi merchant dashboard (comercios.wompi.co) in the developers section. Wompi must be able to reach the Events URL of your store. Wompi El Salvador and Panama are not supported.

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

2. Run bin/magento module:enable Vibefox_WompiPayment 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 VibeFox Wompi Payment. 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. Paste the sandbox and production keys from the Wompi merchant dashboard and set the Events URL shown on the settings page in Wompi (see Configuration). Set Enable to Yes and click Save Config. Test a payment with Sandbox mode = Yes, then set it to No to accept real payments.

The module adds the Wompi 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 two tables for the Wompi payment attempts and the processed events.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Wompi Payment, 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. Clean 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: an empty Title or a title longer than 128 characters (Enter a title for the payment method (1 to 128 characters).); a Sort Order that is not a whole number (Sort order must be a whole number.); a Min Order Total or Max Order Total that is not a number of 0 or more, written with a dot as the decimal separator (Order total must be a number, 0 or greater.).

The first row under the license block shows the Events URL and the line Refund or void in the Wompi dashboard, then record an offline Credit Memo in Magento. While Enable is Yes, it also shows the current mode, SANDBOX — no real charges will be made. or PRODUCTION — real payments will be charged., the line Wompi Colombia accepts COP only, minimum 1500.00 COP., the warning Wompi is enabled but hidden until all four current-environment keys are configured. when a key of the current mode is missing, and Check ...: expected key prefix .... The value has been saved. for every key that does not start with the prefix of its field (for example Check Sandbox private key: expected key prefix prv_test_. The value has been saved.). A key with a wrong prefix is saved anyway. These messages show the settings of the Default Config.

General

Enable: shows or hides Wompi at checkout. It is shown only when all four 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. Required. Default: Wompi.

Description: shown in the payment method list at checkout, when the customer selects Wompi. You can leave it empty. Default: Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

Mode and keys

Copy the keys from the Wompi merchant dashboard (comercios.wompi.co), developers section. Each environment has its own public key, private key, events secret and integrity secret. The public key identifies your account on the Wompi Web Checkout, the private key is used to read transactions from the Wompi API, the events secret verifies the signature of Wompi events and the integrity secret signs the payment request.

Sandbox mode: Yes uses the Wompi sandbox (sandbox keys, sandbox.wompi.co, no real money); No uses production (production.wompi.co). It switches both the keys and the Wompi API. Payment attempts keep the environment they were made in, so a payment started in sandbox mode is still checked in the sandbox after you switch. Default: Yes. While it is on, customers see SANDBOX — no real charges will be made. under the payment method.

Sandbox public key: the sandbox public key. It starts with pub_test_.

Sandbox private key: the sandbox private key. It starts with prv_test_.

Sandbox events secret: the sandbox events secret. It starts with test_events_.

Sandbox integrity secret: the sandbox integrity secret. It starts with test_integrity_.

Production public key: the production public key. It starts with pub_prod_.

Production private key: the production private key. It starts with prv_prod_.

Production events secret: the production events secret. It starts with prod_events_.

Production integrity secret: the production integrity secret. It starts with prod_integrity_.

Public keys are visible in their fields. Magento stores the private keys and secrets encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, or type a new value to change it. To delete a saved key or secret, clear the field and click Save Config.

Events URL (webhook)

Wompi events tell your store that a transaction has changed, including delayed PSE and Nequi payments. The first row of the group shows the Events URL, which looks like https://your-store/wcpwompipayment/webhook/index. Copy the URL exactly as the settings show it. In the Wompi merchant dashboard, developers section, set it as the Events URL for the sandbox and for production.

The module uses this event:

Other events are answered with Ignored. Each event is checked with the events secret of its environment (sandbox or production), as saved for the store of the order. Webhooks without a valid signature are rejected. After the check, the transaction is read from the Wompi API with the private key of that environment, and only that data is used. Without the Events URL, a payment is confirmed only when the customer comes back to the store after paying, and delayed payments are not confirmed later.

Advanced

Debug log: writes payment and event activity to var/log/wompi_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged, even when this option is No. Keys and customer data are not logged. Default: No.

Clean uninstall: removes settings and log; payment and event history is always retained. It works when you uninstall the module with its data (see Uninstall). Default: No.

Conditions

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

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

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

Min Order Total: offer Wompi only from this order total, in the base currency of your store. Empty or 0 means no minimum. The Wompi minimum of COP 1,500 is checked separately, in COP.

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

Log

The last row 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 Wompi) and sees the description and the note You will be redirected to Wompi to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module creates a payment attempt with its own reference (MG-, the cart number and a time stamp), signs it with the integrity secret and sends the customer to the Wompi Web Checkout with the order total in COP. The customer's e-mail and the name of the billing address are passed to Wompi. If the customer opens the payment page of the same order again, the same payment attempt is reused while the total, the currency and the mode are unchanged.

On the Wompi page the customer pays with any payment method enabled in your Wompi account. Then Wompi sends the customer back to your store. The order is marked paid only after Wompi confirms it: by a signed event or by a request to the Wompi API when the customer comes back. The transaction number in the return address itself is not trusted, and only transactions created for that cart in the environment of its attempt are accepted. On page reloads, the transaction is read again at most once every 20 seconds.

When the transaction is approved for the order amount, Magento creates the invoice with the Wompi transaction ID, sets the order to Processing and sends the order e-mail. The customer sees the standard order success page. If Wompi has not confirmed the transaction yet, for example a PSE or Nequi payment that is pending, the customer sees the page Wompi payment status with We are waiting for Wompi to confirm your payment. and a Check again link. The Wompi event confirms the order as soon as it arrives. If the payment needs a manual check (see Order statuses), the page shows Payment requires manual review. Please contact the store. A customer who comes back in another browser lands on the home page.

If the payment is declined, ends with an error or is voided, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Wompi payment was not approved. and the reason given by Wompi. The same happens when the customer comes back from Wompi without a transaction. The next attempt creates a new order and a new reference.

The payment method is shown only when the license is active, all four keys of the current mode are set, the customer shops in COP and the total is at least COP 1,500. If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees the reason in the cart:

If an unexpected error occurs, the message is Wompi payment could not be started. Check the previous payment before retrying. An unpaid payment attempt of an order that was cancelled in Magento does not block the cart: when the customer pays the restored cart again, the old attempt is closed and a new one is created.

An order in Pending Payment can be cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). The Wompi payment page is not closed by that. A payment approved after the order was cancelled is not invoiced; the order gets a note (see Order statuses). For delayed payments such as PSE, keep the lifetime long enough.

The module works with the standard Magento checkout. It has no card form on your site, saved cards or subscriptions, and it does not refund from Magento. Wompi 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 Wompi, but Wompi has not confirmed the payment yet, or Wompi reports the transaction as pending (for example PSE or Nequi). A note shows the pending transaction and its payment method. There is no invoice.

Processing: Wompi approved the transaction for the order amount in COP. The invoice is created with the Wompi transaction ID as the transaction ID, and a note shows the amount, the transaction and the environment.

On Hold after a mismatch: Wompi approved a different amount or currency than the payment attempt or the order total. No invoice is created. The note explains it. Check the transaction in the Wompi dashboard, then fulfil the order or refund the payment there.

Canceled: the latest payment attempt of the order was declined, ended with an error or was voided, the customer came back without paying, the payment could not be started, or the order was cancelled in Magento. Results of older attempts of the cart do not change the order. If a payment is approved after the order was cancelled or closed, the order is not reopened: a note asks you to review the payment and refund it in the Wompi dashboard.

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

If a second approved payment arrives for an order that is already paid, or another order of the same cart is already paid, the order is not changed. A note asks you to review the transaction and refund the duplicate in the Wompi dashboard. If the paying transaction is voided in Wompi, a note asks you to review the payment and record any refund with an offline credit memo. Unknown Wompi statuses are only added as a note. Repeated events and returns never duplicate notes, invoices or e-mails. The notes are order comments that the customer does not see.

Wompi payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and one row Wompi attempt #... for every payment attempt of the order: the reference, the environment, the status of the module and the Wompi status, the requested amount, the transaction ID, the amount of the transaction, the payment method type (for example CARD, PSE or NEQUI) and the Wompi message. The row Refunds reminds you how refunds are made. The customer sees only the payment method title.

Refunds

Refunds are not sent from Magento. Refund or void the payment in the Wompi merchant dashboard, then record it in Magento: open the order, click Credit Memo, choose the items and amounts and click Refund Offline. A full refund closes the order. A void of the paying transaction made in Wompi is added to the order as a note; no credit memo is created automatically.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Wompi Payment is the first row of the VibeFox Wompi Payment 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-wompi 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, Wompi 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 This payment method is not available. Please choose another one. 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 by Wompi events and when the customer returns.

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

Wompi does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that all four keys of the current mode are set (the first row of the group warns you when a key is missing). Check that the customer shops in COP and that the total is at least COP 1,500. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Min Order Total and Max Order Total.

The payment went through, but the order stays Pending Payment: the Events URL is not working. In the Wompi dashboard check that the Events URL is set for the environment you use (sandbox or production) and that it is exactly the one shown in the settings. Check that the events secret and the private key of that environment are saved for the website of the store, and turn on Debug log to see the reason. A payment is also confirmed when the customer returns to the store after paying.

Events URL answers Not configured: no events secret is saved for the event's environment. Paste it into the settings.

Events URL answers Invalid signature: the events secret belongs to another environment or another account. Copy it again from the Wompi dashboard.

Events URL answers Transaction lookup failed: the Wompi API did not return the transaction, for example because of a wrong private key or a network problem. Wompi sends the event again later.

Events URL answers Retry: the order was being updated by another request at the same moment, or an error occurred while the order was being updated. Wompi sends the event again later. The reason is in the log.

Events URL answers Environment mismatch: a sandbox transaction came for a production payment attempt or the other way round. Sandbox payments never confirm production orders.

Events URL answers Unknown reference or Credential scope mismatch: the transaction was not started by this store, or it was signed with keys of another website than the order's. References that were not issued by Magento are answered with Ignored: not a Magento reference, for example when the same Wompi account is used by another shop.

The Events URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Wompi.

Events fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the Events URL too. Wompi sends the event again later, and payments are also confirmed when the customer returns.

Order is On Hold or has a Wompi note: read the order notes and the Wompi attempt rows of the payment information (see Order statuses), then fulfil the order or refund the payment in the Wompi dashboard.

The customer sees A previous payment for this cart needs confirmation or manual review.: a previous payment of the same cart is pending at Wompi or needs a manual check (On Hold, late or duplicate payment). Check the payment in the Wompi dashboard.

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.

Developers can change the parameters sent to the Wompi Web Checkout with the Magento event wompi_p_checkout_params. It does not confirm payments.

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

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

The license key and license status are always removed. If Clean uninstall is Yes, the module settings and the log are removed too. If it is No, the settings are kept for a re-install. The Wompi payment attempts and processed events are always kept, so a late event of an old payment is still recognised after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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