Назад

VibeFox PayPal for Adobe Commerce — Допомога

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.

PayPal account: a PayPal Business account with a REST API app in the PayPal Developer Dashboard. You need the Client ID and the Secret of the app. Sandbox and live apps have different credentials. No webhook is needed: the module confirms each payment on your server through the PayPal API while the customer is at the checkout.

Currency: the currency the customer pays in must be one of the currencies PayPal supports: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, MYR, NOK, NZD, PHP, PLN, SEK, SGD, THB, TWD or USD. For other currencies the payment method is hidden.

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

2. Run bin/magento module:enable Vibefox_PaypalPayment 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 PayPal 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. In the PayPal Developer Dashboard create a REST API app (sandbox and/or live) and copy its Client ID and Secret. Enter the credentials of the mode you use, choose the Payment action, set Enable to Yes and click Save Config. Test with a PayPal sandbox buyer account, then set Sandbox mode to No and enter the live credentials.

The module adds the PayPal payment method with PayPal Smart Payment Buttons 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 three tables for the PayPal payment attempts, their processing steps and refunds. It works alongside the PayPal module that comes with Magento: it has its own payment method code, its own settings and its own copy of the PayPal script.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox PayPal 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 and the log are available in the Default Config only. Save Config saves the whole page. Saving the settings drops the cached PayPal access tokens, so new credentials are used at once.

If a value is wrong, Magento shows an error and nothing on the page is saved: Title is required and must not exceed 128 characters., Sort order must be a whole number., Order total must be a non-negative number. (for Minimum Order Total and Maximum Order Total; use a dot as the decimal separator, for example 9.99).

At the bottom of the group, while Enable is Yes, the page warns PayPal is enabled but the Client ID or Secret of the selected mode is missing. and PayPal does not support the store currency followed by the currency code (the base currency of the store). While sandbox mode is on it shows Sandbox mode is on. No real money is moved. The page always shows No webhook is required. Payments are verified through the authenticated PayPal API.

Enable: shows or hides PayPal at checkout. It is shown only when the Client ID and Secret of the selected mode are set. Default: No.

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

Description: shown in the payment method list at checkout, under the title when the customer selects PayPal. Default: Pay with your PayPal account or a card via PayPal.

Sandbox mode: payments go to the PayPal sandbox with the sandbox credentials; no real money is moved. Default: Yes. Set it to No to accept live payments. Only the Client ID and Secret fields of the selected mode are shown; the credentials of both modes stay saved. Captures, voids and refunds always use the mode the order was paid in. While it is on, customers see Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged. under the payment method.

Sandbox Client ID: the Client ID of your sandbox REST API app.

Sandbox Secret: the Secret of your sandbox REST API app.

Live Client ID: the Client ID of your live REST API app.

Live Secret: the Secret of your live REST API app.

The Client ID is public: it is passed to the PayPal script in the customer's browser. Magento stores the two secrets encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved secret, type a new value to change it. To delete a saved secret, clear the field and click Save Config.

Payment action: what happens when the customer approves the payment. Default: Capture.

Capture: the customer is charged immediately, and Magento creates the invoice.
Authorize: the funds are only reserved. Capture them later with the invoice of the order (Capture Online) or release them with Void (see Orders and refunds).

Order status after payment: the order status set after a completed capture. Default: Processing.

Processing: the standard Magento status for paid orders.
Complete (virtual orders): a paid order with only virtual products becomes Complete. Orders with products to ship stay Processing and are completed by the standard shipment.
On Hold: every paid order waits for your manual review. The payment and the invoice are still recorded on the order.

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

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

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

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

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

Debug log: logs PayPal requests to var/log/wc_plg_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, even when this setting is No. Credentials, tokens, e-mail addresses and the texts of PayPal error answers are not logged. Default: No.

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

The last row of the group (Default Config) shows the size and the latest entries of the log, or The log is empty. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default PayPal) and sees the description and the PayPal buttons. The PayPal script is loaded only on the checkout page and in its own namespace, so it does not clash with the PayPal module of Magento. A click on a PayPal button creates a PayPal order on your server for the cart total in the cart currency. The amount is always calculated on the server, never in the browser. HUF, JPY and TWD amounts are sent without decimals, as PayPal requires. In PayPal the payment is described as Order at and the name of your store: Store Name in Stores > Configuration > General > General > Store Information, or, when that field is empty, the name of the store in Stores > All Stores (for example Main Website Store).

