VibeFox Worldline 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 JSON extensions.

Worldline account: a Worldline Direct (formerly Ingenico Direct) merchant account. Test and live accounts are separate and have different credentials. For each account you need the Merchant ID (your PSPID), an API Key ID with its Secret API Key, and a webhook key with its secret. All of them are created in the Worldline Merchant Portal (see Configuration).

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

2. Run bin/magento module:enable Vibefox_WorldlinePayment 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 Worldline 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 credentials and click Save Config, then Test credentials. Add the webhook URL in the Merchant Portal of the test account and enter the webhook key and secret (see Configuration). Set Enable to Yes, click Save Config and make a test payment. Then enter the live credentials, repeat the webhook setup in your live account, click Live credentials and set Test mode to No.

The module adds the Worldline 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 its own tables for the Worldline payment attempts, processed events and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Worldline 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. The license block, the Log field and Remove data on uninstall are shown 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: 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; a Minimum order total or Maximum order total that is not a number of 0 or greater (use a point as the decimal separator, for example 9.99).

Connection and webhooks

This block is shown right below the license block. When Enable is Yes, it warns you about the current mode: Worldline credentials (Merchant ID, API Key ID and Secret API Key) are incomplete. The payment method is hidden at checkout., No webhook secret is configured for the current environment. Confirm payments on return or configure signed webhooks. and, while test mode is on, Test mode is on (pre-production environment): no real money is charged.

Endpoint URL: the webhook URL to add in the Merchant Portal (see Webhooks below).

Test credentials and Live credentials: check the saved credentials of each account with a test call to Worldline. Save your changes first (Save the credentials before checking the connection.). When the Scope is a website, the settings of that website are checked. The answer appears below the buttons: Test credentials: connection successful. (or the same for live), API credentials are not configured., Worldline connection failed (HTTP and the HTTP code, or Worldline connection could not be checked.

General

Enable: shows or hides Worldline at checkout. It is shown only when the current mode has a Merchant ID, an API Key ID and a Secret API Key. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order: later changes do not rename existing orders. Default: Worldline. Required, 1 to 128 characters.

Description: the text shown under the payment method at checkout. Default: Pay securely via Worldline. Leave it empty to show no description.

Worldline accounts

Get the credentials in the Worldline Merchant Portal of the test account and of the live account. Your PSPID is the Merchant ID. Developer > Payment API creates the API Key ID and the Secret API Key, Developer > Webhooks the webhook key and secret.

Test mode: switches both the API endpoint and the credentials. Test mode uses the pre-production environment and the test credentials, live mode the production environment and the live credentials. Default: Yes. Set it to No to take real payments. While it is on, customers see Test mode — no real money is charged. under the payment method.

Test Merchant ID (PSPID): the PSPID of your test account.

Test API Key ID: the API Key ID created in Developer > Payment API of the test account.

Test Secret API Key: the Secret API Key that belongs to that API Key ID.

Test Webhook Key ID: optional. When set, only webhooks sent with this key ID are accepted.

Test Webhook Secret: the webhook secret of the test account. It is used to check the signature of every webhook.

Live Merchant ID (PSPID): the PSPID of your live account.

Live API Key ID: the API Key ID created in Developer > Payment API of the live account.

Live Secret API Key: the Secret API Key that belongs to that API Key ID.

Live Webhook Key ID: optional. When set, only webhooks sent with this key ID are accepted.

Live Webhook Secret: the webhook secret of the live account.

Magento stores the secret API keys and webhook secrets 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 secret, clear the field and click Save Config.

Webhooks

The webhook tells your store about payments even when the customer does not come back to the store, for example after closing the browser or when a payment is confirmed later. In the Merchant Portal open Developer > Webhooks of the test account and add the URL shown in Endpoint URL. It looks like https://your-store/wcpworldlinegateway/webhook/index. Copy the URL exactly as the settings show it: it must answer without redirects. Then enter the webhook key ID and secret in Test Webhook Key ID and Test Webhook Secret. Do the same in the live account with the live fields.

The module answers the endpoint verification request of Worldline automatically. It handles payment events (payment status changes) and refund events (refund status changes). Other events are accepted and ignored. Webhooks without a valid signature are rejected. An event must be signed with the secret of the account the payment was made in, so a test webhook never confirms a live payment. A webhook is also ignored when it comes from another Merchant ID than the one of that account. Enter the webhook secrets in the Default Config or for the website of the store the payment was made in. Without the webhook, an order is confirmed only when the customer comes back to the store after paying.

Payment page and orders

Payment page template: optional name of a hosted checkout template (variant) uploaded in the Merchant Portal. Leave it empty for the default Worldline page.

Order status after payment: the order status once Worldline confirms the captured payment. Payments are always requested as a direct sale (authorization and capture).

Amount or currency mismatches always go to On Hold.

Conditions

Payment from specific countries: No offers Worldline for every country your store allows, Yes only for the countries below. Default: No.

Specific countries: offer Worldline only for billing addresses in these countries (the shipping address is used when the billing country is not known yet).

Minimum order total: offer Worldline only from this order total, in the base currency of your store. Empty means no minimum.

Maximum order total: offer Worldline only up to this order total, in the base currency. Leave it empty or enter 0 for no maximum.

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

Advanced

Logging: writes all API requests and webhooks to var/log/wlg_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors and warnings are always logged, also when this is off. Keys, card data and personal data are masked. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the module settings and the log (see Uninstall). The license key is always removed. The Worldline transactions and refunds always stay, so old orders can still be refunded. Default: No.

Log: 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 Worldline) and sees the description and the note You will be redirected to Worldline to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates a Worldline hosted checkout for the order total in the order currency and sends the customer to the Worldline payment page. There the customer pays with a card, a wallet or another payment method enabled in your Worldline account. The billing name, address, company, e-mail and phone are passed to Worldline, and the payment page opens in the customer's language when Worldline supports it. Each payment attempt gets its own reference made of MG-, the cart ID and a random part.

