VibeFox ePayco for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

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

Currency: Colombian peso (COP) or US dollar (USD). 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 shop 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

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 ePayco 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. Enter the four ePayco keys and choose the checkout type (see Configuration).

5. Turn on Enable/Disable and click Save. Test a payment with Test Mode on and ePayco test cards, then turn off Test Mode.

On install the module creates two order statuses, Awaiting ePayco payment and ePayco 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 ePayco Payment > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you when not all four keys are entered (the payment method is then hidden at checkout) and when the default currency of your shop is not COP or USD, and shows Test mode is on: customers pay with ePayco test cards and no real money is charged. while test mode is on.

ePayco

Enable/Disable: Enable ePayco Payment 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: ePayco.

Description: the text shown under the payment method at checkout. Default: Pay securely with ePayco.

ePayco account keys

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.

Customer ID (P_CUST_ID_CLIENTE): your ePayco customer ID (numeric).

Secret Key (P_KEY): used to verify the signature of ePayco payment confirmations. Keep it secret.

Public Key (PUBLIC_KEY): your ePayco public API key.

Private Key (PRIVATE_KEY): your ePayco private API key. Keep it secret.

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 secrets: tick Secret Key (P_KEY) or Private Key (PRIVATE_KEY) and click Save to remove it. An empty field keeps the saved value.

Test Mode: checkout sessions are created as test transactions. Customers pay with ePayco test cards, and no real money is charged. Test transactions never pay orders created in live mode. Default: off. While it is on, customers see TEST MODE — use ePayco test cards, no real money is charged. under the payment method and on the payment page.

Checkout

Checkout Type: how the ePayco checkout opens.

Confirmation URL

The confirmation URL tells your shop the result of a payment. It is sent to ePayco automatically with every payment, so there is nothing to configure in the ePayco dashboard. The section shows the URL. With friendly URLs it looks like https://your-shop/module/wcp_epayco_payment/confirmation, possibly with a language code such as /en/. It must be reachable from the internet, not blocked by a firewall or basic authentication. It works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

Each confirmation must carry a valid signature made with your P_CUST_ID_CLIENTE and P_KEY. Confirmations without a valid signature are rejected and do not change anything. Without the confirmation, an order is created only when the customer comes back to the shop after paying.

Advanced

Logging: writes API errors and payment confirmations to logs/epc_p_debug.log.php in the module folder. The file cannot be opened from the web. Keys and customer data are not logged. Default: off. Errors are always logged, even while it is 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 module settings and the log. The ePayco data saved for orders and the module's order statuses always stay, so existing orders keep working. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default ePayco) and confirms. The module creates an ePayco checkout session for the cart total in the cart currency, with the taxes, the cart number and the billing name, address, e-mail and phone. The payment shows at ePayco as Cart # and the cart number. The checkout language is Spanish or English, following the shop language. No order exists yet at this point.

The customer then sees the ePayco payment page with Thank you for your order. The secure ePayco checkout opens automatically; if it does not, click the button below. The ePayco checkout opens as a popup or as a redirect, depending on Checkout Type. The page also has the button Pay with ePayco and the link Choose another payment method. Each click on the payment button at checkout creates a new ePayco session.

In the ePayco checkout the customer pays with one of the methods enabled on your ePayco account. Afterwards ePayco sends the confirmation to your shop 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. The order is then created and the customer sees the standard order confirmation page.

For a pending payment (for example PSE or cash) the order is created in Awaiting ePayco payment and the confirmation page shows Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved. If the pending payment is later rejected or expires, the page shows Your ePayco payment was not completed. Please contact us about this order. If ePayco has not confirmed the payment yet when the customer comes back, a Payment confirmation page shows We are waiting for ePayco to confirm your payment. This page does not need to stay open. and a Check again button.

If the payment was declined, the customer is back at checkout with Your ePayco payment was declined or could not be completed. You can try again or choose another payment method. If the customer comes back without paying, the message is The ePayco payment was not completed. If you already paid, the order will be updated as soon as ePayco confirms it; otherwise you can try again. The cart is kept, and no order is created.

If ePayco cannot start the payment, the customer stays at checkout with a short message, for example We could not connect to ePayco. Please try again in a moment or choose another payment method. The technical reason is written to the log.

The module takes one-time payments only. It has no refunds from the shop, 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.

Orders

Order statuses

No order yet: the customer was sent to ePayco and has not paid, ePayco has not confirmed the payment yet, or the payment was declined. Only the cart exists.

Payment accepted: ePayco approved the payment. The payment is recorded with the ePayco reference (ref_payco) as the transaction ID, and a note shows the reference, the state, the amount, the payment method and the approval code.

Awaiting ePayco payment: ePayco reported the payment as pending or held, for example a PSE transfer or a cash payment. The order changes automatically when ePayco approves or rejects it.

ePayco payment on hold: ePayco approved a payment whose amount or currency differs from the order (for example, the cart was changed after the payment started), or approved a payment after the order had been cancelled. The amount actually paid is recorded on the order when the currency matches. Do not ship before checking the transaction in the ePayco dashboard.

Payment error: a pending payment was rejected, failed, expired or cancelled. The note shows the ePayco reason. A new approved payment for the cart still pays the order. A late failure never changes a paid order.

Refunded: ePayco reversed the payment of this order.

If ePayco reports another approved payment for an order that is already paid, the status is not changed. A note asks you to check for a double charge and refund it in ePayco if needed. A test transaction for an order placed in live mode, and a transaction that already belongs to another order, are ignored with a note.

ePayco payment block

The order page shows an ePayco payment block with the ePayco reference (ref_payco), the transaction ID, the state, the payment method, the approval code, the transaction date, a Test mode badge for test payments and the ePayco notes of the order. For an order in ePayco payment on hold the block shows a warning to check the transaction before shipping.

Refunds

Refunds from the shop are not supported. Refund the payment in the ePayco dashboard, then update the order in PrestaShop manually if needed. A reversal of the paying transaction that ePayco reports sets the order to Refunded.

License key

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

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

ePayco does not appear at checkout: check that the license is active, Enable/Disable is on, all four keys are entered and the cart currency is COP or USD. The settings page shows a warning when 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 ePayco confirmation does not reach your shop. 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. Look at the Log field on the module page; turn on Logging to see every confirmation. The order is also created when the customer returns to the shop after paying.

Confirmation answers Invalid signature: Customer ID (P_CUST_ID_CLIENTE) or Secret Key (P_KEY) 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 a cart without an ePayco payment of this shop.

Confirmation answers Busy, retry later: the order was being updated by another request at the same moment, or the order could not be created (for example, the module is disabled). ePayco retries the confirmation. The reason is in the log.

The customer sees We could not connect to ePayco: ePayco refused the PUBLIC_KEY and PRIVATE_KEY. The log shows the ePayco answer. Copy both keys again.

The customer sees ePayco could not start the payment: ePayco did not create the checkout session. Read the log for the ePayco error.

The ePayco checkout does not open: the customer sees The ePayco checkout could not be loaded. Please reload the page or choose another payment method. The ePayco checkout script could not be loaded on the payment page. The customer can reload the page or use Choose another payment method.

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

Order is ePayco payment on hold: read the notes in the ePayco payment block (see Order statuses) and check the transaction in the ePayco dashboard before shipping.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox ePayco Payment and choose Uninstall. The license key and license status of this module are always removed. If Delete Data on Uninstall is on, the module settings and the log are removed. If it is off, all settings are kept for a later re-install. The ePayco data saved for orders and the order statuses Awaiting ePayco payment and ePayco payment on hold are always kept. Existing orders keep their payment notes and transaction IDs.

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