VibeFox ePayco for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Store currency: Colombian peso (COP) or US dollar (USD). For 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 maintenance mode, a firewall or basic authentication.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_epayco_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > ePayco > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter the four ePayco keys and choose the checkout type (see Configuration).

6. Turn on Enable/Disable. Test a payment in Test Mode with ePayco test cards, then untick Test Mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > ePayco. Above the fields the page warns you when not all four keys are entered (the payment method is then hidden at checkout), when the store currency 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. In the list of payment methods, ePayco is marked as needing setup until all four keys are entered.

General

Enable/Disable: Enable ePayco Payment turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. 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.

Test Mode: Enable test mode creates checkout sessions 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.

Checkout

Checkout Type: how the ePayco checkout opens.

Confirmation URL

The confirmation URL tells your store 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. It looks like https://your-site/wc-api/epc_p/. It must be reachable from the internet, not blocked by maintenance mode, a firewall or basic authentication.

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 the order. Without the confirmation, an order is updated only when the customer comes back to the store after paying.

Advanced

Logging: Enable logging writes API errors and payment confirmations to WooCommerce > Status > Logs, source wcp_epayco_payment. Keys and customer data are not logged. Default: off.

Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Deactivating the plugin never deletes anything. ePayco data saved on orders is kept. Default: off.

Checkout

The customer chooses the payment method (by default ePayco) and places the order. The plugin creates an ePayco checkout session for the order total in the order currency, with the order taxes, the order number and the billing name, address, e-mail and phone. The checkout language is Spanish or English, following the site language. The customer then lands on the order payment page, which shows 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. In test mode the page and the checkout show TEST MODE — use ePayco test cards, no real money is charged.

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.

If the payment is not confirmed yet, the order received page shows We are waiting for ePayco to confirm your payment. This page does not need to stay open. For a pending payment (for example PSE or cash) it shows Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved.

If the payment was declined, the customer goes back to the Pay for order page 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.

If ePayco cannot start the payment, the customer sees a short message, for example We could not connect to ePayco. Please try again in a moment or choose another payment method. The reason is added to the order notes and the log.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS). The customer-facing texts are translated into Spanish.

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

Pending payment: the customer was sent to ePayco and has not paid yet, or ePayco has not confirmed the payment yet.

Processing: the payment was accepted (orders with only virtual downloadable products become Completed, the WooCommerce default). The order note shows the ePayco reference, the state, the amount, the payment method and the approval code. The transaction ID of the order is the ePayco reference (ref_payco).

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

On hold, amount/currency mismatch: ePayco approved a payment whose amount or currency differs from the order. Do not ship before checking the transaction in the ePayco dashboard.

On hold, payment for a cancelled order: ePayco approved a payment after the order had been cancelled. Restore the order or refund the payment in ePayco.

Failed: the payment was rejected, failed, expired, abandoned, cancelled or stopped by antifraud. The note shows the ePayco reason. The customer can try again. 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.

Refunds: refunds from WooCommerce are not supported. Refund the payment in the ePayco dashboard, then record the refund in WooCommerce with Refund manually.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > ePayco. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

ePayco does not appear at checkout: check that the license is active, Enable/Disable is on, all four keys are entered and the store currency is COP or USD. On the Pay for order page the order currency is checked. The settings page shows a warning when something is missing.

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 maintenance mode, a firewall, a security plugin or basic authentication. Turn on Logging and look at WooCommerce > Status > Logs, source wcp_epayco_payment. The order is also updated when the customer returns to the store 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 Busy, retry later: the order was being updated by another request at the same moment. ePayco retries the confirmation.

The customer sees We could not connect to ePayco: ePayco refused the PUBLIC_KEY and PRIVATE_KEY. The order note 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 order note 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 order 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 On hold: read the order note. ePayco reported the payment as pending, the approved amount or currency differed from the order, or the payment came after the order was cancelled. Check the transaction in the ePayco dashboard before shipping.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

For developers, the plugin documentation lists the filters epc_p_supported_currencies (currencies the method is offered for), epc_p_session_payload (data sent to ePayco) and epc_p_icon (checkout icon).

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs are removed only if Delete Data on Uninstall was on. Otherwise they stay for a later re-install. ePayco data saved on orders is always kept. Existing orders keep their payment notes and transaction IDs.

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