After paying, the customer returns to your store. The module checks the return against the stored attempt and reads the payment status from Worldline on the server. The order is marked paid only after Worldline confirms it: by this status check or by a signed webhook. Magento then creates the invoice with the Worldline payment ID as the transaction ID, sets the status from Order status after payment and sends the order e-mail. The customer sees the standard order success page.

If the payment is not confirmed yet, the customer sees the page Worldline payment confirmation with We could not confirm your payment yet. If you completed the payment, please do not pay again. (for an authorized payment: Your Worldline payment is authorized. The order is marked paid only when Worldline confirms the capture.) and the buttons Check again and Back to checkout. The webhook confirms the order as soon as it arrives. Back to checkout first checks the payment with Worldline: if it was cancelled or declined, the order is cancelled and the cart is restored; if the payment may still be completed, the customer goes to the cart with Worldline payment is not confirmed yet. Check the previous payment before retrying. and the order keeps waiting. The return works only in the browser in which the order was placed; in another browser the customer lands on the home page, and the webhook confirms the order.

If the customer cancels on the Worldline page or the payment is declined, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Your Worldline payment was not completed. Please try again or choose another payment method.

If the payment page cannot be created, the order is cancelled, the cart is restored and the customer sees the reason in the cart. When Worldline refuses the request, does not answer (for example a timeout or a connection error) or answers without a payment page, the message is Payment error: Could not create checkout session. Please try again. (or Payment error: Invalid response from payment gateway.); the technical reason is written to the log. Such an attempt never reached a payment page, so it does not block the next try. When the credentials of the current mode are missing or Worldline is disabled in the meantime, the message is Worldline is not available right now. Please choose another payment method.

When the customer pays the same cart again, the module first checks the previous attempt with Worldline. If the previous payment page of the same order is still open for the same amount and mode and was created less than 30 minutes ago, the customer is sent back to it. If a previous payment of the cart is paid, authorized or waiting for review, or its payment page is still open, no new payment is started: the new order is cancelled and the cart restored with A previous payment for this cart needs confirmation or manual review. or A previous payment page is still open. Check it before starting another payment.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), the module does not close the Worldline payment page. A payment made after that does not reopen the order (see Orders and refunds).

The module works with the standard Magento checkout. It takes one-time payments as a direct sale on the Worldline page. It has no saved cards or tokenization, no subscriptions, no embedded card form, no capture or cancel of authorizations from Magento, no surcharging and no automatic webhook registration. Worldline 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 Worldline, but Worldline has not confirmed the payment yet. There is no invoice.

Processing without an invoice: Worldline reports the payment as authorized or with the capture requested, but not captured yet. Magento records the authorized amount, and the note says Worldline: payment … is authorized, but capture is not confirmed. The order is not in Pending Payment, so the Magento cron does not cancel it. When the webhook confirms the capture, the invoice is created as for any paid order; if Worldline rejects the capture, the order is cancelled. If the note says the payment is not captured, capture it in the Worldline Merchant Portal.

Processing or Complete: the payment was captured. The status follows Order status after payment. The invoice is created with the Worldline payment ID as the transaction ID, and a note shows the amount, the payment ID, how it was confirmed (signed webhook or status check) and the mode (test or live).

On Hold: the payment does not match the order, for example the amount or currency differ or the payment belongs to another attempt. The note shows the payment ID and the reported amount. No invoice is created. Check the payment in the Merchant Portal, then fulfil the order or refund the payment there.

Canceled: the customer cancelled the payment, it was declined or failed, the capture was rejected, the payment could not be started, or the order was cancelled in Magento.

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

