VibeFox PayPlug for Adobe Commerce — Help

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 extension.

Currency and amounts: euro (EUR), from 0.99 to 20,000.00 per payment, the PayPlug defaults. With another cart currency or outside these limits the payment method is hidden.

PayPlug account: you need the secret keys of your PayPlug account: the test key (sk_test_...) and/or the live key (sk_live_...). No other keys are needed, and no notification has to be set up in PayPlug. Your store must be reachable from the internet to receive notifications; otherwise orders are confirmed when the customer returns from PayPlug.

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

2. Run bin/magento module:enable Vibefox_PayplugPayment 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 PayPlug 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. Paste your secret keys from the PayPlug portal (see Configuration). Set Enable to Yes and click Save Config. Test a payment with Test Mode = Yes, then set it to No to accept real payments.

The module adds the PayPlug 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 PayPlug payment attempts, their events and the refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox PayPlug 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. Write amounts with a dot as the decimal separator, for example 9.99.

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 (Title is required and must not exceed 128 characters.); a Sort Order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be a non-negative number.).

The PayPlug information row at the end of the group warns you, while Enable is Yes, when the secret key of the current mode is missing (PayPlug: the secret key of the current mode is missing. The method is hidden at checkout.) and when the store currency is not EUR (PayPlug accepts EUR only. Current currency: ... The method is hidden at checkout.). It also has a link to the PayPlug portal.

General

Enable: shows or hides PayPlug at checkout. It is shown only when the secret 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: PayPlug. Required, at most 128 characters.

Description: shown in the payment method list at checkout when the customer selects PayPlug. Default: Pay securely by card via PayPlug.

API keys

Find your secret keys in the PayPlug portal under Developers > API keys.

Test Mode: uses the test secret key for new payments. No real payments are processed. Payments made in the other mode keep using the key of their own mode for status checks and refunds. Default: Yes. While it is on, customers see Test mode: no real payment will be made. under the payment method.

Test Secret Key: your PayPlug test secret key: sk_test_ followed by at least eight letters or digits.

Live Secret Key: your PayPlug live secret key: sk_live_ followed by at least eight letters or digits.

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. A key with the wrong prefix or too short is not saved: the previous key is kept, the other settings are saved, and a warning is shown, for example Test Secret Key must start with "sk_test_" and contain at least eight letters or digits after it. The previous value was kept.

Notifications

The module sends its notification URL to PayPlug with every payment, so nothing has to be entered in the PayPlug portal. It is the storefront address of the store the order was placed in and looks like https://your-store/wcppaypluggateway/webhook/index/. The PayPlug information row shows it for the store view of the selected scope (the default store view in the Default Config). The URL must be reachable from the internet; otherwise orders are confirmed when the customer returns from PayPlug. PayPlug notifications have no signature: they only tell the module which payment to check, and the payment is always read from the PayPlug API with the secret key of the mode it was made in.

Orders

Order Status After Payment: what happens to the order after a successful payment.

Conditions

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

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

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

Maximum Order Total: offer PayPlug only up to this order total, in the base currency. Empty means no maximum.

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

The PayPlug limits of 0.99 to 20,000.00 EUR per payment always apply as well.

Advanced

Debug Log: writes API calls and notifications to var/log/ppg_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged. No credentials, card or customer data are logged. When the file grows over 5 MB, it is moved to var/log/ppg_debug.old.log.php and a new one is started. 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 deletes the module settings and the log (see Uninstall). The license key is always removed. The PayPlug payments, refunds and orders always stay. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default PayPlug) and sees the description and the note You will be redirected to the secure PayPlug payment page. In test mode the option also shows Test mode: no real payment will be made. 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 PayPlug payment for the order total in the order currency and sends the customer to the PayPlug payment page. The billing and delivery addresses, the e-mail and the language of the store view are passed to PayPlug. There the customer pays by card.

After paying, the customer returns to your store. The order is marked paid only after PayPlug confirms it: the module reads the payment from the PayPlug API when the notification arrives and when the customer comes back. Magento then creates the invoice with the PayPlug payment ID (pay_...) 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. A customer who comes back in another browser lands on the home page with Your payment with PayPlug has been received.

If the payment cannot be confirmed yet, for example when PayPlug cannot be asked at that moment, the customer sees a Payment confirmation page with We are confirming your payment with PayPlug. Please check again. and a Check again button. The notification confirms the order as soon as it arrives. If the payment needs your review (see Order statuses), the page says Your PayPlug payment needs manual review. Please contact us about this order.

If the customer cancels on the PayPlug page, or comes back without paying, the open PayPlug page is closed, so it cannot be paid later by mistake. The order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with PayPlug payment was canceled. You can try again. or Your PayPlug payment was not completed. Please try again.

When the customer pays the same cart again, the module first looks at the previous attempt. If it was paid in the meantime, that payment is confirmed instead of a new one. If it is still open for the same amount, currency and mode, the same payment page is used again. Otherwise the old page is closed at PayPlug and a new payment is created. If the result of an earlier attempt is unknown, no new payment is started and the customer sees An earlier payment has an uncertain result. Check PayPlug before starting another payment.

If PayPlug cannot start the payment, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example PayPlug could not accept your billing details (postcode). Please check them and try again. or The payment provider could not be reached. Please check its status before trying again. The technical reason is written to the log.

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), its open PayPlug page is closed and can no longer be paid.

The module works with the standard Magento checkout. It has no Oney installments, no saved cards, no embedded payment form, no subscriptions and no capture or void from Magento. PayPlug is not offered for orders created in the Admin or for multishipping checkout.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to PayPlug, but PayPlug has not confirmed the payment yet. There is no invoice.

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

