VibeFox OpenPay for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

HTTPS: your shop must use HTTPS, because the card form is on your checkout page.

OpenPay account: an OpenPay account from Mexico, Colombia or Peru. You need its Merchant ID, private key (sk_...) and public key (pk_...). The sandbox and production dashboards have different Merchant IDs and keys, and the module keeps them apart.

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

The card is typed on your checkout page, but it is read and tokenized in the browser by openpay.js. The card fields have no name and are never sent to your server. Because the card form is on your page, your PCI DSS scope is SAQ A-EP; ask your acquirer.

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 OpenPay 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. Choose the Account country and enter the sandbox and live keys (see Configuration).

5. Recommended: add the webhook URL in the OpenPay dashboard (see Configuration).

6. Turn on Enable / Disable and click Save. Test a payment with the OpenPay sandbox test cards, then turn off Sandbox mode to take real payments.

On install the module creates two order statuses, Awaiting OpenPay payment and OpenPay payment on hold. PrestaShop offers a new payment module for the currencies, countries and customer groups of your shop. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox OpenPay Gateway > Configure. Each section 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 incomplete (the payment method is then hidden at checkout), when the default currency of your shop is not accepted by the selected account country, and shows Sandbox mode is enabled — no real charges are made. while sandbox mode is on.

When you save, the keys are checked. A Merchant ID may contain only letters and digits, a private key must start with sk_ and a public key with pk_. An invalid value is not saved: the previous value is kept and an error is shown, for example Sandbox: The private key must start with sk_. If the payment method is enabled but the keys of the current mode are incomplete, you also see a message that the gateway stays hidden at checkout. An empty Title is refused with Enter a title for the payment method.

OpenPay

Enable / Disable: Enable OpenPay card payments 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: Credit or debit card (OpenPay). Required.

Description: the text shown above the card form at checkout. Default: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).

OpenPay account

The Merchant ID, private key (sk_) and public key (pk_) are in your OpenPay dashboard under Settings (Configuración). The section has links to the sandbox and production dashboards of Mexico, Colombia and Peru.

Account country: the country of your OpenPay account. It selects the OpenPay API, the openpay.js library of that country and the accepted currencies. Default: Mexico.

Sandbox mode: uses the OpenPay sandbox (test keys, no real charges) and switches both the keys and the API to the sandbox. A SANDBOX MODE badge is shown at checkout while it is on. Default: on. Turn it off to take real payments.

Sandbox Merchant ID: the Merchant ID from the sandbox dashboard, Settings (Configuración), API keys.

Sandbox Private Key: the sandbox private key. It starts with sk_. It is used only on the server; never share it.

Sandbox Public Key: the sandbox public key. It starts with pk_. openpay.js uses it in the browser to tokenize the card.

Live Merchant ID: the Merchant ID from the production dashboard, Settings (Configuración), API keys.

Live Private Key: the production private key (sk_...).

Live Public Key: the production public key (pk_...).

Saved private 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 secrets: tick a private key and click Save to remove it. An empty field keeps the saved value.

Webhook

The webhook is not required, but recommended. It confirms payments when the customer does not come back from the 3D Secure page, for example after closing the browser. In the OpenPay dashboard go to Settings > Webhooks and add the URL shown in Webhook URL in this section. With friendly URLs it looks like https://your-shop/module/wcp_openpay_gateway/webhook, possibly with a language code such as /en/. Copy it exactly as the settings show it. Add the webhook in the dashboard of each mode you use (sandbox and production).

When you add the webhook, OpenPay sends a verification code to this URL. The code appears in this section with the date it arrived, so you can confirm the webhook in the OpenPay dashboard.

Select these events (they are also listed in this section):

OpenPay does not sign webhooks, so the module never trusts the notification itself. It only uses it to find the charge, then reads the charge from the OpenPay API with the private key of the mode and account country the payment was made in. A notification for a charge this shop did not create is ignored. The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

Advanced

Debug log: logs the payment steps to logs/wc_opy_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings are logged even when it is off. Keys, card data and customer details 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 gateway settings, the stored webhook verification code and the logs. The OpenPay charge records of orders are payment history and are always kept, so orders can still be refunded after a re-install. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Credit or debit card (OpenPay)) and fills in Cardholder name, Card number, Expiry (MM/YY) and Card code (CVV). In sandbox mode the form shows SANDBOX MODE — Test environment. No real charges will be made. When the customer confirms, openpay.js turns the card into a one-time token in the browser, and the antifraud library adds a device session ID. Only these two values and the cart number are sent to your shop. An incomplete form shows Please fill in all card fields. under the form.

The module then creates the charge with 3D Secure for the cart total in the cart currency and sends the customer to the 3D Secure page of their bank, served by OpenPay. Each attempt gets its own OpenPay order reference. The charge description is Cart #, the cart number and your shop name. The customer's name, e-mail and phone are passed to OpenPay; no OpenPay customer account is created. No order exists yet at this point.

When the customer comes back, the module reads the charge from the OpenPay API. The order is marked paid only after OpenPay confirms it: the charge must belong to this cart, be completed and match the cart total and currency exactly. The order is then created and the customer sees the order confirmation page with Your card payment has been received. If OpenPay reports the charge as in progress, the order is created in Awaiting OpenPay payment and the page shows We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. If the result is not known yet, a Payment confirmation page shows the same text with a Check again button and a Back to checkout button; the webhook creates the order as soon as it arrives. If a charge in progress fails later, the order confirmation page shows Your OpenPay card payment was not completed. Please contact us about this order.

