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

Stripe account: you need the secret API keys of your Stripe account and a webhook endpoint in the Stripe Dashboard (see Configuration). Only the secret keys and the webhook signing secrets are used. The publishable keys (pk_...) are not needed, because Stripe Checkout is a Stripe-hosted page.

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

2. Run bin/magento module:enable Vibefox_StripePayment 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 Stripe 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 Stripe secret keys, set up the webhook in the Stripe Dashboard and paste its signing secrets (see Configuration). Set Enable Stripe Gateway to Yes and click Save Config. Test a payment in test mode with the card 4242 4242 4242 4242, then set Test mode to No.

The module adds the Stripe payment method to the Magento checkout. It is off after installation (Enable Stripe Gateway = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Stripe payment attempts and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Stripe 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 read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "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; 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.

The Webhook section shows the state of the current mode: Test mode has no secret key: Stripe is hidden at checkout. (or the same for live mode), No webhook signing secret for the current mode: orders are confirmed only when the customer returns to the store after paying. and, while test mode is on, Test mode is on: no real payments are taken.

General

Enable Stripe Gateway: shows or hides Stripe 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: Stripe. Required, at most 128 characters.

Description: the text shown under the payment method when the customer selects it at checkout. Default: Pay securely with your credit or debit card via Stripe.

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

API keys

Copy the secret keys from Stripe Dashboard > Developers > API keys. Test and live keys are separate. Test mode uses only the test keys, live mode only the live keys.

Test mode: uses the Stripe test keys. No real money is charged; pay with Stripe test cards such as 4242 4242 4242 4242. Default: Yes. Set it to No to take real payments. While it is on, customers see Test mode: no real payment is taken. under the payment method.

Test Secret Key: the secret key of the test mode. It starts with sk_test_ (or rk_test_ for a restricted key).

Test Webhook Secret: the signing secret (whsec_...) of the webhook endpoint created in test mode.

Live Secret Key: the secret key of the live mode. It starts with sk_live_ (or rk_live_ for a restricted key).

Live Webhook Secret: the signing secret (whsec_...) of the webhook endpoint created in live mode.

Magento stores the keys and 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 key or secret, clear the field and click Save Config. When a new value does not start with the expected prefix, for example when a publishable key was pasted instead of a secret key, it is saved and a warning is shown: Stripe: the "Test Secret Key" value does not look right — it should start with sk_test_ / rk_test_.

Webhook

The webhook tells your store that a payment has been made. In Stripe Dashboard > Developers > Webhooks add an endpoint in test mode and another one in live mode. Use the URL shown in Endpoint URL in this section. It is the storefront address of the default store view and looks like https://your-store/wcpstripegateway/webhook/index/. Copy the URL exactly as the settings show it, because Stripe does not follow redirects.

Select these events for each endpoint (they are also listed in this section):

After creating each endpoint, copy its signing secret (whsec_...) from Stripe and paste it into Test Webhook Secret or Live Webhook Secret. The webhook reads the secrets of the default store view, so enter them in the Default Config or for the website of the default store view. Webhooks without a valid signature are rejected. An event must be signed with the secret of the mode the payment was made in, so a test secret never confirms a live payment. Without the webhook, an order is confirmed only when the customer comes back to the store after paying.

Orders

Order status after payment: the order status set after a successful payment.

Delayed payments wait in Pending Payment. Amount or currency mismatches always go to On Hold.

Conditions

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

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

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

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

Advanced

Logging: writes Stripe requests and webhooks to var/log/strg_debug.log.php in the Magento folder. The file cannot be opened from the web. Keys and customer data are not logged. Default: No. Nothing is written while it is off.

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 gateway settings and the log (see Uninstall). The license key is always removed. The Stripe transactions and refunds always stay, so old orders can still be refunded. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Stripe) and sees the description and the note You will be redirected to Stripe to complete the payment securely. 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 Stripe Checkout Session for the order total in the order currency and sends the customer to the Stripe payment page. There the customer pays by credit or debit card. The customer's e-mail is passed to Stripe, and the payment shows on the Stripe page as Order # and the order number.

After paying, the customer returns to your store. The order is marked paid only after Stripe confirms it: by the signed webhook or by a server-side request to Stripe when the customer comes back. Magento then creates the invoice with the Stripe payment ID, sets the status from Order status after payment and sends the order e-mail. The customer sees the standard order success page. If Stripe has not confirmed the payment yet, for example for a delayed payment or when Stripe cannot be reached, the success page shows Your payment is being confirmed by Stripe. You will receive an e-mail as soon as it is confirmed. The webhook confirms the order as soon as it arrives. A customer who comes back in another browser lands on the home page with Your payment with Stripe has been received. Order # and the order number.

