Volver

VibeFox Conekta 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 MXN or USD. For other currencies the payment method is hidden.

Conekta account: you need the private API keys of your Conekta account (test and live) and a webhook in the Conekta panel (see Configuration). Only the private keys are used. The public key is not needed, because the payment happens on the Conekta hosted checkout.

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-conekta-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/ConektaPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_ConektaPayment 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 Conekta Gateway. 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. Enter your test and live private keys and add the webhook in the Conekta panel (see Configuration). Set Enable to Yes and click Save Config. Test a payment in test mode, then set Test mode to No.

The module adds the Conekta 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 Conekta payment attempts and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Conekta Gateway, 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 an empty or too long Title; 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).

When you save the page while Conekta is enabled, Magento shows a warning if the private key of the current mode is empty: Conekta: enter the private key of the active mode, otherwise the payment method is hidden at checkout. While test mode is on, it also shows Conekta: test mode is on; no real money is charged. These messages follow the Default Config settings.

General

Enable: shows or hides Conekta at checkout. It is shown only when the private key of the current mode is set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Conekta. Required, at most 128 characters.

Description: shown in the payment method list at checkout when the customer selects Conekta. Default: Pay securely with card, OXXO cash or SPEI transfer. You will be redirected to Conekta to complete your payment.

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

Connection

Copy your private keys from the Conekta panel under Developers > API keys. Test and live keys are different.

Test private key: the private API key from the test mode of your Conekta account.

Live private key: the private API key from the production mode of your Conekta account. Keep it secret.

Test mode: new payments use the test private key. No real money is charged, and 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 private key.

Magento stores the 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.

Each Conekta order remembers its mode: notifications and refunds use the key of that mode. Keep both keys filled in while old test orders are still open.

Page

Payment Methods: the methods offered on the Conekta payment page. Default: card, cash and bank transfer. Cash, SPEI and BNPL are available for MXN orders only (USD orders get cards only) and must be enabled in your Conekta account.

Credit / debit card: card payment.
Cash (OXXO and other stores): the customer gets a reference and pays in cash at a store.
Bank transfer (SPEI): the customer gets a reference and pays by bank transfer.
Buy now, pay later (BNPL): payment through a BNPL option, if enabled in your Conekta account.

Orders

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

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

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

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

Advanced

Debug log: writes Conekta requests and notifications to var/log/wc_ckt_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged, even when this setting is No. API keys are never logged, e-mail addresses are masked and customer data from the requests is not written. 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 Conekta transactions and refunds always stay, so old orders can still be refunded. Default: No.

Webhook

The webhook tells your store about payments, for example OXXO or SPEI payments made after the customer left the Conekta page. The row Conekta portal URLs below the sections shows the Webhook URL. It is the storefront address of the default store view of the selected website (in the Default Config, of the default store view) and looks like https://your-store/wcpconektagateway/webhook/index. In the Conekta panel go to Developers > Webhooks and add this URL for test and for live mode. Copy the URL exactly as the settings show it.

Select the order events, for example:

order.paid: the order was paid.
order.pending_payment: the order is waiting for payment, for example an OXXO or SPEI reference was issued.
order.declined: the payment was declined.
order.expired: the checkout or payment reference expired.
order.canceled: the Conekta order was cancelled.
order.refunded: the payment was refunded, for example in the Conekta panel.
order.charged_back: the customer disputed the payment (chargeback); the module adds an order note.

The webhook body only tells the module which Conekta order changed. Every notification is verified by reading the order back from the Conekta API with the private key of its mode, set for the website where the order was placed; the webhook Digest signature header is not used. Notifications for Conekta orders that were not created by this store are acknowledged and ignored. Without the webhook, an order is confirmed only when the customer comes back to the store after paying, or on the next payment attempt for the same cart.

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 Conekta) and sees the description and the note You will be redirected to Conekta to complete the payment securely. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates a Conekta order for the order total in the order currency, with the products, discounts, tax and shipping, and sends the customer to the Conekta hosted checkout. The payment shows on the Conekta page as Order # and the order number. There the customer pays with one of the allowed methods.

After paying, the customer returns to your store. The order is marked paid only after Conekta confirms it: the module reads the order from the Conekta API when the webhook arrives and when the customer comes back. Magento then creates the invoice with the Conekta 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. A customer who comes back in another browser lands on the home page.

If the payment is not confirmed yet when the customer comes back, for example after an OXXO or SPEI reference was issued, the customer sees a short page Conekta has not confirmed your payment yet. Please do not pay again. with a Check again link. The order waits in Pending Payment until the webhook reports the payment. If the payment is pre-authorized, the amount does not match or a test payment arrived in live mode, the customer sees the success page with Your payment is being reviewed by the store.

If the payment was cancelled, declined or expired, the order is cancelled (the stock goes back), the cart is restored and the customer sees Your payment was cancelled, declined or expired. Please try again. When the customer pays again, an open Conekta checkout of the same order with the same amount is reused; otherwise the previous one is cancelled in Conekta before a new one is created, so an old link cannot be paid twice. If the previous checkout was already paid, that payment is confirmed instead of a new one.

If Conekta cannot start the payment, the order is cancelled, the cart is restored and the customer sees We could not start the Conekta payment. Please try again or choose another payment method. If the return link does not match the payment, the customer is back in the cart with We could not verify the Conekta payment.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), its open Conekta order is cancelled too, and an OXXO or SPEI reference issued for it can no longer be paid. If you accept OXXO or SPEI, set the lifetime long enough for the customer to pay.

