VibeFox ePayco for Adobe Commerce — Guida

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 extension (the module connects to ePayco through cURL).

Currency: Colombian peso (COP) or US dollar (USD). The order is charged in its own currency (the currency the customer sees) with 2 decimals. For carts in other currencies the payment method is hidden at checkout.

ePayco account: you need the four keys of your ePayco account: P_CUST_ID_CLIENTE, P_KEY, PUBLIC_KEY and PRIVATE_KEY. They are in the ePayco dashboard under Integrations, API keys. The same keys work in test and live mode. The payment methods the customer can use (cards, PSE, cash networks, wallets) are the ones enabled on your ePayco account.

Public website: the confirmation URL of your store must be reachable from the internet, not blocked by a firewall or basic authentication.

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

2. Run bin/magento module:enable Vibefox_EpaycoPayment 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 ePayco 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. Enter the four ePayco keys and choose the checkout type (see Configuration). Nothing has to be set up in the ePayco dashboard: the confirmation URL is sent to ePayco with every payment. Set Enable to Yes and click Save Config. Test a payment with Test mode = Yes and ePayco test cards, then set Test mode to No to accept real payments.

The module adds the ePayco 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 ePayco payment requests and the ePayco messages it has processed.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox ePayco 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. Amounts are entered with a dot, for example "9.99".

If a value is wrong, Magento shows an error and nothing on the page is saved: a Title longer than 128 characters (The payment title must be at most 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 a number, 0 or greater.).

When Enable is Yes, saving the Payment Methods page also checks the keys. If one of the four keys is empty, Magento shows ePayco: enter all four keys of your account. The payment method is hidden at checkout until then. While test mode is on, it shows ePayco: test mode is on; no real money is charged. These checks use the Default Config values.

Confirmation URL

The row under the license block shows the Confirmation URL with the note The URL is sent with every checkout session. The same four keys are used in test and live mode. Refunds are made in the ePayco dashboard. It is the storefront address of your store and looks like https://your-store/wcpepaycopayment/confirmation/index/. Each payment carries the confirmation URL of the store view where the order was placed, so there is nothing to configure in the ePayco dashboard. The URL must be reachable from the internet, without a firewall or basic authentication in front of it.

The confirmation tells your store the result of a payment. Each confirmation must carry a valid signature made with the P_CUST_ID_CLIENTE and P_KEY saved for the store of the order. Confirmations without a valid signature are rejected and do not change anything. Without the confirmation, an order is marked paid only when the customer comes back to the store after paying and the module checks the transaction with ePayco (see Checkout).

General

Enable: shows or hides ePayco at checkout. It is shown only when all four keys are set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: ePayco. If you leave it empty, ePayco is used. At most 128 characters.

Description: shown in the payment method list at checkout when the customer selects ePayco. Default: Pay securely with ePayco.

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

Connection

Find the four keys in the ePayco dashboard under Integrations, API keys. P_CUST_ID_CLIENTE and P_KEY verify payment confirmations; PUBLIC_KEY and PRIVATE_KEY create checkout sessions. The same keys work in test and live mode.

P_CUST_ID_CLIENTE: your ePayco customer ID.

P_KEY: the secret key used to verify the signature of ePayco payment confirmations. Keep it secret.

PUBLIC_KEY: your ePayco public API key.

PRIVATE_KEY: your ePayco private API key. Keep it secret.

Magento stores P_KEY and PRIVATE_KEY 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 key, clear the field and click Save Config. Spaces around pasted keys are removed when you save.

Checkout

Test mode: when Yes, new checkout sessions are created as test transactions. Customers pay with ePayco test cards, and no real money is charged. A test transaction never pays an order placed in live mode. Default: No. While it is on, customers see TEST MODE: no real money is charged. under the payment method.

Checkout type: how the ePayco checkout opens.

Advanced

Logging: the switch for the log var/log/epc_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Keys, return tokens and e-mail addresses are masked, and the text of ePayco error answers is not written. Errors, for example a payment that could not be started, a confirmation that could not be saved or an order e-mail that could not be sent, are always logged, also while it is off. With Yes the log also records each created checkout session and each failed check of a transaction. When the log reaches 5 MB, it is moved to epc_p_debug.old.log.php and a new one is started. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the payment settings and the log (see Uninstall). The license key is always removed. The ePayco payment records always stay. Default: No.

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

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

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

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

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 ePayco) and sees the description and the note You will be redirected to ePayco 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 creates an ePayco checkout session for the order total in the order currency, with the taxes, the order number and the billing name, address, e-mail and phone. The payment shows at ePayco as Order # and the order number. The checkout language is Spanish when the locale of the store view is Spanish, otherwise English.

The customer then sees the ePayco payment page with Complete your payment with ePayco. The ePayco checkout opens automatically, as a popup or as a redirect, depending on Checkout type. The page also has the button Pay with ePayco and the link Cancel and return to checkout. If the ePayco checkout script cannot be loaded, the page shows The ePayco checkout could not be loaded. Please try again.

In the ePayco checkout the customer pays with one of the methods enabled on your ePayco account. Afterwards ePayco sends the confirmation to your store and returns the customer. The order is marked paid only after ePayco confirms it: by the signed confirmation, or by a server-side request to ePayco when the customer comes back. The customer's return alone never pays an order. Magento then creates the invoice with the ePayco reference (ref_payco) as the transaction ID, sets the order to Processing and sends the order e-mail. The customer sees the standard order success page; a customer who comes back in another browser lands on the home page.

For a pending payment (for example PSE or cash) the order stays in Pending Payment and the order e-mail is sent. If ePayco has not confirmed the payment yet when the customer comes back, a simple page says Your ePayco payment is being confirmed. and Please contact the store before making another payment., with a Check again link. If the payment arrived but needs your review, the page says Payment requires manual review. While a payment of the cart is pending, approved or under review, the customer cannot start another payment for it.

