VibeFox Culqi for Adobe Commerce — Ayuda

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

Currency: the currency the customer pays in must be Peruvian Sol (PEN) or US Dollar (USD). Culqi accepts no other currencies, and for other currencies the payment method is hidden.

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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-culqi-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/CulqiPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_CulqiPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Culqi Payment. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Paste the integration keys and, for real payments, the production keys (see Configuration). Set Enable to Yes and click Save Config. Keep Test mode on Yes while you test, then set it to No to take real payments.

The module adds the Credit/Debit Card or Yape (Culqi) payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Culqi charges and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Culqi Payment, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: Enter a title for the payment method (1 to 128 characters). for a Title longer than 128 characters; Sort order must be a whole number.; Order total must be a number, 0 or greater. for Minimum Order Total or Maximum Order Total (use a point as the decimal separator, for example 9.99).

Some values are refused without stopping the save: the other fields are saved and the old value of that field is kept. An empty Title keeps the previous title with the warning Culqi: enter a title — the previous title was kept. A key with the wrong prefix or with characters other than letters, digits and _ keeps the previous key with a warning that names the field by its code, for example Culqi: live_secret_key must start with sk_live_ — the previous value was kept.

When you save the page while Culqi is enabled, Magento shows Culqi test mode is active: no real money is charged. while test mode is on, the warning Culqi is enabled but the keys of the active mode are missing, so it is hidden at checkout. when a key of the current mode is missing, and Culqi accepts PEN and USD only. when the default display currency is neither PEN nor USD. These messages follow the Default Config settings.

General

Enable: shows or hides Culqi at checkout. It is shown only when both keys of the current mode are set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit/Debit Card or Yape (Culqi). Required, at most 128 characters.

Description: shown in the payment method list at checkout when the customer selects Culqi. Default: Pay securely with your credit/debit card or Yape via Culqi.

Sort order: the position among the payment methods at checkout. A whole number. Default: 0.

Connection

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.

Test mode: when Yes, new payments use the test keys (pk_test_ / sk_test_) and no real money is charged. Customers see TEST MODE: no real money is charged. under the payment method. Default: Yes. Set it to No 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 sent to 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 sent to the browser.

Magento stores the secret keys encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete a saved key, clear the field and click Save Config. The public keys are not secret and are shown as saved.

Each payment remembers its mode: refunds use the secret key of the mode the payment was made in. Keep both secret keys filled in while old test payments may still be refunded.

Page

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

Offer Yape in the Culqi popup: shows Yape next to cards in the Culqi window. When it is No, Yape payments are refused. Default: Yes.

Orders

Payment from Applicable Countries: All Allowed Countries offers Culqi for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Culqi only for billing addresses in these countries.

Minimum Order Total: offer Culqi only from this order total, in the base currency of your store. 0 or empty means no minimum.

Maximum Order Total: offer Culqi only up to this order total, in the base currency. 0 or empty means no maximum.

Advanced

Debug log: writes API requests and payment steps to var/log/culqi_p_debug.log.php in the Magento folder. The file cannot be opened from the web, and it is rotated at 5 MB. Errors, including card declines with their code, are always logged, even when this setting is No. Secret keys and payment tokens are never logged, and e-mail addresses are masked. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The Culqi charge and refund records always stay, so old orders can still be refunded. Default: No.

Debug log

The last row of the group shows the size and the latest entries of the log. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Credit/Debit Card or Yape (Culqi)) and sees the description and the note Complete your payment in the Culqi popup after placing the order. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet.

The customer then sees the store page Complete payment with Culqi with the amount and the currency, and the buttons Pay with Culqi and Cancel and return to cart. Pay with Culqi opens the Culqi Checkout popup 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. The customer never leaves your store, and card data never reaches your server. The Culqi scripts are loaded only on this page.

Culqi turns the payment data into a single-use token, and the token is sent to your store. Your server creates the charge with the Culqi Charges API for the order total in the order currency, captured immediately. The amount sent by the browser is not used. The charge shows in CulqiPanel as Order and the order number, with the customer's e-mail. The order is marked paid only after Culqi confirms it: when Culqi answers with a successful charge of the same amount and currency, Magento creates the invoice with the Culqi charge ID as the transaction ID, the order becomes Processing and the order e-mail is sent. The customer sees the standard order success page.

If the bank requires 3-D Secure, the customer sees Your bank requires additional verification (3-D Secure). and the Culqi 3-D Secure window opens. After the authentication the charge is sent again automatically with the same token. If the verification is not completed or not accepted, the customer sees The 3-D Secure verification was not accepted. Please try again.

If the card is declined, the customer sees the message from Culqi, or Payment failed. Please try again or contact support., and can try again with another card. If the customer closes the Culqi window, nothing is charged and the customer can click Pay with Culqi again. In these cases the order stays in Pending Payment and can still be paid. Cancel and return to cart cancels the order (the stock goes back) and restores the cart.

If Culqi does not answer clearly, the customer sees We could not confirm your payment with Culqi. Please contact us before trying again. The order gets a note with the cart number, and the module does not charge this order again until you have checked the charge in CulqiPanel. An order is never charged twice: a second click, a second tab or a retry of an already confirmed charge does not create a new charge. If another order of the same cart already has a Culqi payment, the customer sees This cart already has a payment. Please contact the store before trying again.

