VibeFox Wompi 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: Colombian peso (COP). Wompi Colombia charges COP, and the payment method is hidden for carts in other currencies. The settings page warns you when the default currency of the shop is not 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 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 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 Wompi Payment 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. Paste the sandbox and production keys from the Wompi merchant dashboard and set the Events URL in Wompi (see Configuration).

5. Turn on Enable/Disable and click Save. Test a payment in sandbox mode, then turn off Sandbox mode to accept real payments.

On install the module creates two order statuses, Awaiting Wompi payment and Wompi payment on hold. PrestaShop offers a new payment module for the currencies, countries and customer groups that exist at that moment. Check that COP is allowed in Payment > Preferences. A country you add later must be ticked there before customers from it see Wompi.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Wompi Payment > Configure. Each section with fields has its own Save button, which saves the whole page. 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 module 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.

Wompi

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

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Wompi. If you leave it empty, the module name is used.

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: uses the Wompi sandbox (sandbox keys, no real money). It switches both the keys and the Wompi API (sandbox.wompi.co or production.wompi.co). Payment attempts keep the environment they were made in. Default: on. Turn it off to accept real payments. While it is on, customers see Sandbox mode: no real payment is made. under the payment method.

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_...).

Public keys are shown in their fields. Saved private keys and secrets 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 secrets: tick a private key or secret of either environment and click Save to remove it. An empty field keeps the saved value.

Events URL (webhook)

Wompi events tell your shop that a transaction has changed. In the Wompi merchant dashboard, developers section, set the Events URL shown in this section, for the sandbox and for production. With friendly URLs it looks like https://your-shop/module/wcp_wompi_payment/webhook, possibly with a language code such as /es/. Copy the URL exactly as the settings show it.

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). 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, an order is created only when the customer comes back to the shop after paying.

Advanced

Debug log: writes payment and webhook activity to logs/wompi_p_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings are always logged, even when this option is off. Keys, secrets and customer data are never logged. 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 the module settings and the log. The Wompi payment attempts and the module's order statuses always stay, so existing orders keep their Wompi data. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Wompi) and confirms. The module creates a payment attempt with its own reference (PS-, the cart number and a time stamp), signs it with the integrity secret and sends the customer to the Wompi Web Checkout with the cart total in COP. The customer's e-mail and the name of the invoice address are passed to Wompi. No order exists yet at this point.

On the Wompi page the customer pays with any payment method enabled in your Wompi account. Then Wompi sends the customer back to your shop. 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 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 checked again at most once every 20 seconds.

When the transaction is approved, the order is created and the customer sees the standard order confirmation page. For a pending payment (for example PSE, Nequi or a cash payment) the page shows Your Wompi payment is pending confirmation (for example PSE, Nequi or a cash payment). We will process the order as soon as Wompi confirms the payment. For an order on hold it shows We have received your Wompi payment and are reviewing it. We will contact you if anything is needed. If a pending payment is later declined, the page shows Your Wompi payment was not approved. Please contact us. If it is voided, the page shows Your Wompi payment was voided and this order was cancelled. Please contact us.

If Wompi has not confirmed the transaction yet when the customer comes back, a page shows We are waiting for Wompi to confirm your payment. You will receive an e-mail as soon as it is confirmed. with a Check again button. The Wompi event creates the order as soon as it arrives.

If the payment is declined, no order is created and the cart is kept. The customer is back at checkout with Your Wompi payment was not approved (...). You can try again or choose another payment method., with the reason given by Wompi. A voided payment gives Your Wompi payment was voided. You can try again or choose another payment method. If the customer leaves the Web Checkout without paying, the message is Your Wompi payment was not completed. You can try again or choose another payment method. Each new attempt gets a new reference. Once the cart has an order (paid, pending, Payment error or Canceled), it cannot be paid again: the customer is taken to the order confirmation page.

The payment method is shown only when the license is active, all four keys of the current mode are set, the cart currency is COP and allowed for the module, and the total is at least COP 1,500. If the payment cannot start, the customer stays at checkout with a short message:

The Events URL works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

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

Orders

Order statuses

No order yet: the customer was sent to Wompi and has not paid, the payment was declined, or Wompi has not confirmed the transaction yet. Only the cart exists.

Awaiting Wompi payment: Wompi reports the transaction as pending, for example PSE, Nequi or cash payments waiting for confirmation. The order waits until Wompi approves or declines it. When it is approved, the payment is recorded and the order moves to Payment accepted.

Payment accepted: the transaction was approved for the cart amount in COP. The payment is recorded with the Wompi transaction ID, and a note shows the transaction, the payment method type (for example CARD, PSE or NEQUI), the reference, the amount and the environment.

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

Payment error: a pending 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.

Canceled: a pending transaction of the latest payment attempt was voided in Wompi.

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 payments.

Wompi payment block

The order page shows a Wompi payment block with the reference, the transaction ID, the status (with the Wompi status), the requested amount, the amount of the transaction, the payment method, the Wompi message, a SANDBOX badge for sandbox payments, the Payment attempts of the cart when there were several, and the Wompi notes of the order.

Refunds

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

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Wompi Payment is the first block on Modules > Module Manager > VibeFox Wompi Payment > 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-wompi 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, 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. 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 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 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

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 cart currency is COP and the total is at least COP 1,500. In Payment > Preferences check that the module is allowed for COP, the customer's country and the customer's group.

The payment went through, but no order was created: 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 created when the customer returns to the shop 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 Retry: the order was being confirmed by another request at the same moment, or the order could not be created (for example, the module is disabled). Wompi sends the event again later. Look at the Log field for the reason.

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: the transaction reference was not issued by this shop, for example the same Wompi account is used by another shop. References of other systems are answered with Ignored.

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

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 Wompi payment on hold: read the notes in the Wompi payment block (see Order statuses), then fulfil the order or refund the payment in the Wompi dashboard.

Other errors: look at the Log field on the module page and at the Wompi notes of the order. Errors are always logged. Turn on Debug log for more detail.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Wompi Payment 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 Wompi payment attempts and the order statuses Awaiting Wompi payment and Wompi payment on hold are always kept, so a late event of an old payment is still recognised after a re-install. Existing orders keep their payment notes and transaction IDs.

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