The customer approves the payment in the PayPal window with a PayPal account or another funding source PayPal offers. The checkout then places the order automatically. If it cannot, for example because the terms and conditions are not accepted yet, the checkout shows PayPal payment approved. Click Place Order to complete it. If the customer clicks Place Order without approving a payment, the message is Please approve the payment using the PayPal button first. When the cart total changes after the approval, the approval is dropped and the customer clicks the PayPal button again. If the customer closes the PayPal window, the checkout shows PayPal approval was canceled. You can approve again.

Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. Your server then reads the PayPal order and checks that it is approved, that it was created for this cart and that its amount and currency match the order. Only then the payment is captured (or authorized). The order is marked paid only after PayPal confirms it: Magento creates the invoice with the PayPal capture 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 order total no longer matches the approved amount, nothing is captured, the order is cancelled (the stock goes back), the cart is restored and the customer sees The order total changed. Please approve the new total in PayPal. If PayPal declines the payment, the same happens with PayPal declined the payment. Please approve another payment method.

If PayPal does not answer or the capture is still pending, the customer sees the page PayPal payment status with a message such as PayPal is processing the payment. Check again before paying again., the line Do not pay again while this payment is being checked. and a Check again button. The button reads the payment again; it also works in another browser. An earlier attempt is never charged twice: the same approval is reused, and a cart with an open or uncertain PayPal payment cannot start a new one (An earlier payment needs checking. Do not approve another payment.). A cart that was already paid shows This cart has already been paid. Do not pay again.

The module works with the standard Magento (Luma) checkout. It has no PayPal webhooks, no Pay Later messages, no card fields, no saved payment methods or subscriptions and no PayPal buttons on product or cart pages. PayPal is not offered for orders created in the Admin. The addresses entered in the Magento checkout are used, not an address from PayPal.

Orders and refunds

Order statuses

Pending Payment: the order was placed, but PayPal has not confirmed the payment yet, or the capture is PENDING at PayPal, for example under payment review. There is no invoice.

An unpaid order in Pending Payment can be cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). While a capture is pending or its result is uncertain, the order is not cancelled. In the Admin, Magento shows Check the PayPal payment status before canceling this order. The cron leaves such an order in Pending Payment with a note asking you to use Check PayPal payment status, and goes on cancelling the other expired orders. An order whose PayPal payment was approved but never completed is cancelled as usual.

Processing, Complete or On Hold: the capture is completed. The status follows Order status after payment. The invoice is created with the PayPal capture ID as the transaction ID, and a note shows the capture and the amount.

Processing without an invoice: the payment was authorized (payment action Authorize). A note says that the funds are reserved, not captured.

On Hold after a mismatch: PayPal charged another amount or currency than the order total, the payment could not be read from the PayPal answer, or the payment arrived for an order that had been cancelled or put on hold. No invoice is created. The note explains it, and the amount actually charged is kept for reconciliation. Check the payment in your PayPal account, then fulfil the order or refund the payment.

Canceled: the approval failed (total changed, payment declined), a pending capture was declined, or the order was cancelled or voided in Magento.

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

If a second PayPal approval arrives for a cart that is already paid, it is not captured, and a note on the order says so. The notes are order comments that the customer does not see.

PayPal payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and PayPal order, PayPal capture or PayPal authorization and Payment mode (sandbox or live). The customer sees only the payment method title.

The Information tab of the order also has a VibeFox PayPal Gateway block. It is shown for old orders too, also when the module is disabled. For each PayPal attempt of the cart it shows the PayPal order ID, the mode and the state, the authorization and capture IDs, the expected amount, the amount PayPal charged, the refunded and remaining amounts, the link View transaction in PayPal (sandbox or live account) and the refund history with the reasons.

