VibeFox OpenPay for Adobe Commerce — Допомога

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.

HTTPS: your store should use HTTPS, because the card form is on your checkout page and the webhook endpoint you add in the OpenPay dashboard is an HTTPS address.

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 module 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 OpenPay library of your account country. The card number and security code go only to OpenPay; your store receives a one-time token and a device session ID. Because the card form is on your page, your PCI DSS scope is SAQ A-EP; ask your acquirer.

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

2. Run bin/magento module:enable Vibefox_OpenpayPayment 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 OpenPay 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. Choose the Openpay account country, enter the sandbox and live keys and add the webhook in the OpenPay dashboard (see Configuration). Set Enable Openpay to Yes and click Save Config. Test a payment in test mode with the OpenPay sandbox test cards, then set Test Mode to No to take real payments.

The module adds the Credit or debit card (OpenPay) payment method to the Magento checkout. It is off after installation (Enable Openpay = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the OpenPay payment attempts and for refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox OpenPay Gateway, in the standard Magento configuration form. All fields are in one group, in the order below. 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. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title of 1 to 128 characters.); a Sort order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be zero or greater.).

The keys are checked when you save. A merchant ID may contain only letters and digits, a private key must start with sk_ and a public key with pk_. An invalid key is not saved: the previous value is kept, the other fields are saved, and Magento shows Invalid Openpay credential. Previous value was kept; other valid fields were saved.

When Enable Openpay is Yes, the Webhook and payment status row also shows warnings: Enter all three credentials for the active environment. The method stays hidden until configured. when a key of the current mode is missing, Store currency is not supported for the selected Openpay country. and, while test mode is on, Test mode: no real payment is taken.

General

Enable Openpay: shows or hides the payment method at checkout. It is shown only when the merchant ID, private key and public key of the current mode are all set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. In test mode the module adds (TEST MODE) after it. Default: Credit or debit card (OpenPay). Required, at most 128 characters.

Description: the text shown above the card form when the customer selects the payment method. Default: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).

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

OpenPay account

The merchant ID, private key (sk_) and public key (pk_) are in your OpenPay dashboard, in the API keys of the account settings. Sandbox and production have separate keys. Test mode uses only the test keys, live mode only the live keys.

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

Test Mode: uses the OpenPay sandbox: the test keys and the sandbox API, no real charges. Default: Yes. Set it to No to take real payments. While it is on, customers see Test mode: no real payment is taken. under the description, and the payment method title ends with (TEST MODE).

Test merchant ID: the merchant ID from the sandbox dashboard.

Test private key: the sandbox private key. It starts with sk_. It is used only on the server; never share it.

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

Live private key: the production private key (sk_...).

Live public key: the production public key (pk_...).

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

Conditions

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

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

Minimum Order Total: offer OpenPay only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer OpenPay only up to this order total, in the base currency. Empty means no maximum.

The payment method is also hidden when the currency of the cart is not accepted by the Openpay account country.

Webhook

The webhook confirms payments when the customer does not come back from the 3D Secure page, for example after closing the browser. The Webhook and payment status row shows the webhook URL. It is the storefront address of the default store view and looks like https://your-store/wcpopenpaygateway/webhook/index/. Copy the URL exactly as the settings show it and add it as a webhook in the OpenPay 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 the same row as Webhook verification code, so you can confirm the webhook in the OpenPay dashboard.

The module processes these events:

OpenPay does not sign webhooks, so the module never trusts the notification itself. It only uses it to find the payment attempt, then reads the charge from the OpenPay API with the private key of the mode and account country the payment was made in. Other events, non-card payments and charges this store did not create are ignored. The webhook also works when Enable Openpay is No, as long as the keys of the payment's mode are set.

Advanced

