VibeFox Eupago 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: euro (EUR). Eupago charges euros only, so for carts in 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 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 Eupago Gateway 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 API key of your Eupago channel, create a Webhook 2.0 in the Eupago backoffice and paste its key (see Configuration).

5. Choose the Payment Method, turn on Enable/Disable and click Save. Place a test order in sandbox mode, then turn off Sandbox Mode.

On install the module creates two order statuses, Awaiting Eupago payment and Eupago payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences; the euro must stay allowed for the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Eupago Gateway > Configure. Each section has its own Save button, which saves the whole page. When the payment method is enabled, the page warns you above the fields if the API key of the current mode is empty (the payment method is then hidden at checkout), or shows Sandbox mode: no real payments are taken. while sandbox mode is on.

Eupago

Enable/Disable: Enable Eupago Gateway 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: Eupago. Required: an empty title gives Enter a title for the payment method.

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): the order becomes Payment accepted.

Completed: the order becomes Delivered, in one status change.

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 and live are separate accounts with separate keys.

Sandbox Mode: uses sandbox.eupago.pt and the sandbox keys. No real payments are taken. Default: on. Turn it off to take real payments with the live keys. While it is on, customers see SANDBOX / TEST MODE under the payment method.

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.

Saved 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 keys: tick a key and click Save to remove it. An empty field keeps the saved value.

Webhook URL

The webhook tells your shop that a payment has been made. In the Eupago backoffice create a Webhook 2.0 with the URL shown in this section, method POST and encryption enabled. With friendly URLs it looks like https://your-shop/module/wcp_eupago_gateway/webhook, possibly with a language code such as /pt/. Copy the URL exactly as the settings show it. 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. A notification must be signed with the key of the mode the payment was started in, so a sandbox notification never pays a live payment. The module reacts to these notification statuses:

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

CANCELED: the payment was cancelled. A waiting order becomes Canceled.

EXPIRED: the payment expired. A waiting order becomes Canceled.

ERROR: the payment failed. A waiting order becomes Payment error.

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 module does not poll Eupago and the customer's return does not pay an order. The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

Advanced

Debug Log: writes API calls and notifications to logs/eupago_p_debug.log.php in the module folder. The file cannot be opened from the web. Keys, e-mails and full phone numbers are not logged. Errors are always logged. Default: 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 gateway settings, the Eupago payment records of this module and the log. Orders and their payment data are kept. Default: off.

Checkout

The customer chooses the payment method (by default Eupago) at the payment step and places the order. What happens next depends on Payment Method.

Multibanco: at checkout the customer sees You will receive Multibanco payment details after placing the order. The module creates a Multibanco reference for the cart total. The order is created at once in Awaiting Eupago payment, as any PrestaShop order, and the cart is emptied. The order confirmation page shows Multibanco Payment Details with the entity, the reference and the amount. The same details are added to the payment line of the order confirmation e-mail. 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 phone of the invoice address. 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 module sends the payment request to the MB WAY app and creates the order in Awaiting Eupago payment. The order confirmation page asks the customer to open the MB WAY app on the masked phone number 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 cart language. No order exists yet, and the cart is kept. The order is created only when Eupago confirms the payment. If the notification has arrived when the customer comes back, the customer sees the standard order confirmation page. Otherwise a Payment confirmation page shows Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. with a Check again button. If the card payment fails or is abandoned, the customer is back at checkout 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. The payment details are shown only while the order is Awaiting Eupago payment. If Eupago later reports the payment as cancelled, expired or failed and the order was not paid, the order confirmation page shows Your Eupago payment was not completed. Please contact us about this order.

If Eupago cannot start the payment, the customer stays at checkout with 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. No order is created, and the details are in the log. A cart in another currency gives Eupago only supports payments in EUR.

The module offers one Eupago method per installation. It has no refunds from PrestaShop, 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

No order yet: a card payment was started and Eupago has not confirmed it yet. Only the cart exists.

Awaiting Eupago payment: a Multibanco reference or an MB WAY request was created. The note shows the entity and reference or the masked phone number.

Payment accepted or Delivered: the payment was confirmed. The status follows Order Status After Payment. The payment is recorded with the Eupago transaction ID as the transaction ID, and a note shows the method, the transaction ID and the reference.

Eupago payment on hold: Eupago reported a payment with a different amount or currency, with a reference that was not created for this cart, 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.

Canceled: Eupago reported the payment as cancelled or expired, for the current payment attempt of a waiting order.

Payment error: Eupago reported an error for the current payment attempt of a waiting 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.

Eupago payment block

The order page shows an Eupago payment block with every payment attempt of the cart: date, method, a Sandbox badge for sandbox payments, amount, the Multibanco entity and reference or the masked MB WAY phone, the Eupago transaction ID and the status. While the order is Eupago payment on hold, the block shows a Manual review warning. Below it, Eupago notes lists the module's notes on the order, newest first.

Refunds

Refunds from PrestaShop are not supported. Refund the customer in the Eupago backoffice and update the order in PrestaShop manually. The standard PrestaShop refund buttons of the order page do not send money back through Eupago.

License key

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

Eupago does not appear at checkout: check that the license is active, Enable/Disable is on and the API key of the current mode is set (Sandbox API Key in sandbox mode, Live API Key in live mode). The cart currency must be EUR, and in Payment > Preferences the module must be allowed for the euro, the customer's country and the customer's group. With Multibanco the order total must be from 1 € to 999 999.99 €.

The payment went through, but the order stays Awaiting Eupago payment or no order was created: 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 Webhook URL, 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 the Log field on the module page. If a notification never arrives, check the payment in the Eupago backoffice.

Webhook answers Invalid signature or Missing signature: the webhook key in the module 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 payment was started in. A sandbox notification never pays a live payment and the other way round. Check that the sandbox and live keys are not swapped.

Webhook answers Order not found: the notification is for a cart without an Eupago payment of this shop, for example a payment made from another shop with the same Eupago channel.

Webhook answers Busy or Retry: the cart was being processed by another request at the same moment, or the order could not be created (for example, the module is disabled). Eupago retries the notification. The reason is in the log.

Legacy callback answers Invalid API key: the API key sent by Eupago does not match Live API Key or Sandbox API Key. The same answer appears when you open the webhook URL in a browser; this is normal.

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 Eupago payment on hold after payment: read the Eupago notes in the Eupago payment block. 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.

Uninstall

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

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