If the payment was declined, failed or expired, or the customer comes back without paying (for example with Cancel and return to checkout), the order is cancelled (the stock goes back) and the customer is back in the cart, which is restored, with the message The ePayco payment was not completed. If you already paid, please contact the store. A new Place Order creates a new order.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees ePayco could not start the payment. Please try again or choose another payment method. The failure is written to the log.

The module works with the standard Magento checkout. It takes one-time payments only. It has no refunds from Magento, no saved cards, subscriptions or split payments, and does not poll ePayco for pending transactions: orders are updated by the ePayco confirmation and by the customer return. ePayco 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 ePayco, but ePayco has not confirmed the payment yet, or ePayco reported it as pending or held, for example a PSE transfer or a cash payment. There is no invoice. The order changes automatically when ePayco approves or rejects the payment.

Processing: ePayco approved the payment. The invoice is created with the ePayco reference (ref_payco) as the transaction ID, and a note shows the reference and the ePayco transaction.

On Hold: ePayco approved a payment whose amount or currency differs from the order (for example, the order total was changed after the payment started), or the order was no longer waiting for payment. No invoice is created. The note shows the amount received and the order total. Check the transaction in the ePayco dashboard, then fulfil the order or refund the payment there. A payment approved for an order that was already cancelled leaves the order cancelled with the same note.

Canceled: the payment was rejected, failed, expired, was abandoned or cancelled at ePayco, the customer came back without paying, the payment could not be started, or the order was cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). The note shows the ePayco state.

Closed: the order was fully refunded with a credit memo, or ePayco reversed the paying transaction (see Refunds).

If ePayco reports another approved payment for an order that is already paid, the order is not changed and a note asks you to check for a double charge and refund it in ePayco if needed. A second payment for the same cart under another order gets the same kind of note. A test transaction for an order placed in live mode, and a transaction that already belongs to another order, are ignored with a note. Repeated confirmations never create a second invoice, and a late failure never changes a paid order. The notes are order comments that the customer does not see.

ePayco payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, once ePayco has reported the payment, ePayco reference, ePayco transaction, ePayco state, ePayco method, ePayco approval code, ePayco transaction date, ePayco signed amount and ePayco mode. The customer sees only the payment method title. The Information tab also has an ePayco requests table with every payment attempt of the cart: attempt, mode, amount, currency, request status, reference, state and transaction.

Refunds

Refunds from Magento are not sent to ePayco. Refund the payment in the ePayco dashboard, then create a credit memo for the invoice with Refund Offline to record the refund in Magento. A full refund closes the order (Closed).

When ePayco reports that the paying transaction was reversed, the module records it with an offline credit memo for the order, and the order becomes Closed. No money is sent by Magento. A reversal that does not match the paying transaction of the order only adds a note.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox ePayco Payment is the first row of the VibeFox ePayco 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-epayco 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, ePayco 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 ePayco could not start the 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.

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

ePayco does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that all four keys are entered. Saving the settings shows a warning when keys are missing. The cart currency must be COP 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 ePayco confirmation does not reach your store. Check that the confirmation URL shown in the settings opens from the internet and is not blocked by a firewall, a security module or basic authentication. Errors are written to the log at the bottom of the group. The order is also marked paid when the customer returns to the store after paying; the Check again link on the waiting page checks the transaction with ePayco again.

Confirmation answers Invalid signature: P_CUST_ID_CLIENTE or P_KEY saved for the store of the order does not match the ePayco account that took the payment. Copy both again from the ePayco dashboard.

Confirmation answers Gateway not configured: P_CUST_ID_CLIENTE or P_KEY is empty. Enter them in the settings.

Confirmation answers Order not found: the confirmation refers to an order without an ePayco payment of this store.

Confirmation answers Busy, retry later: the order was being updated by another request at the same moment, or the confirmation could not be saved. ePayco sends the confirmation again. The reason is in the log.

Confirmations fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the confirmation URL too. The order is still marked paid when the customer returns after the store is open again, or by a later confirmation.

The customer sees ePayco could not start the payment: the license is not active, a key is missing, the order currency is not COP or USD, or ePayco refused the PUBLIC_KEY and PRIVATE_KEY or did not create the checkout session. The log shows which step failed. Copy the keys again from the ePayco dashboard. The order of that attempt is cancelled.

The ePayco checkout does not open: the payment page shows The ePayco checkout could not be loaded. Please try again. The ePayco checkout script could not be loaded in the browser. The customer can reload the page, click Pay with ePayco or use Cancel and return to checkout.

A test payment did not pay the order: test transactions never pay orders placed in live mode. Place the test order while Test mode is Yes.

The order was cancelled, but the customer paid later: Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), also while a PSE or cash payment is pending at ePayco. A payment approved after that leaves the order cancelled with a note and no invoice. If your customers pay in cash, set the lifetime long enough, and handle such a payment in the ePayco dashboard.

Order is On Hold: read the order notes and the ePayco requests table (see Order statuses) and check the transaction in the ePayco dashboard before shipping.

There is no Refund button on the credit memo: this is normal. The module has no online refunds. Refund the payment in the ePayco dashboard, then use Refund Offline.

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.

Developers can change the data of the checkout session with the Magento event epc_p_session_payload. The invoice number and the order reference sent to ePayco cannot be changed.

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

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

The license key and license status are always removed. If Remove data on uninstall is Yes, the payment settings and the log are removed too. If it is No, the settings are kept for a re-install. The ePayco payment records are always kept, so a payment started before a re-install is still confirmed. Existing orders keep their invoices, payment notes and transaction IDs.

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