VibeFox Eupago for Adobe Commerce — Hilfe

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 and OpenSSL extensions.

Currency: euro (EUR). Eupago charges euros only, so the payment method is shown only when the customer's cart is in euros. The base currency of your store may be another one, but the customer must pay in euros.

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

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

2. Run bin/magento module:enable Vibefox_EupagoPayment 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 Eupago 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 API key of your Eupago channel, create a Webhook 2.0 in the Eupago backoffice and paste its key (see Configuration). Choose the Payment Method, set Enable to Yes and click Save Config. Place a test order in sandbox mode, then set Sandbox Mode to No.

The module adds the Eupago 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 two tables for the Eupago payment attempts and notifications.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Eupago 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 set in the Default Config only. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: Enter a payment title of 1 to 128 characters. for an empty or too long Title; Sort order must be a whole number.; Order total must be a number, 0 or greater. for Minimum Order Total or Maximum Order Total (use a point as the decimal separator, for example 9.99).

After Save Config, while the payment method is enabled in the Default Config, Magento shows these messages when they apply: Eupago: the API Key of the selected mode is empty — hidden at checkout., Eupago: Sandbox mode is on. and Eupago: configure a Webhook 2.0 key to verify signed notifications.

General

Enable: shows or hides Eupago at checkout. It is shown only when the API key of the current mode is set. Default: No.

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

Description: shown in the payment method list at checkout, when the customer selects Eupago. Default: Pay securely via Eupago.

Payment Method: one payment method is offered at a time.

Order Status After Payment: the order status set when the payment is confirmed. Shipping remains your responsibility.

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 use separate keys and accounts.

Sandbox Mode: uses sandbox.eupago.pt and the sandbox keys. No real payments are taken. Default: Yes. Set it to No 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 key of your live Webhook 2.0. Notifications without a valid signature are rejected.

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

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

Magento stores the keys encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete a saved key, clear the field and click Save Config.

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, method POST and encryption enabled. The URL is the storefront address of the default store view (on the website scope, of the default store view of that website) and looks like https://your-store/wcpeupagogateway/webhook/index/?___store=default. Copy the URL exactly as the settings show it, with the store code at the end. Create one webhook in the sandbox backoffice and another one in the live backoffice. The section also has links to clientes.eupago.pt and sandbox.eupago.pt.

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 keys of the store in the webhook URL must be the same as the keys of the store the order was placed in. The module reacts to these notification statuses:

Other statuses need no action. Only the current payment attempt of the cart can cancel an order. 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.

Conditions

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

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

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

Maximum Order Total: offer Eupago only up to this order total, in the base currency. 0 or empty means no maximum.

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

These conditions come on top of the euro currency and the Multibanco amount range.

Advanced

Debug Log: writes API calls and notifications to var/log/eupago_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors are always logged. Keys, e-mails and full phone numbers are redacted. At 5 MB the log starts again and the previous one is kept as eupago_p_debug.old.log.php. Default: No.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove Data on Uninstall: when Yes, uninstalling the module with its data removes the settings and the log (see Uninstall). Existing order and payment history is always kept. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Eupago) and sees the description and the note Payment is confirmed only after Eupago sends a verified notification. After Place Order, Magento places the order in Pending Payment. No invoice is created. The module then creates the Eupago payment for the order total in euros. What happens next depends on Payment Method.

Multibanco: the module creates a Multibanco reference and sends the order e-mail. The order success page shows Use these details to complete your Multibanco payment. with the Entity, the Reference and the Amount. The same details are in the payment information of the order e-mail and of the order in the customer account 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 phone of the billing address. Portuguese numbers can be entered without +351. The module sends the payment request to the MB WAY app and sends the order e-mail. The order success page shows Open the MB WAY app on the masked phone number to approve the payment.

Credit Card: the customer is sent to the Eupago card page, in Portuguese, Spanish or English according to the locale of the store view. The order e-mail is sent only after the payment is confirmed. If the notification has arrived when the customer comes back, the customer sees the standard order success page. Otherwise an Eupago payment page shows Your card payment is being confirmed by Eupago. with a Check again link. If the card payment fails or is abandoned, the order is cancelled (the stock goes back), the cart is restored and the customer sees Your Eupago card payment failed. Please try again or choose another payment method. or Your Eupago card payment was cancelled. in the cart.

For every method, the order is marked paid only after Eupago confirms it with a verified notification. Magento then creates the invoice with the Eupago transaction ID, sets the status from Order Status After Payment and sends the order e-mail (for Multibanco and MB WAY once more, now as a paid order). If Eupago reports the payment as cancelled, expired or failed, the order is cancelled. If the order needs a manual review, the customer sees Your payment is under manual review. Please contact us about this order. Do not pay again.

