VibeFox Eupago for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

Currency: euro (EUR). Eupago charges euros only, so the euro must be enabled in your store; when the customer pays in another currency, 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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_eupago_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_eupago_gateway.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_eupago_gateway-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Eupago Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_eupago_gateway.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Eupago Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the Eupago keys and the webhook as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the webhook URL is different (see Webhook URL).

A new install starts with the payment method turned off and sandbox mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Eupago Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. When the payment method is enabled, the page warns you above the settings 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. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, the title must not be empty or longer than 128 characters, a payment method must be chosen, Sort Order must be a whole number, Total a number not below zero, and the geo zone and order statuses must exist. Otherwise an error names the problem, for example Enter a title for the payment method (1 to 128 characters)., and nothing is saved.

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, up to 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay securely via Eupago.

Payment Method: the one Eupago method offered at checkout.

Sort Order: the position of Eupago among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer Eupago only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Eupago is offered. Leave it empty to offer Eupago for any total. Independently of this field, Eupago is offered only when the customer pays in EUR, and Multibanco only for 1 € to 999 999.99 €.

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 at the Confirm Order step.

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. To remove a saved key, tick Clear the saved key on save under the field and click Save.

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. On OpenCart 3 the URL looks like https://your-store/index.php?route=extension/payment/wcp_eupago_gateway/webhook, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_eupago_gateway/payment/wcp_eupago_gateway.webhook. It is built from the storefront address of your OpenCart installation. 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 extension reacts to these notification statuses:

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 extension does not poll Eupago and the customer's return does not pay an order. The webhook also works while the store is in maintenance mode, because OpenCart 3 lets payment extension requests through and the extension adds a startup action for it on OpenCart 4 (also for the customer's return from the card page).

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). With Multibanco and MB WAY the order gets the awaiting status as soon as Eupago has issued the reference or the MB WAY request. With a card the order gets a status only from the Eupago notification. The order is paid only when a verified notification arrives and its mode, reference, amount and currency match the order. Each field below lists your OpenCart order statuses.

Order Status After Payment: the order status set when the payment is confirmed. Default: Processing.

Awaiting payment status: the Multibanco reference or MB WAY request was issued and the customer still has to pay. The Multibanco details are sent with this status (in the order e-mail and in the customer's order history). Default: Pending.

Manual review status: Eupago reported a payment that does not match the order (amount, currency, reference), a payment after the order was cancelled, or a payment of an order whose cart was already paid. A note explains why. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Cancelled status: Eupago reported the current payment of an awaiting order as cancelled or expired. Default: Canceled.

Failed status: Eupago reported the current payment of an awaiting order as failed (ERROR). Default: Failed.

Advanced

Debug Log: writes API calls and notifications to eupago_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to eupago_p_debug.old.log.php. 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 extension removes the gateway settings and the log. Orders and their Eupago payment records are kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. API and webhook keys are not exported.

Import: paste previously exported JSON and click Import to restore the settings. Saved keys are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Eupago). OpenCart creates the order at the Confirm Order step, still without a status. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. What happens when the customer clicks Confirm Order depends on Payment Method.

Multibanco: the customer sees You will receive Multibanco payment details after placing the order. The extension creates a Multibanco reference for the order total in euros, and the order gets Awaiting payment status. The order e-mail and the customer's order history get the comment Multibanco Payment Details with the entity, the reference and the amount. The order success page shows the same details. The customer pays at an ATM or in home banking.

MB WAY: the customer enters MB WAY Phone Number, filled in with the phone of the order. Portuguese numbers can be entered without +351. OpenCart 4 does not ask for a phone by default, so there the field is usually empty and the customer enters the number. A wrong number gives Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). The extension sends the payment request to the MB WAY app, and the order gets Awaiting payment status. The success page asks the customer to open the MB WAY app on the masked phone number and approve the request within 5 minutes. If Eupago refuses the request, the customer stays at the Confirm Order step with The MB WAY payment could not be started. Check that the phone number is associated with MB WAY and try again.

