VibeFox Eupago for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active.

PHP: 8.0 or later.

Store currency: euro (EUR). Eupago charges euros only, so for other currencies the payment method is hidden at checkout.

Eupago account: you need the API key of your Eupago channel and the key of a Webhook 2.0 that you create in the Eupago backoffice (see Configuration). The live backoffice is clientes.eupago.pt, the sandbox backoffice is sandbox.eupago.pt. Sandbox and live are separate accounts with separate keys.

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

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Eupago > 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 API key of your Eupago channel, create a Webhook 2.0 in the Eupago backoffice and paste its key (see Configuration).

6. Choose the Payment Method, turn on Enable/Disable, place a test order in sandbox mode, then untick Sandbox Mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Eupago. When the gateway is enabled, the page warns you if the API key of the current mode is empty (the gateway is then hidden at checkout), or shows Sandbox mode: no real payments are taken. while sandbox mode is on. In the list of payment methods, Eupago is marked as needing action until the API key of the current mode is set, and shows a test mode badge in sandbox mode.

General

Enable/Disable: Enable Eupago Gateway turns the payment method on or off. Default: off.

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

Description: the text shown under the payment method at checkout. Default: Pay securely via Eupago.

Payment Method: the one Eupago method offered at checkout.

Multibanco: the customer gets an entity and a reference to pay at an ATM or in home banking (default). Offered for order totals from 1 € to 999 999.99 €.

MB WAY: the customer enters the MB WAY phone number at checkout and approves the payment in the MB WAY app.

Credit Card: the customer is redirected to the Eupago card page.

Order Status After Payment: the order status set when the payment is confirmed: Processing (default) or Completed. The status is set at once, with one status change and one e-mail.

Eupago account

Get the API key of your channel and the Webhook 2.0 key in the Eupago backoffice: clientes.eupago.pt (live) or sandbox.eupago.pt (sandbox).

Sandbox Mode: Enable sandbox/test mode uses sandbox.eupago.pt and the sandbox keys. No real payments are taken. Default: on. Untick it to take real payments with the live keys.

Live API Key: the API key of your live Eupago channel (clientes.eupago.pt).

Live Webhook Key: the encryption key of your live Webhook 2.0. Required: notifications without a valid signature are rejected.

Sandbox API Key: the API key of your sandbox channel (sandbox.eupago.pt).

Sandbox Webhook Key: the encryption key of your sandbox Webhook 2.0.

Webhook URL

The webhook tells your store that a payment has been made. In the Eupago backoffice create a Webhook 2.0 with the URL shown in this section of the settings, method POST and encryption enabled. The URL looks like https://your-site/wc-api/eupago_payment_callback/. Create one webhook in the sandbox backoffice and another one in the live backoffice.

Copy the key of each webhook into Sandbox Webhook Key or Live Webhook Key. Webhooks without a valid signature are rejected. An unencrypted webhook is accepted only if Eupago signs it, so keep encryption on. The plugin reacts to these notification statuses:

PAID: the payment was made. The order is marked paid after all checks.

CANCELED: the payment was cancelled. An unpaid order becomes Cancelled.

EXPIRED: the payment expired. An unpaid order becomes Cancelled.

ERROR: the payment failed. An unpaid order becomes Failed.

Other statuses need no action. The legacy GET callback of Eupago to the same URL is also accepted; it is authenticated by the API key and always reports a payment. Without notifications, orders are never marked paid: the plugin does not poll Eupago and the customer's return does not pay an order.

Advanced

Debug Log: Enable logging writes API calls and notifications to WooCommerce > Status > Logs, source wcp_eupago_gateway. Keys, e-mails and full phone numbers are not logged. Errors are always logged. Default: off.

Delete Data on Uninstall: Delete all plugin data when uninstalling. If checked, the gateway settings and logs are removed when the plugin is deleted. Orders and their payment data are kept. Default: off.

Checkout

The customer chooses the payment method (by default Eupago) and places the order. In sandbox mode the checkout shows SANDBOX / TEST MODE. What happens next depends on Payment Method.

Multibanco: at checkout the customer sees You will receive Multibanco payment details after placing the order. The plugin creates a Multibanco reference for the order total. The order is put On hold, stock is reduced and the cart is emptied. The order received page shows Multibanco Payment Details with the entity, the reference and the amount. The same details are added to the customer's order e-mail while the order waits for payment. The customer pays at an ATM or in home banking.