Unpaid orders stay in Pending Payment until the customer pays or cancels them, or until Magento cancels them after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings).

The module works with the standard Magento checkout. It takes one-time card and Yape payments only, captured immediately. It has no PagoEfectivo or CIP codes, bank apps, agents, wallets or Cuotéalo, no saved cards, subscriptions or installments, no Culqi webhooks and no separate authorize and capture. Culqi is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed, but Culqi has not confirmed a charge yet: the customer has not paid, closed the Culqi window, the card was declined, or Culqi did not answer clearly. There is no invoice.

Processing: Culqi confirmed the charge with the same amount and currency. The invoice is created with the Culqi charge ID (chr_...) as the transaction ID, and a note shows the charge and the mode (test or live).

On Hold after a mismatch: the charge amount or currency does not match the order, or the payment was not captured. No invoice is created. The note shows the charge ID, the amount and whether it was captured. Check the charge in CulqiPanel, then fulfil the order or refund the payment (see Refunds).

Canceled: the customer clicked Cancel and return to cart, or the order was cancelled in Magento. If a charge is reported for an order that is no longer waiting for payment, the order is not re-opened and no invoice is created: a note asks you to review it.

Closed: the payment was fully refunded with a credit memo.

The notes are order comments that the customer does not see.

Culqi payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, once Culqi has charged the payment, Culqi charge, Environment (test or live), Charged minor amount (the amount in cents), Currency, Captured and 3-D Secure (1 for yes, 0 for no). The customer sees only the payment method title. The information is shown for old orders too, also when the payment method is disabled.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Culqi. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Culqi.

The refund is made in the order currency, up to the amount Culqi charged minus the amounts already refunded. It uses the secret key of the mode the payment was made in (test or live), even if you have switched mode since, so that key must be set. Refunds work also when the payment method is disabled. If Culqi does not accept the refund, Magento shows the error, for example Culqi refund failed: followed by the reason, and the credit memo is not created. After a successful refund Magento records it on the order with the Culqi refund ID as the transaction ID. A full refund closes the order.

If the outcome of a refund is unknown, for example Culqi did not answer, no credit memo is created and further online refunds of that order are refused with Culqi refund outcome is uncertain. Check CulqiPanel before retrying. Check the refund in CulqiPanel, finish it there if needed and record it with a credit memo with Refund Offline.

Culqi payment review: an order on hold after a mismatch has no invoice, so it cannot get a credit memo. If the charge was captured, the order page shows the block Culqi payment review with the amount actually charged and the amount still refundable. Enter the Refund amount (the refundable amount is filled in) and optionally a Reason (private order note), then click Refund reviewed Culqi payment. The money is sent back through Culqi in the currency it charged, and a note with the Culqi refund ID, the amount and your reason is added to the order. No credit memo is created: resolve the held order yourself. The block and the refund need the Admin permission for credit memos.

Refunds made in CulqiPanel are not synced back to Magento. Record them with a credit memo with Refund Offline or 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 row of the VibeFox Culqi Payment group in Stores > Configuration > Sales > Payment Methods, 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 store. Below them are the line Product: magento-payment-culqi and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store 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. and no charge is made. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: refunds and the payment information of old orders work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Culqi does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that 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). The currency the customer pays in must be PEN or USD and the order total above 0. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: the module does not use webhooks. The charge is confirmed only by the answer of Culqi to your server. If Culqi did not answer clearly, the order has the note Culqi did not confirm the charge. Check CulqiPanel using cart_id with the cart number, and the module log says Unconfirmed charge. Find the charge with this cart_id or the order number in CulqiPanel, then fulfil the order manually or refund the charge in CulqiPanel. The module does not charge this order again.

Order is On Hold after payment: read the note in the order. 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 fulfil the order or refund the payment in the Culqi payment review block.

The key is not saved: the warning 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.: Culqi rejected the secret key of the current mode. 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 payment page was open. The customer should reload the page and pay again.

The customer sees Culqi could not be loaded. Please try again.: the Culqi scripts did not load. Check that scripts from js.culqi.com and 3ds.culqi.com are not blocked on the payment page, for example by a cache or optimization module.

The customer sees Invalid payment session. Please return to your cart.: the payment page was opened in another session or the session expired. The customer should start again from the cart.

The customer sees a Payment unavailable page: after Place Order the payment could not start, for example because the license is no longer active, the payment method was disabled, the keys of the current mode are missing or the currency is not PEN or USD. The order stays in Pending Payment until Magento cancels it after the Pending Payment Order Lifetime, or until you cancel it.

The customer sees Payment is busy. Please wait and try again.: another payment request for the same cart was running at the same moment. The customer should wait a moment and try again.

A card was declined and you want the reason: look at the Debug log row at the end of the settings. Declines are logged with the Culqi decline code even when Debug log is No.

Refund fails with Culqi secret key of the payment environment is missing.: 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 Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (On Hold after a mismatch) is refunded in the Culqi payment review block.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_CulqiPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_CulqiPayment to remove the data, then bin/magento module:disable Vibefox_CulqiPayment, delete the folder app/code/Vibefox/CulqiPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The Culqi charge and refund records are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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