Debug Log: also writes the payment steps to var/log/wc_opy_debug.log.php in the Magento folder. Errors and warnings are written even when it is off. The file cannot be opened from the web and is rotated at 5 MB. Keys, card data and customer details are not logged. Default: No.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings (including the stored webhook verification code), the module cache and the log (see Uninstall). The license key is always removed. The charge and refund history always stays, so old orders can still be refunded. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Credit or debit card (OpenPay)) and fills in Cardholder name, Card number, Expiry month, Expiry year and Security code. When the customer clicks Place Order, openpay.js turns the card into a one-time token in the browser, and the OpenPay antifraud library adds a device session ID. Only these two values reach your store; they are stored encrypted and deleted from the order when the payment starts. If the card cannot be tokenized or the OpenPay library does not load, the customer sees The card could not be validated. Check its details and try again. and no order is placed.

Magento then places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module 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 charge description is Order #, the order number and your store name. The customer's name, e-mail and phone are passed to OpenPay; no OpenPay customer account is created.

When the customer comes back, the module reads the charge from the OpenPay API. The order is marked paid only after OpenPay confirms it: the charge must belong to this payment attempt, be completed and match the order total and currency exactly. Magento then creates the invoice with the OpenPay charge ID, the order goes to Processing and the order e-mail is sent. The customer sees the standard order success page. If the payment needs your review, the success page shows Your Openpay payment requires review. Do not pay again. If OpenPay has not finished the payment yet, a Payment confirmation page shows Your payment is being confirmed. Do not pay again until its status is known. with a Check again link; the webhook confirms the order as soon as it arrives. A customer who comes back in another browser lands on the home page.

If the card is declined or 3D Secure fails, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with a short message, for example The card has insufficient funds. Please use another card., The card has expired. Please use another card., The security code (CVV) is not valid. Please check it and try again., 3-D Secure authentication failed. Please try again or use another card. or Your card was declined. Please try another card or payment method. The customer can then pay again with a new order. Technical errors of OpenPay are never shown to customers; they go to the log.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees Openpay could not start payment. Please check your order before retrying. This also happens when the settings or the mode were changed between Place Order and the start of the payment.

A cart is never charged twice. Before a new attempt for the same cart, the module checks the previous charge with OpenPay. If the previous charge is paid, in progress or its outcome is unknown, no new charge is made. If OpenPay does not answer when the charge is created, the order is put On Hold with the note Openpay creation outcome is unknown. Do not pay again; check the dashboard or wait for a verified webhook. A verified webhook from OpenPay later confirms or cancels it.

The module works with the standard Magento checkout. It takes one-time card payments only, captured immediately. It has no saved cards, subscriptions, months without interest (MSI) or installments, card points, cash, SPEI, PSE or CoDi payments, and no separate authorize and capture. OpenPay 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 3D Secure, but OpenPay has not confirmed the payment yet. There is no invoice.

Processing: the payment was confirmed. The invoice is created with the OpenPay charge ID as the transaction ID, and a note shows the charge and how it was confirmed (checkout, return, webhook or sync).

On Hold: the outcome of the charge creation is unknown, OpenPay reported a different amount or currency than the order (Openpay amount or currency differs from the order. Do not pay again; review and refund the actual charge if needed.), a second payment arrived for the same cart, the 3D Secure address from OpenPay was not valid, or OpenPay returned a status the module does not know. No invoice is created. Check the charge in the OpenPay dashboard, then fulfil the order or refund the payment.

Canceled: the card was declined, 3D Secure failed, the charge failed, was cancelled or expired, the payment could not be started, or the order was cancelled in Magento. If money still arrives for a cancelled or closed order, the order is not reopened; a note asks you to review the payment in the OpenPay dashboard.

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

The notes are order comments that the customer does not see. Refunds and chargebacks made in the OpenPay dashboard arrive by webhook and add the note Openpay dashboard status: with the status, once per status. They do not create credit memos and do not change a paid order. A refund made through the module does not add this note again.

OpenPay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Openpay charge (the charge ID), Environment (sandbox or live), Openpay account country and Payment reference. Below the order, the VibeFox OpenPay Gateway section lists every payment attempt with the charge, environment and country, status and the actual amount and amount refunded, and the refund history. It is shown also when Enable Openpay is No.

Sync payment status reads the charge from OpenPay again with the mode and account country of the payment and adds a note with the result. It needs the right to edit orders.

Refunds

For accounts from Mexico and Peru: 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 OpenPay. Full and partial refunds are supported. The credit memo comment is sent to OpenPay as the refund description. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through OpenPay.

