VibeFox Culqi for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

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

PHP: 8.0 or later.

Store currency: Peruvian Sol (PEN) or US Dollar (USD). Culqi accepts no other currencies, and the payment method is hidden at checkout for any other store currency.

Culqi account: you need the public key and the secret key of your Culqi account. Integration (test) keys come from integ-panel.culqi.com, production (live) keys from mipanel.culqi.com, in CulqiPanel > Desarrollo > API Keys. The public key is used by the Culqi popup in the browser. The secret key is used only on your server and is never sent to the browser. No webhook is needed.

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_culqi_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Culqi > 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. Paste the integration keys and, for real payments, the production keys (see Configuration).

6. Turn on Enable/Disable. Keep Test Mode on while you test, then untick it to take real payments.

7. Make sure the store currency is PEN or USD.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Culqi. Above the fields the page shows Test mode is active: the integration keys are used and no real money is charged. while test mode is on. It warns you when the gateway is enabled but the keys of the current mode are missing, and when the store currency is not supported by Culqi. In both cases the payment method is hidden at checkout. In the list of payment methods, Culqi is marked as needing setup until both keys of the current mode are set.

General

Enable/Disable: Enable Culqi Payment Gateway turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Credit/Debit Card or Yape (Culqi).

Description: the text shown under the payment method at checkout. Default: Pay securely with your credit/debit card or Yape via Culqi.

API keys

Copy the keys from CulqiPanel > Desarrollo > API Keys: integration (test) keys in integ-panel.culqi.com, production keys in mipanel.culqi.com. Test mode uses only the test keys, live mode only the live keys. Each key must start with the prefix of its field. A key with the wrong prefix is not saved: the page shows an error and keeps the previous value.

Test Mode: Use the Culqi integration (test) environment. When on, the test keys (pk_test_ / sk_test_) are used and no real money is charged. Default: on. Untick it to take real payments with the live keys.

Test Public Key: the public key of the integration environment. It starts with pk_test_.

Test Secret Key: the secret key of the integration environment. It starts with sk_test_ and is never shared with the browser.

Live Public Key: the public key of the production environment. It starts with pk_live_.

Live Secret Key: the secret key of the production environment. It starts with sk_live_ and is never shared with the browser.

If you update from version 1.0, the single key pair of that version is moved to the test or live fields by its prefix. Check the keys after the update.

Payment methods

Cards are always offered. Bank transfer, agents, wallets and Cuotéalo need the Culqi Orders API and are not offered by this plugin.

Yape: Offer Yape in the Culqi popup shows Yape next to cards in the Culqi window. Default: on.

Advanced

Debug log: Log API requests and payment steps writes details to WooCommerce > Status > Logs, source wcp_culqi_payment. Errors are always logged. Keys, card data and customer details are never logged. Default: off.

Delete Data on Uninstall: Delete the gateway settings and logs when the plugin is deleted. Deactivating the plugin never deletes anything. Culqi data saved on orders is always kept. Default: off.

Checkout

The customer chooses the payment method (by default Credit/Debit Card or Yape (Culqi)) and clicks the place order button. The Culqi Checkout popup opens on the same page with your store name, the order total and the currency. There the customer enters the card details or pays with Yape. While test mode is on, the payment method shows TEST MODE: No real charges will be made.

Culqi turns the payment data into a single-use token, and the checkout is sent to your store with that token. Your server creates the charge with the Culqi Charges API for the order total in the order currency, with the order number in the charge description. The order is marked paid only after Culqi confirms the charge and the charged amount and currency match the order. Then the customer goes to the order received page.

If the bank requires 3-D Secure, the customer sees Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. After the authentication the charge is sent again automatically. If the verification is not completed, the customer sees The 3-D Secure verification was not completed. Please try again or use another card.

If the card is declined, the customer sees the message from Culqi, for example Payment failed: followed by the reason, and can try again with another card. If Culqi does not answer, the customer sees We could not confirm your payment with Culqi. Please check your email or contact us before trying again. If the customer closes the Culqi window, nothing is charged, the customer sees The payment window was closed before the payment was completed. and can place the order again.

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

The plugin takes one-time card and Yape payments only, captured immediately. It has no PagoEfectivo or CIP codes, bank app, agents, wallets or Cuotéalo, no saved cards, subscriptions or installments, no Culqi webhooks and no separate authorize and capture.

Orders and refunds

Order statuses

Pending payment: the order was created but not charged yet, or Culqi did not answer. In that case a note says Culqi did not confirm the charge. Check CulqiPanel for a charge of this order before you accept another payment.

Processing: the payment was confirmed (the WooCommerce default; orders with only virtual downloadable products become Completed). The order note shows the Culqi charge ID, the mode (test or live) and whether 3-D Secure was used. The transaction ID is the Culqi charge ID.

On hold: Culqi reported a charge whose amount or currency does not match the order, or a payment that was authorized but not captured. The order note explains it and shows the charge ID. Check the charge in CulqiPanel and complete or refund the order manually.

Failed: the card was declined. The order note shows the reason, the decline code and the charge ID. The customer can pay again with another card.

An order that is already paid or already has a Culqi charge, including an order on hold, is never charged again. Only one payment request per order is processed at a time.

Refunds

Open the order, click Refund, enter the amount and click Refund via Culqi. Full and partial refunds are supported. The refund is sent with the keys of the mode the payment was made in (test or live), even if you have switched mode since, so that mode's secret key must be set. If Culqi does not accept the refund, WooCommerce shows the error and no refund is recorded. A successful refund is added to the order notes with the Culqi refund ID, the amount and the reason.

Refunds made in CulqiPanel are not synced back to WooCommerce. If needed, create a manual refund in WooCommerce without Refund via Culqi.

License key

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

Culqi does not appear at checkout: check that the license is active, Enable/Disable is on, both keys of the current mode are set (Test Public Key and Test Secret Key in test mode, Live Public Key and Live Secret Key in live mode) and the store currency is PEN or USD. The settings page shows a warning in each of these cases.

The payment went through, but the order stays Pending payment: the plugin does not use webhooks. The charge is confirmed only by the answer of Culqi to your server. If Culqi did not answer in time, the order note says Culqi did not confirm the charge. Find the charge of this order in CulqiPanel and, if it exists, complete the order manually.

Order is On hold after payment: read the order note. The charged amount or currency differed from the order, or the payment was not captured. Check the charge in CulqiPanel (its ID is in the note), then complete or refund the order.

The key is not saved: the error says that the field must start with a prefix, for example sk_live_. Each field accepts only keys of its own type and mode: pk_test_, sk_test_, pk_live_ or sk_live_.

The customer sees Payment gateway misconfiguration. Please contact the store owner.: the keys of the current mode are missing, or Culqi rejected the secret key. Check the keys in the settings.

The customer sees Payment token is invalid. Please try again.: the token from the Culqi window belongs to the other mode, for example after switching Test Mode while the checkout page was open. The customer should reload the page and pay again.

The Culqi window does not open: the customer sees The Culqi payment window could not be loaded. Please reload the page and try again. Check that scripts from js.culqi.com and 3ds.culqi.com are not blocked on your checkout page, for example by an optimization plugin.

The customer sees This order is already being paid: another payment request for the same order was running at the same moment. The customer should wait and check the e-mail before trying again.

Refund fails with a message about the keys: the payment was made in test or live mode, and the secret key of that mode is not set. Enter it 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.

For developers, the plugin documentation lists the filters culqi_p_supported_currencies, culqi_p_charge_data, culqi_p_icon and culqi_p_lock_timeout.

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 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 and transaction IDs.

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