Credit Card: 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 store language. The order stays without a status, and the cart is kept. If the notification has arrived when the customer comes back, the customer sees the OpenCart order success 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 the buttons Check again and Back to checkout. 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. On OpenCart 4 these messages are shown above the checkout page.

For every method, the order is marked paid only after Eupago confirms it with a verified notification. The order then gets its status the standard OpenCart way, with stock update. The payment details are shown on the success page only while the order waits for the payment. If Eupago has already reported the payment as cancelled, expired or failed, the success page shows Your Eupago payment was not completed. Please contact us about this order.

OpenCart 3 creates a new order each time the Confirm Order step is shown. OpenCart 4 updates the order of the checkout, so after a cancelled or failed card payment the customer pays the same order with a new Eupago payment. If an earlier order of the same cart is already paid through Eupago, the customer goes to the success page and no new payment is created.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed without a payment meanwhile (for example its Multibanco reference expired, the MB WAY request was refused or you cancelled the order), the customer is sent back to the checkout with Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., and the next Confirm Order pays a new order of the cart. If that order is already paid or awaits its payment but the cart has changed since, including a new quantity, the message is Your previous order is already paid or awaiting its payment. Please confirm the order again: the cart will be paid with a new order. A paid order is never shown as paid for a different cart.

If Eupago cannot start the payment, the customer stays at the Confirm Order step 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. The order stays without a status, and the details are in the log.

The extension offers one Eupago method per installation. It has no refunds from the store, 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 status (missing order): a card payment was started and Eupago has not confirmed it yet, or it failed. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Awaiting payment status (default Pending): a Multibanco reference or an MB WAY request was created. The note shows the entity and reference or the masked phone number.

Order Status After Payment (default Processing): the payment was confirmed. A note shows the method, the Eupago transaction ID and the reference.

Manual review status (default Pending): Eupago reported a payment with a different amount or currency, with a reference that was not created for this order, for an order that had been cancelled or failed meanwhile (for example a Multibanco reference paid late), or for an order whose cart was already paid by another order. 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 status (default Canceled): Eupago reported the payment as cancelled or expired, for the current payment attempt of a waiting order.

Failed status (default Failed): 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. Notes are entries in the order History that the customer does not see.

VibeFox Eupago Gateway tab

In Sales > Orders open an order paid with Eupago. At the bottom of the order page, next to History and Additional, the VibeFox Eupago Gateway tab lists every payment attempt of the order: Date, Method (with a Sandbox label for sandbox payments), Amount, Entity / reference / phone, Eupago transaction ID and Status. For an order on manual review the tab shows a warning. Below it, Eupago notes lists the extension's notes on the order. The tab is read only and is shown to users who have access to the extension.

Refunds

Refunds are not available in this extension. Refund the customer in the Eupago backoffice and update the order in OpenCart manually. Product returns in Sales > Returns do not send money back through Eupago.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Eupago Gateway is the first block on Extensions > Extensions > Payments > VibeFox Eupago Gateway > Edit, 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: opencart-payment-eupago and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. 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 customer sees This payment method is not available. Please choose another one. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 customer must pay in EUR, and with Multibanco the order total must be from 1 € to 999 999.99 €. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays in the awaiting status or without a status: 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 extension 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 extension 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 an order 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 order was being processed by another request at the same moment, or the processing failed. 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 This payment method is temporarily unavailable: the API key of the current mode is missing. Enter it in the settings.

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 in the manual review status after payment: read the Eupago notes in the VibeFox Eupago Gateway tab. The amount or currency differed, the reference was unknown, the payment came after the order was cancelled, or the cart was already paid by another order. Verify the payment in the Eupago backoffice, then complete the order or refund the customer.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Eupago Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the webhook and the customer's return through in maintenance mode). If Delete Data on Uninstall is on, the other gateway settings (title, description, payment method, sandbox mode, keys, debug log) and the log are removed. If it is off, they are kept for a later re-install. The Eupago payment records of orders are always kept, so late notifications for old orders still work after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Eupago Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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