The module works with the standard Magento checkout. It takes payments on the Conekta page only. It has no card form on your checkout page, no saved cards, subscriptions or recurring payments, and pre-authorized payments are captured in the Conekta panel, not in Magento. Conekta is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Conekta, but Conekta has not confirmed the payment yet, or the customer has not paid the OXXO or SPEI reference yet. There is no invoice. A note shows how the customer will pay, for example Conekta: awaiting payment via OXXO / cash. No invoice until Conekta confirms payment.

Processing: Conekta confirmed the payment with the same amount and currency. The invoice is created with the Conekta charge ID as the transaction ID, and a note shows the Conekta order, the charge and the payment method (for example the card brand and last four digits, OXXO / cash or SPEI transfer), and whether it was confirmed by the webhook or the customer's return.

On Hold after a pre-authorization: the payment is only pre-authorized. The note asks you to capture it in the Conekta panel. Before the hold the order is moved from Pending Payment to Processing, so Unhold returns it to Processing and the Pending Payment cron does not cancel it. When Conekta then reports the payment, the invoice is created, whether the order is still On Hold or already unheld; if the pre-authorization is cancelled, declined or expires at Conekta, the order is cancelled.

On Hold after a mismatch: the amount or currency received from Conekta does not match the order, or a test-mode payment arrived while the store is in live mode (no real money was collected). No invoice is created. Before the hold the order is moved from Pending Payment to Processing, so Unhold returns it to Processing and the Pending Payment cron does not cancel it. The note shows the amount received. Check the payment in the Conekta panel, then fulfil the order or refund the payment there.

Canceled: the payment was cancelled, declined or expired, the payment could not be started, or the order was cancelled in Magento. If a payment arrives later for a cancelled order, the order is not re-opened and no invoice is created: a note asks you to review it. Fulfil the order manually or refund the payment in the Conekta panel.

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

A paid or refunded order is never downgraded or re-opened. If another Conekta payment arrives for a cart that is already paid, a note asks you to refund the duplicate in the Conekta panel. The notes are order comments that the customer does not see.

Conekta payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, once Conekta has reported the payment, Conekta transaction (the Conekta order ID), Conekta status, Conekta amount and Conekta mode (test or live). 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 Conekta. 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 Conekta.

The refund is made in the order currency, up to the amount Conekta charged minus the amounts already refunded. It goes to the Conekta order that holds the payment and uses the key of the mode the payment was made in, so that key must be set. If Conekta does not accept the refund, Magento shows the error, for example Conekta rejected or could not complete the refund. Check the outcome in the Conekta panel before retrying., and the credit memo is not created. After a successful refund Magento records it on the order with the Conekta refund ID as the transaction ID. A full refund closes the order. Refunds are available once Conekta has confirmed the payment and the order has an invoice.

Refunds and chargebacks reported by Conekta arrive by the webhook and are added as a note with the amount refunded in Conekta and no credit memo was created automatically. The same note also appears after a refund made with a credit memo. Create 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 Conekta Gateway is the first row of the VibeFox Conekta Gateway 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-conekta 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, Conekta is not shown to customers at checkout. If a payment is started anyway, the order is cancelled, the cart is restored and the customer sees We could not start the Conekta payment. Please try again or choose another payment method. 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: 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: 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

Conekta does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the current mode has a private key: Test private key in test mode, Live private key in live mode. The currency the customer pays in must be MXN 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 webhook is not working. In the Conekta panel check that the webhook exists for the mode you use (test or live), that its URL is exactly the one shown in Conekta portal URLs and that the order events are selected. Check that the private key of that mode is set for the website of the order, because every notification is verified with it. The order is also confirmed when the customer returns to the store after paying, or when the customer tries to pay the same cart again.

Webhook answers Busy, retry later, Gateway not configured, Order unavailable, Status verification failed or Please retry later: the order was being processed by another request at the same moment, the private key of the payment's mode is missing, the Conekta API could not be reached, or an error occurred while the order was being updated. Conekta retries the webhook. Look at the debug log for the reason.

Webhook answers API verification failed, Reference mismatch, Invalid payload or Invalid order id: the Conekta API did not confirm the order, or the notification was not a valid Conekta order event.

Webhook answers Ignored or Unknown transaction: the notification belongs to a Conekta order that was not created by this store (for example another store or a payment link on the same account), or to another object than an order.

The webhook URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Conekta.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Conekta retries the webhook later, and the order is also confirmed when the customer returns.

The customer is back in the cart with We could not start the Conekta payment: the license is not active, the private key of the current mode is wrong or missing, Conekta rejected the order (for example the payment methods are not enabled in your Conekta account), or Conekta could not confirm a previous payment attempt of the same cart. Look at the debug log. The order of that attempt is cancelled.

An OXXO or SPEI order was cancelled before the customer paid: the Magento cron cancelled it after the Pending Payment Order Lifetime, and the Conekta order was cancelled with it. Increase the lifetime in Stores > Configuration > Sales > Sales > Orders Cron Settings.

Order is On Hold after payment: read the order notes (see Order statuses): the payment is only pre-authorized, the amount or currency did not match, or a test-mode payment arrived while the store is in live mode.

Refund fails with Conekta private key of the payment mode is not configured: the payment was made in test or live mode, and the private 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 (for example On Hold after a mismatch) cannot be refunded online; refund it in the Conekta panel.

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.

For developers, the README lists the Magento events wc_ckt_supported_currencies, wc_ckt_allowed_payment_methods, wc_ckt_order_request and wc_ckt_refund_reason.

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_ConektaPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_ConektaPayment to remove the data, then bin/magento module:disable Vibefox_ConektaPayment, delete the folder app/code/Vibefox/ConektaPayment 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 Conekta transactions and refunds 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.

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