VibeFox ePay.bg for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active.

PHP: 8.0 or later.

Store currency: Bulgarian lev (BGN), euro (EUR) or US dollar (USD). The order is charged in its own currency with 2 decimals. For other currencies the payment method is hidden at checkout.

ePay.bg account: you need the customer number (MIN) and the secret key from your ePay.bg merchant profile: the live ones from www.epay.bg, the test ones from demo.epay.bg (a test account is registered separately). You also need to enter the notification URL of your store in the merchant profile.

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_epaybg_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate. WooCommerce must be active.

3. Open the settings: WooCommerce > Settings > Payments > ePay.bg > 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 test and/or live MIN and secret key (see Configuration).

6. Copy the notification URL shown in the section Payment notifications (IPN) into the field URL for receiving notifications of the ePay.bg merchant profile, in both the demo and the live profile. Without it orders stay Pending payment.

7. Turn on Enable/Disable. Place a test order in test mode, then untick Test Mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > ePay.bg. Above the fields the page shows an error when the store currency is not BGN, EUR or USD, a warning when the gateway is enabled but the MIN or secret key of the selected mode is empty (it is then hidden at checkout, and saving shows the same error), and Test mode is on: payments go to demo.epay.bg and no real money is charged. while test mode is on. In the list of payment methods, ePay.bg is marked as needing setup until the credentials of the selected mode are entered.

General

Enable/Disable: Enable ePay.bg Payment Gateway turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: ePay.bg.

Description: the text shown under the payment method at checkout. Default: Pay securely via ePay.bg with a bank card or your ePay.bg account.

ePay.bg account

The customer number (MIN) and the secret key are shown in your merchant profile on www.epay.bg (live) and demo.epay.bg (test account, registered separately). Spaces and line breaks in pasted secret keys are removed when you save.

Test Mode: Enable test mode (use demo.epay.bg and the test credentials). When on, customers are sent to the ePay.bg demo environment and the requests are signed with the test credentials. Default: on.

Test Merchant ID (MIN): the customer number (MIN) of your demo.epay.bg merchant account.

Test Secret Key: the secret key of your demo.epay.bg merchant account (64 characters).

Live Merchant ID (MIN): the customer number (MIN) of your www.epay.bg merchant account.

Live Secret Key: the secret key of your www.epay.bg merchant account (64 characters), used for the HMAC-SHA1 signature.

If you update from version 1.0, the single set of credentials of that version is moved to the test fields when test mode was on.

Payment notifications (IPN)

The notification tells your store that a payment request was paid, denied or has expired. This section shows the notification URL. It looks like https://your-site/wc-api/epaybg_payment_callback/. Enter it as URL for receiving notifications in the ePay.bg merchant profile, live and test. Orders are marked paid only by these signed notifications; the customer returning to the store does not mark an order paid.

ePay.bg reports these results for each invoice:

PAID: the customer paid. The order is marked paid.

DENIED: the payment was denied. The unpaid order is cancelled.

EXPIRED: the payment request expired unpaid. The unpaid order is cancelled.

Each notification is checked with the secret key of the selected mode. Notifications without a valid checksum are rejected, and ePay.bg keeps sending them. Without the notification URL in the merchant profile, no order is marked paid.

Payment request

Invoice Prefix: digits only (up to 10), put in front of the order ID to form the ePay.bg invoice number, for example 00001 + 123 = 00001123. Use different prefixes for different shops on one ePay.bg account. Other characters are removed when you save. Changing the prefix later is safe: pending orders are found by the invoice stored on the order. Default: 00001.

Expiration Time: the time after which an unpaid payment request expires; ePay.bg then reports it as expired and the pending order is cancelled. Choose 1, 3, 6, 12, 24, 48 or 72 hours. The time is sent in Bulgarian time, whatever the time zone of your site. Default: 24 hours.

Language: the language of the ePay.bg payment page, English or Bulgarian. Default: English.

Order Status After Payment: the order status set after a successful payment. The status is set at once, without a second status change.

Default (WooCommerce decides): Processing, or Completed for orders with only virtual downloadable products (default).

Processing: every paid order becomes Processing.

Completed: every paid order becomes Completed.

On Hold: every paid order waits for your manual review.

Advanced

Logging: Enable logging writes payment requests and notifications to WooCommerce > Status > Logs, source wcp_epaybg_gateway, without secret keys or card data. Default: off.

