VibeFox Culqi for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

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

Shop currency: Peruvian Sol (PEN) or US Dollar (USD). Culqi accepts no other currencies, and the payment method is shown only for carts in PEN or USD.

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 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 Culqi 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 integration keys and, for real payments, the production keys (see Configuration).

5. Turn on Enable/Disable and click Save. Keep Test Mode on while you test, then turn it off to take real payments.

6. Make sure PEN or USD is an active currency of your shop.

On install the module creates the order status Culqi payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Culqi Payment > Configure. Each section has its own Save button, which saves the whole page. 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 no shop currency is supported by Culqi. In both cases the payment method is hidden at checkout. If your default currency is not PEN or USD, the page notes that Culqi is offered only for carts in the supported currencies.

Culqi

Enable/Disable: Enable Culqi Payment Gateway 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/Debit Card or Yape (Culqi). Required.

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, for example Live Secret Key must start with sk_live_ — the previous value was kept., and the other fields are saved.

Test Mode: when on, the test keys (pk_test_ / sk_test_) are used and no real money is charged. Default: on. Turn it off to take real payments with the live keys. While it is on, customers see TEST MODE: No real charges will be made. under the payment method.

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.

Saved secret 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 secret keys: tick Test Secret Key or Live Secret Key and click Save to remove it. An empty field keeps the saved value.

Payment methods

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

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

Advanced

Debug log: logs API requests and payment steps to logs/culqi_p_debug.log.php in the module folder. The file cannot be opened from the web. Errors, including card declines with their code, are always logged. 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 Culqi charge and refund records of the module and the log. The order status and the Culqi data on orders (payments, notes) are always kept. Default: off.

Checkout

At the payment step 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 shop name, the cart total and the currency. There the customer enters the card details or pays with Yape. The Culqi scripts are loaded only on the checkout page.

Culqi turns the payment data into a single-use token, and the token is sent to your shop. Your server creates the charge with the Culqi Charges API for the cart total in the cart currency, captured immediately. The charge shows in CulqiPanel as Cart and the cart number, with the customer's e-mail. No order exists before this point. The order is marked paid only after Culqi confirms it: the order is created when Culqi answers with a successful charge, and the customer sees the standard order confirmation 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 cart is kept in all these cases. Failed attempts are written to the module log, because no order exists yet.

A cart is never charged twice. If the customer submits again while a payment of the same cart is running, the customer sees This order is already being paid. Please wait a moment and check your email before trying again. If Culqi took the money but the order could not be created, the customer sees Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. The charge is kept, and the next attempt creates the order from it without a new charge.

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

No order yet: the card was declined, the customer closed the Culqi window, or Culqi did not answer. Only the cart exists. The module log has the details.

Payment accepted: the charge was confirmed and matches the cart. The payment is recorded with the Culqi charge ID (chr_...) as the transaction ID, and a note shows the mode (test or live) and whether 3-D Secure was used.

Culqi payment on hold: Culqi reported a charge whose amount or currency does not match the cart, or a payment that was authorized but not captured. The note explains it and shows the charge ID. A captured charge in the cart currency is recorded as a payment of the amount actually charged. Check the charge in CulqiPanel, then fulfil the order or refund the payment.

Refunded: the payment was fully refunded through the module.

If a second charge arrives for a cart that already has an order, the order is not changed. A note asks you to check the charge in CulqiPanel and refund it if needed.

Culqi payment block

The order page shows a Culqi payment block with the charge ID, the charged amount (with 3-D Secure if used), a Test badge for test payments, a review hint for orders on hold, the amounts paid and refunded, and the refund history.

Refunds

In the Culqi payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Culqi. Confirm the question Refund this amount through Culqi? This cannot be undone. Full and partial refunds are supported. You need the right to edit orders; access to the modules is not needed. Refunds are made in the amount and currency Culqi charged, so after an amount mismatch you can refund up to what the customer actually paid, not the order total. 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, the block shows the error and no refund is recorded. A successful refund is added to the refund history and the order notes with the Culqi refund ID, the amount and your reason. A full refund sets the order to Refunded. A partial refund does not change the status.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Culqi. Refunds made in CulqiPanel are not synced back to PrestaShop. Update the order manually if needed.

License key

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

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 cart currency is PEN or USD. The settings page shows a warning when the keys are missing. 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 module 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 module log says Culqi did not confirm the charge with the cart number. Find the charge with this cart_id in CulqiPanel. If the customer saw the message that the order could not be completed, the next payment attempt of the same cart creates the order without charging again.

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

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 a cache or optimization module.

The customer sees Security check failed. Please reload the page and try again.: the checkout page was open too long or in another session. Reloading the page fixes it.

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

A card was declined and you want the reason: look at the Log field on the module page. Declines are logged with the Culqi decline code even when Debug log is off.

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.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Culqi Payment 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 Culqi charge and refund records of the module and the log are removed. Orders paid before can then no longer be refunded from the order page. If it is off, everything is kept for a later re-install. The order status Culqi payment on hold is always kept. Existing orders keep their payment notes and transaction IDs.

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