On Hold: the paid amount or currency differs from the order (note Amount/currency mismatch); or a test payment was made while the store is in live mode, so no money was received; or the payment arrived for an order that had been cancelled, closed or put on hold. No invoice is created, and the note ends with Manual review required. No native invoice was created. An order is also put on hold when a payment is authorized but not captured: capture it in the PayPlug portal, and the order is released and invoiced once PayPlug reports it as paid. When money is at PayPlug (an authorized payment, a different amount or currency, a duplicate payment), the order is moved to Processing before the hold, so Unhold returns it to Processing and Magento does not cancel it as an expired Pending Payment order. If you decide not to keep such an order, release or refund the payment (in the PayPlug portal or with Refund held payment), then use Unhold and Cancel.

Canceled: the customer cancelled or did not complete the payment, the payment failed or could not be started, or the order was cancelled in Magento.

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

If a second attempt of a cart that is already paid is paid as well, the order is not changed. A note asks you to refund the duplicate payment in the PayPlug portal. A paid, cancelled or refunded order is never reopened by a later notification. The notes are order comments that the customer does not see.

PayPlug payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title, PayPlug payment (the payment ID) and PayPlug mode. The customer sees only the payment method title.

Below the order information the page has a PayPlug payments and notes block with a link to the PayPlug portal and, for every payment attempt of the order, the payment ID, the mode and the status, the amount expected, actually paid, refunded through the module and remaining, and the refund history. At the end it lists the PayPlug notes of the order. The block is shown also for old orders and while the module is disabled. Admin users whose role allows PayPlug reconciliation (under Sales > Operations > Orders in the role resources) also see the button Check PayPlug payment status, which reads the payment from PayPlug again and updates the order, for example after a capture in the portal.

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 PayPlug. 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 PayPlug.

The refund is made in the order currency, up to the amount PayPlug actually charged minus the refunds already made through the module. The comment of the credit memo is sent as the reason (up to 250 characters). The refund goes to the payment that actually paid the order, with the secret key of the mode it was made in, so that mode's key must be set. If PayPlug does not accept the refund, Magento shows the error, for example PayPlug rejected the refund. No credit memo was saved., and the credit memo is not created. After a successful refund Magento records it with the PayPlug refund ID as the transaction ID, and a note shows the amount, the refund ID and the reason. A full refund closes the order. Refunds are available once PayPlug has reported the payment as paid and the order has an invoice.

Refund held payment: an order on hold after a mismatch, a late payment or a duplicate payment has no invoice, so it cannot be refunded with a credit memo. In the PayPlug payments and notes block, users with the PayPlug reconciliation permission enter the amount in Refund amount in the actual payment currency, optionally a Reason, and click Refund held payment. The refund is limited to what PayPlug actually charged. A note records it; no invoice or credit memo is created.

Refunds made in the PayPlug portal arrive by notification and are added to the notes once: PayPlug reports a refund of ... made outside Magento, e.g. in the PayPlug portal. Record it in Magento manually if needed. They are not counted in the module refund totals, and the order and credit memos are not changed. Create a credit memo with Refund Offline if needed.

License key

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

PayPlug 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 secret key: Test Secret Key with Test Mode = Yes, Live Secret Key with Test Mode = No. The cart currency must be EUR and the cart total between 0.99 and 20,000.00 EUR. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total. Developers can change the currencies and limits with the Magento events ppg_supported_currencies and ppg_amount_limits (values in cents), and add fields to the payment request with ppg_payment_data.

The payment went through, but the order stays Pending Payment: the notification did not reach your store and the customer did not come back. Check that your store is reachable from the internet at https://your-store/wcppaypluggateway/webhook/index/, for example that no firewall, password protection or Magento maintenance mode blocks it. Open the order and click Check PayPlug payment status to confirm it. Turn on Debug Log and look at the Log field for rejected notifications.

Notification answers Verification failed.: the payment could not be read from the PayPlug API, for example because PayPlug did not answer or the secret key of the payment's mode is not set. The order is not changed.

Notification answers Temporarily unavailable.: the order was being updated by another request at the same moment, for example the customer return, or an error occurred while the order was being updated. The log shows the reason. The order is also confirmed when the customer returns or with Check PayPlug payment status.

Notification answers Unknown payment. or Payment does not belong to the order.: the payment was not created by this store or not for this order, for example a payment of another shop on the same PayPlug account. It is ignored.

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

The customer is back in the cart with an error after Place Order: turn on Debug Log and look at the Log field in the group. A wrong key gives This payment method is temporarily unavailable. Please choose another payment method.; other messages name the billing field PayPlug rejected. The order of that attempt is cancelled.

The customer sees An earlier payment has an uncertain result.: PayPlug did not give a clear answer when the previous payment of this cart was created. Check the payment in the PayPlug portal and in the order block before the customer tries again.

Order is On Hold after payment: read the notes in the PayPlug payments and notes block (see Order statuses), then release and process the order or refund the payment with Refund held payment.

Refund fails with The secret key of the original payment mode is missing.: the payment was made in test or live mode, and the secret key of that mode is not set. Enter it and try again.

Refund fails with The refund result is uncertain. or Unexpected response from PayPlug.: PayPlug did not give a clear answer. Check the refund in the PayPlug portal before trying again: until it is checked, the module refuses another refund of this payment with An earlier refund has an uncertain result. Reconcile it in PayPlug before sending another request.

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 with a credit memo; use Refund held payment in the PayPlug block.

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

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_PayplugPayment to remove the data, then bin/magento module:disable Vibefox_PayplugPayment, delete the folder app/code/Vibefox/PayplugPayment 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 PayPlug payment and refund records 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.

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