Check PayPal payment status: shown while a capture is pending or uncertain. It reads the payment again. A completed capture creates the invoice; a declined one cancels the order. Admin users need the right to edit orders.
Refund held payment: shown for a completed capture that is on hold after a mismatch or was not matched to an invoice. Enter the amount (the remaining amount is filled in) and a reason. The refund is made in the currency PayPal charged, up to what is left of it. It does not create an invoice or a credit memo; a note is added to the order. Admin users need the credit memo permission.

Authorized payments

To capture an authorized payment, open the order, click Invoice and save it with Capture Online. Only the full order total can be captured (Capture the complete PayPal authorization.). A completed capture closes the authorization and records the payment. A capture that is still pending at PayPal is not invoiced: use Check PayPal payment status later. To release the funds, use Void on the order page; Cancel also voids the authorization and cancels the order. An order with a pending or uncertain capture cannot be cancelled: Check the PayPal payment status before canceling this order.

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 PayPal. Full and partial refunds are supported. The comment of the credit memo is passed to PayPal as a note to the buyer. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through PayPal.

The refund is made in the order currency, up to the amount PayPal charged minus the amounts already refunded, and is sent to the mode the payment was made in (sandbox or live), so that mode's credentials must be set. For HUF, JPY and TWD PayPal accepts only whole amounts, while Magento can keep decimals in the order total (for example after tax). The credit memo amount is then rounded to a whole amount so that all refunds of the order add up to what PayPal charged, and the credit memo that refunds the order completely returns exactly what is left. If PayPal does not accept the refund, Magento shows the error, for example PayPal rejected the refund. No native credit memo was saved., and the credit memo is not created. After a successful refund Magento records it with the PayPal refund ID as the transaction ID. A PENDING refund is completed by PayPal later, and a note says so. A full refund closes the order. A refund with an uncertain result is never repeated automatically: The PayPal refund result is uncertain. Reconcile it before trying again.

Refunds, disputes and reversals made in your PayPal account are not synced to Magento. 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 PayPal Gateway is the first row of the VibeFox PayPal 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-paypal 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, PayPal is not shown to customers at checkout. If a payment is started anyway, your server refuses to create the PayPal order, so no order is placed and nothing is charged; the checkout shows PayPal could not complete approval. Please try again. 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 approved are still confirmed, and captures, voids, status checks 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

PayPal does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the selected mode has its credentials: Sandbox Client ID and Sandbox Secret in sandbox mode, Live Client ID and Live Secret in live mode. The settings page shows a warning when they are missing. Check that the cart currency is supported by PayPal and the cart total is above zero. 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 module has no webhook, so the payment is confirmed only while the customer is at the checkout, or later with Check again or Check PayPal payment status. This happens when PayPal did not answer during the capture or the capture is PENDING at PayPal. Open the VibeFox PayPal Gateway block of the order and click Check PayPal payment status, or check the payment in your PayPal account. A retry never charges twice.

The PayPal buttons do not show: the checkout says PayPal buttons could not be loaded. Please try again. The PayPal script did not load in the browser, for example because a browser extension blocks www.paypal.com or because of a network problem.

PayPal could not complete approval. Please try again.: your server could not create the PayPal order. The credentials may be wrong or belong to the other mode: copy the Client ID and Secret of the right app again. Turn on Debug log and look at the log in the settings to see the reason.

This payment is already being processed. Please try again shortly.: the same cart was submitted twice at the same moment. The customer waits a moment and tries again.

Your PayPal payment needs manual review. Do not pay again.: the order is On Hold after a mismatch. Read the order notes and the VibeFox PayPal Gateway block (see Order statuses), then fulfil the order or use Refund held payment.

Capture of an authorization fails: the authorization may be expired or already voided. Magento shows the error, and the invoice is not created.

Refund fails: the order has no completed PayPal capture (only an authorization or a pending capture), the amount is more than what is left to refund (Refund exceeds the remaining amount actually captured by PayPal.), the amount entered in Refund held payment has decimals in HUF, JPY or TWD (Refund amount must be positive and exact for the payment currency.), or the credentials of the mode the payment was made in are missing.

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 VibeFox PayPal Gateway 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_PaypalPayment. It removes the data and the code.

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

The license key and license status and the cached PayPal access tokens are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The PayPal 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.

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