VibeFox ePay.bg for Adobe Commerce — Aide

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, JSON and SimpleXML extensions.

Currency: Bulgarian lev (BGN), euro (EUR) 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.

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

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

2. Run bin/magento module:enable Vibefox_EpaybgPayment 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 ePay.bg 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. Enter the test and/or live MIN and secret key (see Configuration). Copy the notification URL shown under the license block into the field URL for receiving notifications of the ePay.bg merchant profile, in both the demo and the live profile. Without it no order is marked paid. Set Enable to Yes and click Save Config. Place a test order in test mode, then set Test mode to No to accept real payments.

The module adds the ePay.bg 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 one table for the ePay.bg payment requests.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox ePay.bg Gateway, 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: an empty Title or a title longer than 128 characters (Enter a title for the payment method (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 a number, 0 or greater.).

When Enable is Yes, saving also checks the selected mode. If its MIN or secret key is empty, Magento shows ePay.bg: enter the MIN and secret key of the selected mode. The payment method is hidden at checkout until then. While test mode is on, it shows ePay.bg: test mode is on; no real money is charged. These checks use the Default Config values.

Notification URL

The row under the license block shows the URL to enter as URL for receiving notifications in the ePay.bg merchant profile, with the note Enter this notification URL in both ePay.bg merchant profiles. Payments require a signed notification. Refunds are handled in the merchant panel. It is the storefront address of your store and looks like https://your-store/wcpepaybggateway/notify/index/. Copy the URL exactly as the settings show it. It must be reachable from the internet, without a firewall or basic authentication in front of it.

The notification tells your store that a payment request was paid, denied or has expired. ePay.bg reports these results for each invoice:

The order is marked paid only after ePay.bg confirms it with this signed notification; the customer returning to the store does not pay an order. Notifications without a valid checksum are rejected, and ePay.bg keeps sending them. The checksum is checked with the secret key of each mode that has one, so payments started before you switched between test and live are still confirmed. A payment must arrive in the mode its request was made in; otherwise the order goes to review (see Orders and refunds).

General

Enable: shows or hides ePay.bg at checkout. It is shown only when the MIN and the secret key of the current mode are set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: ePay.bg. Required, at most 128 characters.

Description: shown in the payment method list at checkout when the customer selects ePay.bg. Default: Pay securely via ePay.bg with a bank card or your ePay.bg account.

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

Connection

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

Test mode: when Yes, customers are sent to the ePay.bg demo environment (demo.epay.bg) and the requests are signed with the test credentials. Default: Yes. Set it to No to accept real payments on www.epay.bg. While it is on, customers see TEST MODE: no real money is charged. under the payment method.

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

Live 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, used for the HMAC-SHA1 signature.

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

Options

Invoice prefix: digits only (up to 10), put in front of the Magento order ID to form the ePay.bg invoice number, for example 00001 + 123 = 00001123. Use different prefixes for different stores on one ePay.bg account. Other characters are removed when you save, and Magento shows ePay.bg: the invoice prefix may contain only digits (up to 10); other characters were removed. Changing the prefix later is safe: open payment requests are found by the invoice stored for them. Default: 00001.

Expiration: the time after which an unpaid payment request expires; ePay.bg then reports it as expired and the 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 store. 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 confirmed payment.

Advanced

Logging: the switch for the log var/log/epay_bp_debug.log.php in the Magento folder. The file cannot be opened from the web. Secret keys and e-mail addresses are masked. Errors, for example a notification that could not be saved or an order e-mail that could not be sent, are always logged, also while it is off; this version of the module writes no other entries. Default: No.

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

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

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

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

Maximum Order Total: offer ePay.bg 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 ePay.bg) and sees the description and the note You will be redirected to ePay.bg 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 customer sees You are being redirected to ePay.bg. 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 payment shows on ePay.bg as Magento order and the order number. The page also has a Pay via ePay.bg button in case the redirect does not start. On ePay.bg the customer pays with a bank card or an ePay.bg account.

After paying, the customer returns to your store. The order is marked paid only after ePay.bg confirms it with the signed notification. Magento then creates the invoice with the STAN as the transaction ID, sets the status from Order status after payment and sends the order e-mail. If the notification has already arrived, the customer sees the standard order success page; a customer who comes back in another browser lands on the home page. If it has not arrived yet, a simple page says Payment pending with the links Check again and Cancel and return to checkout. If the payment arrived but needs your review, the page says Payment requires manual review and Please contact the store before making another payment.