If a payment arrives for a cancelled or refunded order, the order is not reopened. A note says The order was NOT reopened; review it in the Merchant Portal. If a second payment arrives for an order that is already paid, or the cart was already paid with another order, the order is not changed and a note asks you to review or refund that payment in the Merchant Portal. The notes are order comments that the customer does not see.

Worldline payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and one line per Worldline attempt (Worldline attempt): the reference, the hosted checkout ID, the payment ID, the mode, the attempt status, the Worldline status, the expected amount and the amount charged. Each refund has its own line (Worldline refund) with the Worldline refund ID, the mode, the status and the amount. The customer sees only the payment method title. The lines are also shown while the module is disabled.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Worldline. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Worldline.

The refund is made in the order currency, up to the amount Worldline charged minus the amounts already refunded. In zero-decimal currencies such as JPY or KRW, Magento keeps totals with two decimals while Worldline charged whole units: each credit memo refunds the difference of the rounded refunded totals, and the last credit memo refunds exactly what is left of the charge, so a full refund always matches the charge. The refund is always sent to the environment of the original payment (test or live) with that account's credentials, so they must be set. A refund retried after a timeout is not executed twice: retry the same amount. Only one operation on an order runs at a time. If Worldline does not accept the refund, Magento shows the error and the credit memo is not created. After an accepted refund Magento records it on the order with the Worldline refund ID as the transaction ID. A full refund closes the order. Refunds are available once Worldline has confirmed the captured payment and the order has an invoice.

Refund status changes from Worldline arrive by webhook, update the refund line and are added to the order notes (Check the Merchant Portal and native Credit Memos for reconciliation.). Refunds made in the Merchant Portal do not create credit memos. Create a credit memo with Refund Offline or update the order manually if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Worldline Gateway is the first row of the VibeFox Worldline 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-worldline 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, Worldline 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 This payment method is not available. Please choose another one. 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, and refunds work.

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

Worldline 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 a Merchant ID, an API Key ID and a Secret API Key: the test fields in test mode, the live fields in live mode. The Connection and webhooks block shows a warning when they are missing. Check Payment from specific countries and 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 webhook is not working. In the Merchant Portal of the account you use (test or live) check that the endpoint exists and that its URL is exactly the one shown in Endpoint URL, without redirects. Check that the webhook secret of that account is in the matching field (Test Webhook Secret or Live Webhook Secret) and that the webhook key ID field is empty or matches the key. The order is also confirmed when the customer returns to the store after paying.

Webhook answers Webhook secret not configured: neither webhook secret is set. Enter the webhook secret in the settings. Worldline retries the webhook.

Webhook answers Invalid signature: the webhook secret belongs to another account or another key, or the webhook key ID does not match the key that sent the webhook. Check that the test and live secrets are not swapped.

Webhook answers Missing signature, Empty body or Invalid JSON: the request did not come from Worldline in the expected form, or a proxy or redirect changed it. Check that the URL answers without redirects.

Webhook answers Ignored: the event belongs to no payment of this store, or it came from another Merchant ID or account than the one of the payment. Check Test Merchant ID (PSPID) or Live Merchant ID (PSPID) and the webhook secret of that mode.

Webhook answers Retry later: the order was being updated by another request at the same moment, or an error occurred while the order was being updated. Worldline retries the webhook. Look at the Log field for the reason.

The webhook URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Worldline.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Worldline retries the webhook later, and the order is also confirmed when the customer returns.

Test credentials or Live credentials shows an error: save the settings first, then check that the Merchant ID, API Key ID and Secret API Key come from the same account and that the test values are in the test fields and the live values in the live fields.

The customer is back in the cart with an error after Place Order: look at the Log field in the Default Config. Errors are logged even when Logging is off. For full details of the requests, turn on Logging and try again. The order of that attempt is cancelled.

Test payments do not confirm a live payment: test and live are kept apart. Switch Test mode to the mode you want and use that account's credentials and webhook.

Order is Processing without an invoice: the payment is authorized, but Worldline has not confirmed the capture yet (read the order notes). The webhook creates the invoice when the capture is confirmed; check the capture in the Merchant Portal.

Order is On Hold after payment: read the order notes (see Order statuses), then fulfil the order or refund the payment in the Merchant Portal.

Refund fails with a message about the environment: the payment was made in the test or live environment, and the credentials of that environment are not set. Enter them and try again.

Refund fails with A previous Worldline refund is unconfirmed: the answer to an earlier refund was lost. Retry the same amount, or check the refund in the Merchant Portal first.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded online; refund it in the Merchant Portal.

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: the Magento event wlg_hosted_checkout_data changes the hosted checkout request before it is sent, for example to limit the payment methods shown. It cannot change the amount, the currency or the reference.

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

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

The license key and license status are always removed. If Remove data on uninstall is Yes, the module settings and the log are removed too. If it is No, the settings are kept for a re-install. The Worldline transactions and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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