If Eupago cannot start the payment, for example because Eupago is unavailable or the MB WAY phone number is not valid, the order is cancelled, the cart is restored and the customer sees Eupago could not start the payment. Please try again or choose another payment method. in the cart. The reason is written to the log.

A Multibanco or MB WAY order waits in Pending Payment until Eupago reports the payment. The Magento cron cancels orders in Pending Payment after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings, 480 minutes by default). For Multibanco, set it long enough for your customers to pay. A payment that arrives after the order was cancelled is not invoiced; it is noted on the order for your review.

The module works with the standard Magento checkout. It offers one Eupago method per installation. It has no online refunds, no saved cards, subscriptions or pre-authorisation, no PayShop, Cofidis Pay, Bizum or other Eupago methods, no Multibanco expiry date and no status polling. Eupago is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and is waiting for Eupago: a Multibanco reference or an MB WAY request was created, or the customer was sent to the card page. There is no invoice. A note shows the method and the reference or the masked phone number.

Processing or Complete: the payment was confirmed. The status follows Order Status After Payment. The invoice is created with the Eupago transaction ID as the transaction ID, and a note shows the transaction and the amount paid.

On Hold: Eupago reported a payment with a different amount or currency, with a reference that was not created for this cart, or for a cart already paid with another order. No invoice is created. The note explains it. Verify the payment in the Eupago backoffice, then complete the order manually or refund the customer there. Later notifications for this payment do not complete the order behind your back.

Canceled: Eupago reported the current payment as cancelled, expired or failed, the card payment failed or was abandoned, the payment could not be started, or the order was cancelled in Magento. If Eupago reports a payment for a cancelled order (for example a Multibanco reference paid late), the order stays Canceled, no invoice is created and a note asks you to check the stock and complete the order manually or refund the customer.

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

If Eupago reports another payment for an order that is already paid, the order is not changed. A note asks you to check for a duplicate payment and refund it in the Eupago backoffice if needed. The notes are order comments that the customer does not see.

Eupago payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Eupago method, Entity, Reference, Amount, MB WAY phone (masked), Eupago mode and Eupago transaction, when they are set. The customer sees the method, entity, reference, amount and masked phone only while the order is in Pending Payment, and after that only the payment method title.

The Information tab of the order also shows Eupago requests: every payment attempt of the cart with Attempt, Method, Mode, Amount, Currency, Request status, Entity, Reference, Masked phone and Transaction. It is shown also for old orders and while the module is disabled.

Refunds

Refunds through Eupago from Magento are not supported. Refund the customer in the Eupago backoffice, then create a credit memo in Magento with Refund Offline to record it. Refund Offline does not send money back. A full refund closes the order.

License key

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

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

Eupago does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the API key of the current mode is set (Sandbox API Key in sandbox mode, Live API Key in live mode). The cart must be in euros (EUR) and its total above 0. With Multibanco the order total must be from 1 € to 999 999.99 €. 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 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 in the Advanced section. 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 for the store in the webhook URL. 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 Store credentials mismatch: the store in the webhook URL and the store of the order have different keys. Use the same keys, or set the webhook URL shown for the website of the order.

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

Webhook answers Busy or Retry: the cart was being processed by another request at the same moment, or an error occurred while the order was being updated. 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.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Eupago retries the notification later.

The customer is back in the cart with Eupago could not start the payment: turn on Debug Log and look at the Log field. Check the API key of the current mode and, for MB WAY, that the phone number is associated with MB WAY. The order of that attempt is cancelled.

A Multibanco order was cancelled before the customer paid: the Magento cron cancelled it after the Pending Payment Order Lifetime. Increase it in Stores > Configuration > Sales > Sales > Orders Cron Settings. For a payment that arrived later, read the order notes, check the stock and complete the order manually or refund the customer.

Order is On Hold after payment: read the order notes and the Eupago requests table. The amount or currency differed, the reference was unknown, or the cart was already paid with another order. Verify the payment in the Eupago backoffice, then complete the order or refund the customer.

There is no Refund button on the credit memo: the module has no online refunds. Refund in the Eupago backoffice and create the credit memo with 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.

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_EupagoPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_EupagoPayment to remove the data, then bin/magento module:disable Vibefox_EupagoPayment, delete the folder app/code/Vibefox/EupagoPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove Data on Uninstall is Yes, the settings and the log are removed too. If it is No, the settings are kept for a re-install. The Eupago payment attempts and notifications are always kept, so late notifications for old orders are still recognised after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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