Configuring the Magento 2 module

    Learn how to configure the Stripe Magento 2 module to choose payment methods for your Magento site and other options.

    Find the module configuration options

    Navigate to the configuration section for the Stripe module (Stores > Configuration > Sales > Payment Methods):

    Configuring the Stripe module

    Configure API keys Required

    1. Mode: If you would like to test a payment, use test mode. Change to live mode when you’re ready to accept live transactions. You can learn more about testing payments on Stripe.
    2. API keys: Fill in the test and live keys that Stripe provides to you when creating your account. To get them,log into Stripe, navigate to your account settings, and click API Keys.

    Configuring Stripe API keys

    1. Webhooks signing secret: This is an optional key that you can use to verify the origin of webhooks sent to your website. Although the setting is optional, you should set it to ensure that the webhooks you receive are sent by Stripe, rather than a third party. You can retrieve the signing key from the specific webhook that you configured for your website. If you configure the same webhook endpoint for both live and test mode, the signing secret will be different for each mode.

    Configure webhooks Required

    Stripe can send webhook events to notify you whenever a payment event occurs on your account. This module uses webhooks to:

    • Create credit memos or invoices in Magento when a payment is refunded or captured.
    • Issue invoices for SEPA Direct Debit and other asynchronous payment methods like SOFORT.
    • Change the order status from Pending to Processing when a charge succeeds.
    • Cancel an order when a charge fails.

    The order cancellation event is especially important for redirect-based payment methods, where a customer may close the browser tab (and not return to your website) after they authorize a payment. This is automatically handled when webhooks are configured.

    You can configure webhooks in the Webhook settings section of the Dashboard. Click Add endpoint and enter the details:

    • Endpoint URL: https://www.yourdomain.com/stripe/webhooks
    • Events to send: Select all events for Charges, Sources, Payment Intents and Invoices.

    After you add them, your list of webhook endpoints should look like this:

    Configuring webhook endpoints in the Stripe Dashboard

    If you have multiple domain names or store views using the same Magento installation, you only need to configure a single webhook endpoint. The module automatically notifies all modules and add-ons across your Magento installation when it receives a webhook event. As an example, if the following endpoints are available, you can choose either endpoint and specify just one:

    • https://www.your-domain.com/en_us/stripe/webhooks
    • https://www.your-uk-domain.co.uk/en_gb/stripe/webhooks

    Configure card payments Required

    You can define how card payments are accepted with this module using several configuration options:

    • Enabled: Enable or disable card payments at checkout.
    • Title: Change this to whatever you want to display to the customer on the checkout page.
    • Apple Pay: Enabling this feature displays an Apple Pay, Google Pay, or Microsoft Pay button on the checkout page after you configure some additional features.
    • Apple Pay Location: Use this setting to control whether you want the Apple Pay button to appear inside, above, or below the payment form. The default is to display the button inside the payment method form, but if you need to make the button more prominent, you can reconfigure it to appear above or below any other payment methods that you use. Base this decision on how many payment methods are enabled, which one is expanded by default, your theme layout and any other OneStepCheckout specific adjustments adjustments that you need to make (such as compacting the form into a narrower column).
    • Payment Action: Select Authorize and Capture if you want to charge customer cards immediately after a purchase. This is the default option and does not require you to do anything after the customer has placed the order. If you prefer to finalize the payment later, you can choose Authorize Only which authorizes (and locks) the order amount on the customer’s card so you can capture the amount later by issuing an invoice. You can read more about capturing payments using invoices with this module.
    • Expired Authorizations: If you use Authorize Only mode, note that authorizations for your customer’s transactions expire after seven days after which any attempt to capture the charge returns an error. Under Expired Authorizations, you can optionally attempt to recreate the original payment using one of your customer’s saved cards. If you enable this option, make sure to also enable the Save Customer Cards feature.
    • Automatic Invoicing: The Authorize Only option creates a new invoice with the Pending status on checkout. Once the charge is captured, the invoice status updates to Paid and the order status changes to Complete. This option is useful when Payment Action is set to Authorize Only mode: invoices won’t be automatically created on checkout as no charge was created. Once enabled, an invoice will be generated on checkout so you can email it to a customer before charging them; the order status will also update to Processing.
    • Hold Elevated Risk Orders: If Stripe Radar marks a payment with the Elevated Risk status, the order is placed On Hold until it is reviewed. See the section Enabling fraud prevention features with Stripe Radar for additional details.
    • Save Customer Cards: Enable this option to save customer cards so that customers only need to enter their card details once.
    • Pay with in-store currency: If you’re running a multi-currency or multi-language website, you can charge your customers in either the configured base currency or in a foreign currency shown on the checkout page. This is enabled by default, but you may prefer a different base currency for a given store view to support multi-currency localization. For example, your Magento site may support USD, but you may also want to present a specific store view for CAD.
    • Enable Stripe email receipts: This option enables or disables sending customer email addresses to Stripe, which is required to use Stripe’s email receipts to send custom emails to your customers (without setting up a mail server for your Magento installation).
    • Payment From Applicable Countries: If you only want to provide the card payment option to certain countries, you can change the Payment Applicable From to Specific Countries.
    • Payment For Specific Countries: Select the countries for which this payment method should appear at the checkout.
    • Sort Order: If you have enabled multiple payment methods, this setting determines the order of payment methods presented on the checkout page.

    Apple Pay, Google Pay, and Microsoft Pay support

    When the Apple Pay option is enabled and your customer is using a device that supports Apple Pay, Google Pay, or Microsoft Pay, a Payment Request Button will appear:

    Apple Pay using the Stripe module on an iPhone

    You can also test Apple and Google Pay support on the demo Magento server. Before using this feature on your own website, you must first meet some minimum requirements.

    Minimum requirements checklist

    1. Verify your domain with Apple Pay in the Dashboard.
    2. You must serve your page over HTTPS using TLS. Make sure that your HTTPS page does not load any images, CSS or JavaScript from an insecure URL using HTTP. You can check this by verifying that you see a padlock on your browser’s address bar.
    3. Make sure that Stripe.js is enabled in the module’s configuration section. You can verify it is working correctly by placing a test order.
    4. Make sure that Apple Pay is also enabled in the module’s configuration section. You can test Apple Pay on Stripe’s website by visiting that page with your iOS device or Safari on a compatible Apple device.
    5. Make sure that you have at least one card in your Wallet (in iOS, you can add one by going to Settings > Wallet & Apple Pay).
    6. You can test Google Pay using Chrome Desktop or Chrome Mobile with a logged-in Google account. You can also test whether or not your Android device supports Google Pay by visiting the Payment Request Button documentation.

    Configuration options for Apple Pay

    Use the dedicated Apple Pay configuration section in the Magento Admin Panel for all other options:

    Configuration options for Apple Pay

    • Cart Express Checkout: Enable or disable the payment button on the cart page.
    • Product Express Checkout: Enable or disable the payment button on product pages.
    • Save Customer Cards: Enable whether or not the module should save a customer’s cards with Stripe. When the customer visits the checkout page with this option enabled, they can reuse their saved cards to check out quickly.
    • Button Type: Choose between three types of payment buttons to display (Default, Buy, and Donate).
    • Button Theme: Choose between three types of button themes (Dark, Light, and Light-Outline).
    • Button Height: Adjust the button height to match your theme’s Add to Cart and Proceed to Checkout buttons.

    Configure payment methods

    You can enable support for payment methods like Bancontact, EPS, Giropay, iDEAL, Multibanco, Przelewy24, Alipay, SEPA Direct Debit, SOFORT, and WeChat Pay.

    • Enabled: Enable or disable the payment method at checkout.
    • Title: This is the name of the payment method as shown on the checkout page.
    • Optional Statement Descriptor: This is an optional short description for the source of the payment, shown in the customer’s bank statements. If left empty, the default descriptor configured from your Stripe Dashboard is used. This option isn’t available for Multibanco, SEPA Direct Debit, and SOFORT.
    • Payment From Applicable Countries: Determines whether this payment method will be available to the customer at checkout based on the country they set in their billing address. You can select All Allowed Countries if you want to show the payment method for all countries. An error message will be displayed at the final checkout step if the customer’s country isn’t supported.
    • Payment For Specific Countries: Each payment method is only available in specific countries. The supported countries for each payment method are preselected by default.
    • Currencies Applicable For: Determines whether or not the payment method will be available to the customer at checkout based on the currency used to place the order. The supported currencies for this payment method are preselected by default.
    • Sort Order: If you have enabled multiple payment methods, this setting determines the order of payment methods presented on the checkout page.

    Next steps

    Learn more about using the module:

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page