VibeFox Wompi for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Store currency: Colombian peso (COP). Wompi Colombia charges COP, and the payment method is hidden for orders in other currencies.

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 El Salvador and Panama use different APIs and are not supported.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_wompi_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Set the store currency to Colombian peso (COP) in WooCommerce > Settings > General.

4. Open the settings: WooCommerce > Settings > Payments > Wompi, or click Settings under the plugin name on the Plugins page.

5. Enter your VibeFox license key in the license block at the top of the page and click Activate.

6. Paste the sandbox and production keys from the Wompi merchant dashboard and set the Events URL in Wompi (see Configuration).

7. Turn on Enable/Disable. Test a payment in sandbox mode, then untick Sandbox mode to accept real payments.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Wompi. Above the fields a status box shows the current mode, SANDBOX or PRODUCTION. When a key of this mode is missing, the box lists it and says that the payment method is hidden at checkout until all keys of this environment are set. When all keys are set, it says whether real payments are charged. When you save, the plugin warns you if a key does not start with the prefix of its section, and if Wompi is enabled but hidden at checkout because keys are missing. In the list of payment methods, Wompi is marked as needing setup until the current mode has all four keys. Keys of version 1.0 are moved to the matching Sandbox or Production section automatically on update.

General

Enable/Disable: Enable Wompi turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Wompi.

Description: the text shown under the payment method at checkout. Default: Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

Wompi account

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.

Sandbox mode: Use the Wompi sandbox (sandbox keys, no real money). It switches both the keys and the Wompi API (sandbox.wompi.co or production.wompi.co). Orders keep the environment they were paid in. Default: on. Untick it to accept real payments.

Sandbox keys

The four keys of the Wompi sandbox. They start with pub_test_, prv_test_, test_events_ and test_integrity_.

Public key: the sandbox public key (pub_test_...). It identifies your account on the Wompi Web Checkout.

Private key: the sandbox private key (prv_test_...). It is used to read transactions from the Wompi API.

Events secret: the sandbox events secret (test_events_...). It verifies the signature of Wompi events.

Integrity secret: the sandbox integrity secret (test_integrity_...). It signs the payment request sent to the Web Checkout.

Production keys

The four keys of the Wompi production environment. They start with pub_prod_, prv_prod_, prod_events_ and prod_integrity_.

Public key: the production public key (pub_prod_...).

Private key: the production private key (prv_prod_...).

Events secret: the production events secret (prod_events_...).

Integrity secret: the production integrity secret (prod_integrity_...).

Events URL (webhook)

Wompi events tell your store that a transaction has changed. In the Wompi merchant dashboard, developers section, set the Events URL shown in this section of the settings, for the sandbox and for production. It looks like https://your-site/wc-api/wompi_p/. Copy the URL exactly as the settings show it.

The plugin uses this event:

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

Advanced

Debug log: Log payment and webhook activity writes payment and event activity to WooCommerce > Status > Logs, source wcp_wompi_payment. Errors are always logged, even when this option is off. Keys, secrets and customer data are never logged. Default: off.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted. Deactivation never deletes anything. Order data is always kept. Default: off.

Checkout

The customer chooses the payment method (by default Wompi) and places the order. In sandbox mode the checkout shows Sandbox mode: no real payment is made. under the description. The plugin creates a payment attempt with its own reference (WC-, the order 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 billing e-mail and name of the customer are passed to Wompi. A note on the order records the environment, the reference and the amount.

On the Wompi page the customer pays with any payment method enabled in your Wompi account. Then Wompi sends the customer back to the order received page of your store. The order is marked paid only after Wompi confirms it: by a signed event or by a server-side request to the Wompi API when the customer lands on that page. The transaction number in the return address itself is not trusted. On page reloads, the transaction is checked again at most once every 20 seconds.

Only transactions created for that order can pay it, and only in the environment of the attempt. A customer can pay an unpaid order again, for example from the Pay for order page. Each attempt gets a new reference.

The payment method is shown only when the license is active, all four keys of the current mode are set, the order currency is COP and the total is at least COP 1,500. If the payment cannot start, the customer sees a short message and can choose another payment method:

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS). Spanish translations for Colombia and Spain are included.

The plugin does not refund from WooCommerce. It has no saved cards, no subscriptions and no card fields on your site: all payment data is entered on Wompi.

Orders

Order statuses

Pending payment: the customer was sent to Wompi and has not paid yet, or Wompi has not confirmed the transaction yet.

On hold (pending payment): Wompi reports the transaction as pending, for example PSE, Nequi or cash payments waiting for confirmation. The order stays on hold until Wompi approves or declines it.

Processing or Completed: the transaction was approved. The WooCommerce standard applies: Processing, or Completed for orders with only virtual downloadable products. The order note shows the Wompi transaction, the payment method type (for example card, PSE or Nequi) and the reference. The transaction ID of the order is the Wompi transaction ID.

On hold after payment: Wompi approved a different amount or currency than the order total (for example, the order was edited after the payment started), or the payment was approved after the order had been cancelled. The order is not marked paid. The order note explains it. Check the payment in the Wompi dashboard and fulfil the order or refund the payment.

Failed: the transaction of the latest payment attempt was declined or ended with an error. The Wompi message is added to the note. Results of older attempts do not change the order.

Cancelled: the transaction of the latest payment attempt was voided in Wompi before the order was paid.

If a second approved payment arrives for an order that is already paid, the order is not changed. A note asks you to refund the duplicate in the Wompi dashboard. If the paying transaction is voided in Wompi, a note asks you to review the order. A late payment for a refunded order only adds a note. Repeated events and returns never duplicate notes, e-mails or stock changes.

Refunds

Refunds are not sent from WooCommerce. Refund or void the payment in the Wompi merchant dashboard, then record a manual refund in WooCommerce. A void made in Wompi is added to the order as a note.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Wompi. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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 customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed by Wompi events and customer returns.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Wompi does not appear at checkout: check that the license is active, Enable/Disable is on and all four keys of the current mode are set (the status box on the settings page lists missing keys). Check also that the order currency is COP and the order total is at least COP 1,500.

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 of that environment is in the matching section. The order is also confirmed when the customer returns to the store after paying.

Events URL answers Not configured: the events secret of the event's environment is empty. 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 Busy, retry: the order was being updated by another request at the same moment. Wompi sends the event again later.

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.

The key does not start with ... warning on save: a key was pasted into the wrong section. Sandbox keys start with pub_test_, prv_test_, test_events_ and test_integrity_, production keys with pub_prod_, prv_prod_, prod_events_ and prod_integrity_.

Order is On hold with a note about the amount: the approved amount or currency differs from the order total. Check the payment in the Wompi dashboard and complete or refund the order manually.

Other errors: open the order notes or WooCommerce > Status > Logs, source wcp_wompi_payment. Errors are always logged. Turn on Debug log for more detail. Developers can allow another currency with the wompi_p_supported_currencies filter if their Wompi account accepts it.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the plugin logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, Wompi data and transaction IDs.

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