If the card is declined or 3D Secure fails, the customer is back at checkout with The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. and can pay again. The cart is kept. Before a new attempt, the module checks the previous charge of the cart: if it was in fact paid, the order is created from it without a second charge; if it is still in progress, the order is created in Awaiting OpenPay payment; if its state cannot be checked, no new charge is made and the customer sees We could not confirm the status of your previous payment attempt. Please try again in a few minutes. A cart that already has an order is never charged again.

Declined cards get a clear message, for example The card has insufficient funds. Please use another card., The card has expired. Please use another card. or The security code (CVV) is not valid. Please check it and try again. Technical errors of OpenPay are never shown to customers; they go to the log.

If a voucher in the cart stops being valid between the payment and its confirmation, it is removed from the order. The order then goes to OpenPay payment on hold with a note, because the customer paid the price with the discount.

The payment method is hidden at checkout when it is disabled, when the keys of the current mode are incomplete or when the cart currency is not accepted by the account country.

The module takes card payments only, captured immediately. It has no saved cards, subscriptions, months without interest (MSI) or installments, payment with card points, cash, SPEI, PSE or CoDi payments, and no separate authorize and capture.

Orders and refunds

Order statuses

No order yet: the customer is on the 3D Secure page, has not finished the payment, or the card was declined. Only the cart exists.

Payment accepted: the payment was confirmed. The payment is recorded with the OpenPay charge ID as the transaction ID, and a note shows the charge ID and the mode (live or sandbox).

Awaiting OpenPay payment: OpenPay reports the charge as in progress (not captured yet). The order moves to Payment accepted when the charge is completed, or to Payment error if it fails.

OpenPay payment on hold: OpenPay reports a completed charge with a different amount or currency than the cart (the order is not marked paid, the note shows the difference), a voucher was removed, or a payment arrived for an order that had already been cancelled or refunded (the payment is recorded). Check the order and fulfil it or refund the payment in the OpenPay dashboard.

Payment error: a charge in progress failed, was cancelled or expired.

Refunded: the charge was fully refunded through the module.

If a second completed charge arrives for an order that is already paid, the order is not changed. A note starting with WARNING asks you to refund the duplicate in the OpenPay dashboard.

OpenPay payment block

The order page shows an OpenPay payment block with the charge ID, the charge status, the environment and account country, the amount charged and the order total, the amount refunded, a Sandbox badge for sandbox payments, the refund history and the OpenPay notes of the order.

Refunds

For accounts from Mexico and Peru: in the OpenPay payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via OpenPay. Confirm the question Refund this amount through OpenPay? This cannot be undone. Full and partial refunds are supported, up to the amount OpenPay charged. You need the right to edit orders. The refund is sent with the keys of the mode and account country the charge was made in, so that mode's keys must be set: keep the sandbox keys while you may still refund sandbox orders. If OpenPay does not accept the refund, the block shows the error, for example OpenPay refund failed: ..., and no refund is recorded. A successful refund is added to the refund history and the notes with the OpenPay refund ID. A full refund sets the order to Refunded. A partial refund does not change the status. Refunds are available once OpenPay has confirmed the payment; an order on hold after an amount mismatch is not refunded through the module.

OpenPay Colombia does not support card refunds through the API, as in the official OpenPay plugins. For Colombian charges the block offers no refund form; refund the charge in the OpenPay dashboard.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through OpenPay.

Refunds and chargebacks made in the OpenPay dashboard arrive by webhook and are added to the notes once. The order status and credit slips are not changed automatically. Update them manually if needed.

License key

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

OpenPay does not appear at checkout: check that the license is active, Enable / Disable is on and the current mode has all three keys: the sandbox keys in sandbox mode, the live keys in live mode. Check that the cart currency is accepted by the Account country (Mexico: MXN, USD; Colombia: COP, USD; Peru: PEN, USD). The settings page shows a warning in each case. 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 customer did not come back from the 3D Secure page and the webhook is not working. Check that the webhook URL is added in the OpenPay dashboard of the mode you use, exactly as the settings show it, with the events listed above. Check that the keys of the mode the payment was made in are filled in: without them the webhook answers not configured and OpenPay retries later. The order is also created when the customer returns to the shop, or when the customer tries to pay the same cart again.

The webhook answers ignored (unknown order): the charge was not created by this shop, for example a charge from another shop on the same OpenPay account. Nothing is changed.

The webhook answers verification failed: the OpenPay API could not be reached to read the charge. OpenPay retries the webhook.

The webhook answers busy: the cart was being updated by another request at the same moment, or the order could not be created (for example, the module is disabled). OpenPay retries the webhook. Turn on Debug log to see the reason.

The customer sees The secure card form could not be loaded: openpay.js or the antifraud library of OpenPay did not load in the browser, or the device session ID could not be created. Ask the customer to reload the page and try again.

The customer sees The payment could not be processed right now: OpenPay rejected the request or did not answer. The reason is in the log. A wrong Merchant ID or private key is a typical cause. If OpenPay did not answer, check the OpenPay dashboard for the charge before the customer pays again.

The customer sees This test card cannot be used for real payments: a sandbox test card was used while sandbox mode is off.

Order is OpenPay payment on hold after payment: read the OpenPay notes in the block (see Order statuses), then fulfil the order or refund the payment.

Refund fails with a message about the mode: the order was paid in sandbox or live mode, and the keys of that mode are not set. Enter them and try again.

Refund fails with The order is being updated right now: a webhook or another request was updating the order at the same moment. Try again in a moment.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox OpenPay Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the gateway settings, the stored webhook verification code and the logs are removed. If it is off, all settings are kept for a later re-install. The OpenPay charge and refund records and the order statuses Awaiting OpenPay payment and OpenPay 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.

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