VibeFox OpenPay for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

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

PHP: 8.0 or later.

HTTPS: your site 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 plugin 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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_openpay_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > OpenPay > Manage, or click Settings under the plugin name on the Plugins page.

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

5. Choose the Account country and enter the sandbox and live keys (see Configuration).

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

7. Turn on Enable / Disable and save. Test a payment with the OpenPay sandbox test cards, then untick Sandbox mode to take real payments.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > OpenPay. 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 store currency is not accepted by the selected account country, and shows Sandbox mode is enabled — no real charges are made. while sandbox mode is on. In the list of payment methods, OpenPay is marked as needing setup until the current mode has all three keys, and a test mode badge is shown 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.

General

Enable / Disable: Enable OpenPay card payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Credit or debit card (OpenPay).

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: Use the OpenPay sandbox (test keys, no real charges) switches both the keys and the API to the sandbox. A SANDBOX MODE badge is shown at checkout while it is on. Default: on. Untick it 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_...).

Keys from version 1.0 of the plugin (one set of keys and a sandbox flag) are moved to the sandbox or live fields automatically.

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 this section of the settings. It looks like https://your-site/wc-api/webhook_wc_openpay/. 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:

OpenPay does not sign webhooks, so the plugin 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 the order was paid in. A notification for a charge this store did not create is ignored.

Advanced

Debug log: Log payment steps (errors are always logged) writes the payment steps to WooCommerce > Status > Logs, source wcp_openpay_gateway. Errors and warnings are logged even when it is off. Keys, card data and customer details are never logged. Default: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Default: off.

Checkout

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). When the order is placed, openpay.js turns the card into a one-time token in the browser, and the antifraud library of OpenPay adds a device session ID. Only these two values are sent to your store.

The plugin then creates the charge with 3D Secure for the order total in the order 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 order number and a short suffix). The charge description is Order #, the order number and your site name. The customer's name, e-mail and phone are passed to OpenPay; no OpenPay customer account is created. The order stays Pending payment while the customer is on the 3D Secure page.

When the customer comes back, the plugin reads the charge from the OpenPay API. The order is marked paid only after OpenPay confirms it: the charge must belong to this order, be completed and match the order total and currency exactly. If the result is not known yet, the order received page shows We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. The webhook then updates the order.

If the card is declined or 3D Secure fails, the customer comes back to the Pay for order page with the message The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. and can pay again. Before a new attempt, the plugin checks the previous charge of the order: if it was in fact paid, the order is marked paid without a second charge; if it is still processing, the customer sees that a previous payment is still being processed and should not pay again; if its state cannot be checked, no new attempt is made and the customer is asked to try again in a few minutes.

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 order notes and the log.

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). It is hidden at checkout when it is disabled, when the keys of the current mode are incomplete or when the order currency is not accepted by the account country.

The plugin 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

Pending payment: the customer is on the 3D Secure page or has not finished the payment. A note shows the charge ID.

Processing: the payment was confirmed. This is the standard WooCommerce status after payment; orders with only virtual downloadable products become Completed. The order note shows the charge ID and the mode (live or sandbox). The transaction ID is the OpenPay charge ID.

On hold: the charge is in progress and not captured yet; or OpenPay reports a completed charge with a different amount or currency than the order (the order is not marked paid, the note shows the difference); or a payment arrived for an order that had already been cancelled. Check the order in the OpenPay dashboard and fulfil it or refund the payment there.

Failed: the card was declined when the charge was created, or the latest attempt failed, was cancelled or expired. The customer can pay again.

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.

Refunds

For accounts from Mexico and Peru: open the order, click Refund, enter the amount and click Refund via Credit or debit card (OpenPay) (the button shows your payment method title). Full and partial refunds are supported. The refund is sent in the mode and account country the order was paid in, so keep the sandbox keys filled in while you still have sandbox orders to refund. If OpenPay does not accept the refund, WooCommerce shows the error, for example OpenPay refund failed: ..., and no refund is recorded. A successful refund is added to the order notes with the OpenPay refund ID.

OpenPay Colombia does not support card refunds through the API, as in the official OpenPay plugins. For Colombia the refund button is not offered; refund the charge in the OpenPay dashboard.

Refunds and chargebacks made in the OpenPay dashboard arrive by webhook and are added to the order notes once. They are not recorded as WooCommerce refunds automatically. If needed, create a manual refund in WooCommerce without the OpenPay button.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > OpenPay. 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, 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. 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, and refunds work.

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

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

The payment went through, but the order stays Pending payment: 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 order was paid in are filled in: without them the webhook answers not configured and OpenPay retries later.

The webhook answers ignored (unknown order): the charge was not created by this store for this order, 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 order was being updated by another request at the same moment. OpenPay retries the webhook.

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 order notes and in the log, source wcp_openpay_gateway. 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.

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

Order is On hold after payment: read the order note. The charge is still in progress, the paid amount or currency differed from the order, or the payment came after the order was cancelled.

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.

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, the stored webhook verification code and the logs of the plugin are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Order data is always kept: existing orders keep their payment notes, transaction IDs and the charge data needed for refunds after a re-install.

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