If the customer cancels on the Stripe page, the Stripe session is closed, the order is cancelled (the stock goes back) and the customer is back in the cart with The payment was cancelled. You can try again or choose another payment method. If the payment was not completed, the message is The payment was not completed. You can try again or choose another payment method. The cart is restored. Each new attempt closes the previous Stripe session of the order and of the same cart, so the cart cannot be paid twice. If the previous session turns out to be paid already, that payment is confirmed instead of a new one. If the cart was already paid with another order, the new order is cancelled and the customer sees Your cart has already been paid with order # and the order number.

If Stripe cannot start the payment, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example The order total is below the minimum amount Stripe can charge in this currency. Please choose another payment method. 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 Stripe session is closed and can no longer be paid.

The module works with the standard Magento checkout. It takes card payments only, captured immediately on the Stripe page. It has no saved cards, subscriptions or recurring payments, no on-site card form, no Apple Pay or Google Pay buttons on your site and no separate authorize and capture. Stripe 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 Stripe, but Stripe has not confirmed the payment yet, or a delayed payment is still processing. There is no invoice.

Processing, Complete or On Hold: the payment was confirmed. The status follows Order status after payment. The invoice is created with the Stripe payment ID (pi_...) as the transaction ID, and a note shows the Stripe payment, the session and how it was confirmed (webhook or return).

On Hold after a mismatch: Stripe reported a different amount or currency than the order total. No invoice is created. The note shows the amount paid and the amount expected. Check the payment in the Stripe Dashboard, then fulfil the order or refund the payment there.

On Hold after a late payment: the payment arrived after the order had been cancelled or put on hold. The note asks you to check the stock and fulfil the order, or refund the payment.

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

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

If a second payment arrives for an order that is already paid, the order is not changed. A note asks you to check it and refund the duplicate in the Stripe Dashboard. The notes are order comments that the customer does not see.

Stripe payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for the Stripe payment, Stripe mode (Test or Live), Stripe payment (the payment ID), Checkout Session and Charged by Stripe (the amount and currency Stripe charged). The customer sees only the payment method title.

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

The refund is made in the order currency, up to the amount Stripe charged minus the amounts already refunded. The refund is sent in the mode the payment was made in (test or live), so that mode's secret key must be set. If Stripe does not accept the refund, Magento shows the error and the credit memo is not created. After a successful refund Magento records it on the order with the Stripe refund ID (re_...) as the transaction ID. A full refund closes the order. Refunds are available once Stripe has confirmed the payment and the order has an invoice.

Refunds made in the Stripe Dashboard arrive by the charge.refunded webhook and are added to the order notes with the total refunded in Stripe and in Magento. The order and credit memos are not changed automatically. 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 Stripe Gateway is the first row of the VibeFox Stripe 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-stripe 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, Stripe 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

Stripe does not appear at checkout: check that the license is active and Enable Stripe Gateway is Yes for the website of the store, and that the current mode has a secret key: Test Secret Key in test mode, Live Secret Key in live mode. The Webhook section shows a warning when the key is missing. 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 webhook is not working. In the Stripe Dashboard check that the endpoint exists in the mode you use (test or live), that its URL is exactly the one shown in Endpoint URL and that the four events are selected. Check that the signing secret of that endpoint is in the matching field (Test Webhook Secret or Live Webhook Secret) in the Default Config or for the website of the default store view. The Stripe Dashboard shows the answer of your store for each webhook. 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. Paste the signing secret into the settings.

Webhook answers Invalid signature: the signing secret belongs to another endpoint or another mode, or the server clock is wrong. Stripe signatures are accepted within 5 minutes of the server time. The answer is also Invalid signature when an event of a live payment is signed with the test secret or the other way round: check that the test and live secrets are not swapped.

Webhook answers Busy, retry: the order was being confirmed by another request at the same moment, or an error occurred while the order was being updated. Stripe retries the webhook automatically. Turn on Logging to see the reason.

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

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

The value does not look right warning on save: a key was pasted into the wrong field. Secret keys start with sk_test_ / rk_test_ or sk_live_ / rk_live_, webhook secrets with whsec_.

The customer is back in the cart with an error after Place Order: turn on Logging and look at the Log field in the Advanced section. A wrong key gives the message that the payment method is not configured correctly. An order total below the Stripe minimum for the currency (for example 0.50 EUR) cannot be paid with Stripe. The order of that attempt is cancelled.

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

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

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

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 Stripe Dashboard.

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

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

The license key and license status 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 Stripe 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.

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