If the customer cancels on ePay.bg, or clicks Cancel and return to checkout, the order is cancelled (the stock goes back) and the customer is back in the cart, which is restored. The same happens when the customer returns after ePay.bg has reported the request as denied or expired. A new Place Order creates a new order with a new invoice number.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees We could not start the ePay.bg payment. Please try again or choose another payment method.

The module works with the standard Magento checkout. It takes one-time payments on ePay.bg only. It has no refunds from Magento, no saved cards, no subscriptions or recurring payments and no EasyPay or B-Pay cash payment codes. ePay.bg 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 ePay.bg, but the notification has not arrived yet. There is no invoice.

Processing, Complete or On Hold: the payment was confirmed. The status follows Order status after payment. The invoice is created with the STAN as the transaction ID (or the invoice number if there is no STAN), and a note shows the invoice number, the STAN, the BORICA code and the payment time.

On Hold after a mismatch: the payment arrived, but not for what the order says now: the order total or currency was changed after the payment request, the notification came in the other mode (test or live) than the request, or the order was no longer waiting for payment. No invoice is created. The note shows the signed amount and the STAN. Check the payment in the ePay.bg merchant panel and fulfil or refund the order manually. A payment that arrives for an order that was already cancelled leaves the order cancelled and adds the same note.

Canceled: ePay.bg reported the request as denied or expired, the customer cancelled the payment, 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).

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

If a payment arrives for a cart that is already paid, the order is not changed and gets a note about a possible double payment, so you can refund it in the ePay.bg merchant panel. Repeated notifications never create a second invoice, and a late denied or expired notice never changes a paid order. The notes are order comments that the customer does not see.

ePay.bg payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, once the request is made and confirmed, ePay.bg invoice, ePay.bg STAN, ePay.bg BORICA code, ePay.bg payment time, ePay.bg signed amount, ePay.bg mode and ePay.bg status. The customer sees only the payment method title. The Information tab also has an ePay.bg requests table with every payment request of the cart: invoice, mode, amount, currency, request status, notification, STAN, BORICA code and payment time.

Refunds

Refunds from Magento are not sent to ePay.bg, because the ePay.bg payment flow has no refund call. Refund the payment in the ePay.bg merchant panel, then create a credit memo for the invoice with Refund Offline to record the refund in Magento. A full refund closes the order (Closed).

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox ePay.bg Gateway is the first row of the VibeFox ePay.bg 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-epaybg 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, ePay.bg 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 We could not start the ePay.bg 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 by the notification.

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

ePay.bg does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the current mode has its MIN and secret key: the test fields in test mode, the live fields otherwise. Saving the settings shows a warning when they are missing. The cart currency must be BGN, EUR or USD. 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 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), exactly as shown on the settings page, and that the secret key of that mode is correct. Errors are written to the log at the bottom of the group.

Notification answers ERR=Not valid CHECKSUM: no saved secret key matches the merchant profile that sent the notification. ePay.bg keeps retrying, so the order is confirmed once the key is correct.

Notification answers ERR=Not configured: no secret key is saved. Enter it.

Notification answers STATUS=NO for an invoice: the invoice was not issued by this store, for example by another store on the same ePay.bg account. Give each store its own Invoice prefix.

Notification answers STATUS=ERR: a temporary error, for example two notifications for the same cart at the same moment, or the order could not be saved. ePay.bg sends the notification again. The reason is in the log.

The notification URL shows ERR=POST required in the browser: this is normal. The URL accepts only requests from ePay.bg.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. ePay.bg sends the notification again later.

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). A payment that arrives after that leaves the order cancelled with a note and no invoice. Set the lifetime to at least the Expiration of the payment request, and handle such a payment in the ePay.bg merchant panel.

The customer sees We could not start the ePay.bg payment: the license is not active, the MIN or secret key of the current mode is missing, the order currency is not supported, or another order has already used the same invoice number (for example after the Invoice prefix was changed back to an older value). In the last case choose another prefix. The order of that attempt is cancelled.

Order is On Hold after payment: read the order notes and the ePay.bg requests table (see Order statuses), check the payment in the ePay.bg merchant panel, then fulfil the order or refund the payment there.

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

There is no Refund button on the credit memo: this is normal. The module has no online refunds. Refund the payment in the ePay.bg merchant panel, 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 fields of the payment form with the Magento event epay_bp_form_fields, for example to use the direct card page (PAGE=credit_paydirect). The signed data and the checksum 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_EpaybgPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_EpaybgPayment to remove the data, then bin/magento module:disable Vibefox_EpaybgPayment, delete the folder app/code/Vibefox/EpaybgPayment 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 and the log are removed too. If it is No, the settings are kept for a re-install. The ePay.bg 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.

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