Before each refund the module reads the charge from OpenPay again. The refund is made in the order currency, up to the amount OpenPay charged minus the amounts already refunded, with the keys of the mode and account country the payment was made in, so that mode's keys must be set. If OpenPay does not accept the refund, Magento shows the error and the credit memo is not created, for example Openpay refund failed. Check the dashboard before retrying. or Refund exceeds the actual remaining Openpay charge. After a successful refund Magento records it with the OpenPay refund ID as the transaction ID. A full refund closes the order. If the result of a refund is not clear, further refunds of the order are blocked with An earlier refund requires manual reconciliation before another refund. until you check it in the OpenPay dashboard, so money is never refunded twice.

OpenPay Colombia does not support card refunds through the API. For charges of a Colombian account the credit memo offers only Refund Offline; refund the charge in the OpenPay dashboard. This follows the country of the payment, also after you change Openpay account country.

Refund of a charge under review: an order On Hold after a mismatch has no invoice, so it cannot be refunded with a credit memo. For such a charge (Mexico and Peru) the VibeFox OpenPay Gateway section shows a form: enter the amount and a reason and click Refund actual charge. The money is refunded through OpenPay, up to the amount actually charged, and a note asks you to update the Magento order manually. The order keeps its current state. This form needs the right to edit orders and to create credit memos.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox OpenPay Gateway is the first row of the VibeFox OpenPay 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-openpay 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, OpenPay is not shown to customers at checkout. If a payment is started anyway, no charge is made: the order is cancelled, the cart is restored and the customer sees Openpay could not start payment. Please check your order before retrying. 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

OpenPay does not appear at checkout: check that the license is active and Enable Openpay is Yes for the website of the store, and that the current mode has all three keys: the test keys in test mode, the live keys in live mode. Check that the cart currency is accepted by the Openpay account country (Mexico: MXN, USD; Colombia: COP, USD; Peru: PEN, USD). The Webhook and payment status row shows a warning in both cases. 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 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, and that the keys of the mode the payment was made in are set for the website of the order. You can also click Sync payment status on the order page.

The webhook answers ignored unknown order: the charge was not created by this store, for example a charge from another store on the same OpenPay account. Nothing is changed.

The webhook answers retry (HTTP 503): the OpenPay API could not be reached to read the charge, the keys of the payment's mode are missing, or the cart was being updated by another request at the same moment. OpenPay retries the webhook. Turn on Debug Log to see the reason.

The webhook answers foreign or invalid charge (HTTP 400): the charge in the notification does not match the payment attempt of this store or does not exist in OpenPay. Nothing is changed.

The webhook URL shows POST required in the browser: this is normal. The URL accepts only notifications from OpenPay.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. OpenPay retries the webhook later, and the order is also confirmed when the customer returns or when you click Sync payment status.

Invalid Openpay credential on save: a key was pasted into the wrong field or with extra characters. Merchant IDs have only letters and digits, private keys start with sk_, public keys with pk_.

The customer sees The card could not be validated: the card details are incomplete or wrong, or openpay.js or the antifraud library of OpenPay did not load in the browser. Ask the customer to check the card 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 log. A wrong merchant ID or private key is a typical cause. If OpenPay did not answer, the order is On Hold: check the OpenPay dashboard for the charge before the customer pays again.

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

Order is On Hold after payment: read the order notes (see Order statuses), then fulfil the order or refund the payment.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. Payments of a Colombian account and orders without an invoice (for example On Hold after a mismatch) cannot be refunded with a credit memo; see Refunds.

Refund fails with Only a verified completed Openpay charge can be refunded: OpenPay could not be reached, the keys of the payment's mode are not set, or the charge is not completed in OpenPay. Check the keys and the charge in the dashboard and try again.

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

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_OpenpayPayment to remove the data, then bin/magento module:disable Vibefox_OpenpayPayment, delete the folder app/code/Vibefox/OpenpayPayment 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, the stored webhook verification code, the module cache and the log are removed too. If it is No, the settings are kept for a re-install. The OpenPay charge and refund history is always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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