Delete Data on Uninstall: Remove all plugin data when uninstalled. If checked, the gateway settings, the ePay.bg data stored on orders and the plugin logs are deleted when the plugin is uninstalled. Default: off.

Checkout

The customer chooses the payment method (by default ePay.bg) and places the order. The customer sees Redirecting to ePay.bg for payment... and is sent to ePay.bg with a signed payment request for the order total in the order currency, with the invoice number and the expiration time. The page also has a Pay via ePay.bg button in case the redirect does not start, and a Cancel order button. On ePay.bg the customer pays with a bank card or an ePay.bg account.

After paying, the customer returns to the order received page of your store. The order is marked paid only when the signed ePay.bg notification arrives. The cart is emptied only on the order received page.

If the customer cancels on ePay.bg, the order is cancelled the standard WooCommerce way and the cart is kept, so the customer can choose another payment method.

If the order cannot be paid with ePay.bg, the customer sees a short message, for example ePay.bg payments are temporarily unavailable. Please choose another payment method. or that ePay.bg does not accept payments in the order currency.

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 plugin takes one-time payments on ePay.bg only. It has no refunds from WooCommerce, no saved cards or tokenization, no subscriptions or recurring payments and no EasyPay or B-Pay cash payment codes.

Orders

Order statuses

Pending payment: the customer was sent to ePay.bg and has not paid yet, or the notification has not arrived yet. The order note says Awaiting ePay.bg payment.

Processing, Completed or On Hold: the payment was confirmed. The status follows Order Status After Payment. The order note shows the invoice number, the payment date, the STAN and the BORICA code. The transaction ID is the STAN (or the invoice number if there is no STAN).

On hold after payment: the payment arrived, but not for what the order says now: the total or currency was changed after the payment request, the request was made in the other mode or the gateway was switched between test and live afterwards, the payment method of the order was changed, or the order had been cancelled before. The order note explains the reason. Check the payment in the ePay.bg merchant panel and complete or refund the order manually.

Cancelled: ePay.bg reported the payment request as denied or expired, or the customer cancelled on ePay.bg. WooCommerce restores the stock. A cancelled order cannot be paid again, because the ePay.bg invoice number is the prefix plus the order ID. The customer places a new order.

A late denied or expired notice never changes a paid order. If a payment arrives for an order that is already paid or refunded, the status is not changed, and a note asks you to check for a double payment in the ePay.bg merchant panel.

Refunds

Refunds from WooCommerce are not available, because the ePay.bg WEB API has no refund call. Refund the payment in the ePay.bg merchant panel and record the refund manually in WooCommerce.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > ePay.bg. 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, ePay.bg 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

ePay.bg does not appear at checkout: check that the license is active, Enable/Disable is on, the MIN and secret key of the selected mode are set and the store currency is BGN, EUR or USD. The settings page shows a warning in each of these cases.

The payment went through, but the order stays Pending payment: the order is marked paid only by the ePay.bg notification. Check that the notification URL is entered in the ePay.bg merchant profile of the mode you use (demo or live) and that the secret key of the active mode is correct. Turn on Logging and look at WooCommerce > Status > Logs, source wcp_epaybg_gateway.

Notification answers ERR=Not valid CHECKSUM: the secret key in the settings does not match the merchant profile that sent the notification. Notifications are checked with the key of the mode selected now, then with the key of the other mode, so payment requests made before you switched the mode are still accepted. ePay.bg keeps retrying, so the order is updated once the key is correct.

Notification answers ERR=Not configured: the secret key of the selected mode is empty. Enter it.

Notification answers STATUS=NO for an invoice: the invoice does not belong to an ePay.bg order of this store, for example it was issued by another shop on the same ePay.bg account. Give each shop its own Invoice Prefix.

Notification answers STATUS=ERR: a temporary error, for example two notifications for the same order at the same moment. ePay.bg sends the notification again.

Order is On hold after payment: read the order note. The total or currency changed after the payment request, the request was made in the other mode or the mode was switched afterwards, the payment method changed or the order had been cancelled. Check the payment in the ePay.bg merchant panel.

The invoice prefix was changed when saving: the prefix may contain only digits, up to 10. Other characters are removed.

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 readme mentions the filter epay_bp_form_fields, for example to use the direct card page (PAGE=credit_paydirect).

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, the ePay.bg data stored on orders and the logs are removed only if Delete Data on Uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

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