MB WAY: at checkout the customer enters MB WAY Phone Number, filled in with the billing phone. Portuguese numbers can be entered without +351. A wrong number gives Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). The plugin sends the payment request to the MB WAY app. The order is put On hold, stock is reduced and the cart is emptied. The order received page asks the customer to open the MB WAY app and approve the request within 5 minutes.

Credit Card: at checkout the customer sees You will be redirected to a secure payment page to enter your card details. The customer is sent to the Eupago card page, in Portuguese, Spanish or English according to the site language. The order stays Pending payment and the cart is kept. After paying, the customer returns to the order received page, which shows Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. until the notification arrives. If the card payment fails or is abandoned, the customer lands on the Pay for order page with The card payment was not completed. You can try again or choose another payment method. or The card payment was cancelled. You can try again or choose another payment method.

For every method, the order is marked paid only after Eupago confirms it with a verified notification. A customer can pay an unpaid order again from the Pay for order page; every payment reference created for the order stays valid for the check.

If Eupago cannot start the payment, the customer sees a short message, for example The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method. The order does not change, and the details are in 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 Portuguese.

The plugin offers one Eupago method per installation. It has no refunds from WooCommerce, no saved cards, subscriptions or pre-authorisation, no PayShop, Cofidis Pay, Bizum or other Eupago methods, no SMS reminders, no Multibanco expiry date and no status polling.

Orders

Order statuses

Pending payment: a card payment was started and Eupago has not confirmed it yet.

On hold, awaiting payment: a Multibanco reference or an MB WAY request was created. The order note shows the entity and reference or the masked phone number.

Processing or Completed: the payment was confirmed. The status follows Order Status After Payment. The order note shows the method, the Eupago transaction ID and the reference. The transaction ID of the order is the Eupago transaction ID.

On hold, manual review: Eupago reported a payment with a different amount or currency, with a reference that was not created for this order, or for an order that had been cancelled or failed meanwhile (for example a Multibanco reference paid late). The note explains it. Check the payment and the stock, then complete the order manually or refund the customer. Later notifications for this payment do not complete the order behind your back.

Cancelled: Eupago reported the payment as cancelled or expired, for the current payment attempt of an unpaid order.

Failed: Eupago reported an error for the current payment attempt of an unpaid order.

If Eupago reports another payment for an order that is already paid (for example an older Multibanco reference was paid too), the order is not changed. A note asks you to check for a duplicate payment and refund it in the Eupago backoffice. A paid notification never reopens an order that was paid and later cancelled or refunded.

Refunds: refunds from WooCommerce are not supported. Refund the customer in the Eupago backoffice and 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 > Eupago. 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, Eupago 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

Eupago does not appear at checkout: check that the license is active, Enable/Disable is on, the API key of the current mode is set (Sandbox API Key in sandbox mode, Live API Key in live mode) and the store currency is EUR. With Multibanco the order total must be from 1 € to 999 999.99 €.

The payment went through, but the order stays Pending payment or On hold: the Eupago notification does not arrive or is rejected. In the Eupago backoffice of the mode you use, check that the Webhook 2.0 exists, that its URL is exactly the one shown in the settings, that the method is POST and encryption is on. Check that its key is in the matching field (Sandbox Webhook Key or Live Webhook Key). Turn on Debug Log and look at WooCommerce > Status > Logs, source wcp_eupago_gateway. If a notification never arrives, check the payment in the Eupago backoffice.

Webhook answers Invalid signature or Missing signature: the webhook key in the plugin does not match the key of the webhook, or the webhook is unencrypted and unsigned. Copy the key again and keep encryption on.

Webhook answers Webhook key not configured: neither webhook key is set. Eupago retries the notification after you paste the key.

Webhook answers Decryption failed: the signature is valid, but the body could not be decrypted. Check the Webhook 2.0 settings in the Eupago backoffice.

Webhook answers Environment mismatch: the notification is signed with the key of the other mode than the one the order was placed in. A sandbox notification never pays a live order and the other way round.

Legacy callback answers Invalid API key: the API key sent by Eupago does not match Live API Key or Sandbox API Key.

The customer sees The MB WAY payment could not be started: check that the phone number is associated with MB WAY and try again.

Order is On hold after payment: read the order note. The amount or currency differed, the reference was unknown, or the payment came after the order was cancelled. Verify the payment in the Eupago backoffice, then complete the order or refund the customer.

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 eupago_p_icon (checkout icon) and eupago_p_card_language (language of the Eupago card page: PT, EN or ES).

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. Orders and their Eupago references are always kept. Existing orders keep their payment notes and transaction IDs.

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