Stripe

The Stripe payment gateway for WooCommerce lets you accept payments directly onsite, and includes the option to accept Payment Requests (Apple Pay and Google Pay), SEPA, and more international payment methods.

Download it now at WordPress.org. See Changelog.

Installation ↑ Back to top

  1. Go to Plugins > Add New on your WordPress site.
  2. Enter WooCommerce Stripe in the Search Plugins bar. Author is Automattic/WooCommerce.
  3. Click Install Now and Activate.

To learn more, see Installing and Managing Plugins.

Setup and Configuration ↑ Back to top

  1. Go to: WooCommerce > Settings > Payments > Stripe.
    Note: ‘Payments’ formerly called ‘Checkout’ prior to WooCommerce 3.4
  2. Tick the Enable Stripe checkbox. Untick to disable.
  3. Enter a Title (required) and Description (optional) seen by the customer during checkout.
  4. Tick the Enable Test Mode checkbox, if you wish to test before going live. Untick to begin accepting payments with Stripe.woocommerce-stripe
  5. Enter your Live Secret Key and Live Publishable Key (obtained from your Stripe account). The Test Secret Key and Test Publishable Key are different and should only be used when Enable Test Mode selected in step 4.
  6. Enter Statement Descriptor, a description that appears on a customer’s bank or credit card statement. This cannot be blank and may be up to 22 characters. The statement description must contain at least one letter, may not include these characters > < " '. In addition, only alpha-numeric characters may be used.
  7. Tick the checkbox to Capture Charge Immediately (Authorize and Capture at the same time) or untick to only Authorize. If you untick the box, you’ll need to capture funds manually for each order within 7 days otherwise the authorization will be canceled alongside the order. See our FAQ for more.
  8. Enable 3D Secure (optional) means to force customers to go through 3D Secure payment process if the payment method supports it.
  9. Enable Stripe Checkout if you prefer a popup to request details and using a checkout image. Please see next section Stripe Checkout to understand how it appears for customers and how this works.
  10. Enable Payment Request Buttons (optional) if you wish to give customers the ability to pay via Apple Pay or Google Pay. For example, this will prompt Apple Pay if using Safari or Chrome Pay if they’re using Chrome browser. The customer will need to be using a supported browser as well as having credit cards saved to their account.
  11. Payment Request Button Type will change the type of the button to show.
    1. Default – “Pay” (default Apple or Google button)
    2. Buy – “Buy Now” (Apple or Google variant)
    3. Donate – “Donate” (Apple or Google variant)
  12. Payment Request Button Theme will change the appearance of the button to show.
  13. Payment Request Button Height will change the height of the button to match your styling preferences.
  14. Saved Cards, if you want to give Stripe customers the ability to use a card saved on their account for future purchases.
  15. Log Debug Messages, if you wish to save logs that can help you/us troubleshoot your site. Can be disabled and enabled as needed.
  16. Save Changes.

Webhooks ↑ Back to top

Webhooks are a way for Stripe to communicate with your site. It provides information such as the status of the transactions to your WooCommerce site and can even up update the order based on that information. We highly recommend for you to set this up on your Stripe dashboard and it is as simple as copying and pasting a simple link. If you go to your WooCommerce Stripe settings page under Stripe Gateway, you will see a generated webhook link.

stripe-webhook-link
Then go to your Stripe Dashboard Webhook Setting and click on “Add Endpoint”. Paste the link into the URL field and click on “Add Endpoint”. You want to choose “Send all event types”.
stripe webhook setting

The same single user account credentials cannot be used to make purchases in both Live Mode and Test Mode.

Stripe Checkout ↑ Back to top

If you tick the box for Enable Stripe Checkout, more options will appear:

  • Stripe Checkout Image: Enter the URL of a 128×128 px image/logo to be displayed at checkout. Use an image already uploaded to your site or upload one now at Media > Add New.
  • Stripe Checkout Description: Shows a description of your store on Stripe Modal Checkout.

Enabling Stripe Checkout provides a popup instead of the standard payment form (the default setting). A pop-up is used to collect credit card details from the user.

Since version 4.1, the Stripe Checkout (modal popup) flow has changed. It now requires one additional step before the modal popup is shown. This is so that checkout form validation can be done prior to Stripe Checkout engaging.
If enabled, this option shows a “Continue to Payment” button and modal credit card form on a new Pay for Order order-pay page, instead of credit card fields directly on the page. We recommend you leave this disabled and use the embedded form as that is the preferred method. Please note that customers who choose a saved payment method won’t see this page.

For more information about Stripe Checkout, please Stripe’s own information page.

Here is a gif showing the new purchase flow for Stripe Checkout introduced in Stripe 4.1:

Payment Request Buttons ↑ Back to top

In version 4.0.0 of the Stripe payment gateway extension for WooCommerce, all Payment Request buttons are activated (on your site) at once. Apple Pay and Google Pay are the most well known, Google Pay is the name for all payment methods which fall under the Google umbrella, including Android Pay, Chrome payments, and Pay with Google. Most official documentation may still refer to “Google Pay” or “Android Pay” but for customers on your site, these are all the same.

To see what a payment request button will look and behave like, please see the Stripe.com Payment Request button documentation page.

Apple Pay ↑ Back to top

Before you start using Apple Pay, you must accept the Terms of Service in your Stripe dashboard at this link https://dashboard.stripe.com/account/apple_pay

After this, you will then need to add the domain of your site, remove any www or https://.

Please note: for the WooCommerce Stripe extension you do not need to upload the verification file to your site – the extension does this for you in the background. After you’ve added the domain, you can check that the file exists by navigating to example.com/.well-known/apple-developer-merchantid-domain-association – replacing example.com with the domain you entered. The domain will then show on your Apple Pay Stripe page under “On the Web domains”.

 

Customers will need to have a payment method from a supported bank or payment card provider, please see the Apple Pay support page for more details, along with a compatible Apple device.

Google Pay ↑ Back to top

Make sure that the Payment Request Buttons option is enabled, there is no other setup for you to accept payments via this method.

Note: the Google Pay button on mobile devices will only show when there is a saved payment card, and with all the permissions (Location is optional) allowed for Google Play services.

Customers will need to have a payment method from a supported bank or payment card provider, please see the Google Pay help page for more details.

Additional Payment Methods ↑ Back to top

Aside from standard credit and debit cards, Stripe comes with additional payment methods that can be used to target different markets. Here is a list of the ones this extension supports.

  • Alipay
  • Bancontact
  • Giropay
  • iDEAL
  • SEPA Direct Debit
  • SOFORT
  • Przelewy24
  • Multibanco
  • EPS
  • WeChat Pay – coming soon!

For detailed information about these payment methods, please visit Stripe Payment Methods, alternatively Stripe.com has a Payments overview page with a lot of useful information. Most of these additional payment methods will need to be enabled under your Payment Settings on your Stripe.com Dashboard. Some may require additional information to work.

Once enabled in Stripe, they can then be enabled under WooCommerce > Settings > Payments (note: ‘Payments’ was formerly called ‘Checkout’ prior to WooCommerce 3.4) by clicking the slider icon or by clicking on the payment service name and enabling there. You can also change the title and description for each service.

Customer Usage ↑ Back to top

Standard Checkout ↑ Back to top

Customers pay on the checkout page, with version 4 of the extension, the form now uses Stripe Elements which provided enhanced security, styles, and a better customer experience above the standard WooCommerce fields.

Using a new card, they see the option to enter credit card details, and tick the Save to account box if enabled (this screenshot shows the “Inline Credit Card Form” version):

For your regular customers who may have a saved card, they are presented with the stored cards (if that option has been enabled) or they can store a new one (screenshot showing the standard non-Inline form):

When Payment Request Button is enabled, customers see the corresponding button on the product page and on the cart page when using a supported device, browser, and payment method:

Payment Request Buttons ↑ Back to top

Safari on iPhone:

Safari on a desktop:

 

 

Chrome on a desktop:

Saved Payment Methods ↑ Back to top

On the ‘My Account’ page, customers can add, view, and remove cards from their account within the Payment Methods submenu:

Hooks (Actions/Filters) ↑ Back to top

This section will describe all the hooks available to you in an event you need to manipulate how Stripe functions. This is more advanced so if you’re not familiar with how hooks work in general within WordPress space, please have a read here Hooks

Hook name (parameters)

Action Hooks

  • wc_gateway_stripe_process_response ($stripe_response, $order) – The response we get back after calling a charge request to Stripe.
  • woocommerce_credit_card_form_start ($gateway_id) – Before showing the credit card form.
  • woocommerce_credit_card_form_end ($gateway_id) – After showing the credit card form.
  • wc_stripe_checkout_receipt_page_before_form – Before showing the Stripe Checkout (Popup modal) form.
  • wc_stripe_checkout_receipt_page_after_form – After showing the Stripe Checkout (Popup modal) form.
  • wc_stripe_checkout_receipt_page_before_form_submit – Before showing the Stripe Checkout (Popup modal) form submit.
  • wc_stripe_checkout_receipt_page_after_form_submit – After showing the Stripe Checkout (Popup modal) form submit.
  • wc_stripe_checkout_return_handler ($order) – Stripe Checkout (Popup modal) after submitting the payment in the popup.
  • wc_gateway_stripe_process_payment ($stripe_response, $order) – The response we get back after calling a charge request to Stripe but before processing the actual response.
  • wc_gateway_stripe_process_payment_error ($error, $order) – Called when an error occurs during the process payment event.
  • woocommerce_stripe_add_customer ($args, $response) – Called after creating a Stripe customer.
  • woocommerce_stripe_add_source ($stripe_customer_id, $wc_token, $response, $source_id) – Called after creating/attaching a source to a customer.
  • wc_stripe_delete_source ($stripe_customer_id, $response) – Called after deleting a source from customer.
  • wc_stripe_set_default_source ($stripe_customer_id, $response) – Called after setting a default source to a customer.
  • wc_gateway_stripe_process_redirect_payment ($response, $order) – Called after a redirect payment process.
  • wc_gateway_stripe_process_redirect_payment_error ($error, $order) – Called after a failed redirect payment process.
  • woocommerce_stripe_process_manual_capture ($order, $result) – Called after a manual capture of a charge within admin order.
  • woocommerce_stripe_process_manual_cancel ($order) – Called after a cancel of the order that is authorized and not yet captured.
  • wc_gateway_stripe_process_webhook_payment ($response, $order) – Called after a webhook payment process.
  • wc_gateway_stripe_process_webhook_payment_error ($order, $notification, *$e) – Called after a webhook payment process error.

Filter Hooks

  • wc_stripe_save_to_account_text ($text) – Text that shows to customers next to the save payment information checkbox.
  • wc_stripe_payment_icons ($icons_array) – Icons that show next to each payment method.
  • wc_stripe_send_stripe_receipt *boolean* – Whether to send a receipt via Stripe.
  • wc_stripe_payment_metadata ($metadata, $order, $prepared_source) – Metadata that gets passed during a payment request.
  • wc_stripe_generate_payment_request ($post_data, $order, $prepared_source) – Post data that gets passed during a payment request.
  • wc_stripe_owner_details ($details, $order) – The owner details of an order.
  • wc_stripe_require_3ds ($require_3ds, $source_object, $three_d_secure) – Override if 3DS should be required.
  • wc_stripe_3ds_source ($post_data, $order) – Post data when creating 3DS source.
  • wc_stripe_force_save_source ($force_save_source, $customer) – Override force save customer.
  • wc_stripe_use_default_customer_source ($use_default) – Whether to use default customer source if source not found.
  • wc_stripe_refund_request ($request, $order) – Request parameters when refund is requested.
  • wc_stripe_PAYMENT_METHOD_settings ($settings)Admin settings for payment method.
  • wc_stripe_checkout_verify_zip *boolean* – Whether to verify zip when using Stripe Checkout (Popup modal).
  • wc_stripe_checkout_require_billing_address *boolean* – Whether to require billing address when using Stripe Checkout (Popup modal).
  • wc_stripe_checkout_require_shipping_address *boolean* – Whether to require shipping address when using Stripe Checkout (Popup modal).
  • wc_stripe_checkout_locale ($locale) – Sets the locale for the Stripe Checkout (Popup modal).
  • wc_stripe_allow_remember_me *boolean* – Whether to show the remember me option for Stripe Checkout (Popup modal).
  • wc_stripe_description ($description, $payment_method_id) – Override the description of credit card payments.
  • wc_stripe_display_save_payment_method_checkbox *boolean* – Whether to show the save payment method checkbox.
  • wc_stripe_sepa_mandate_notification ($method) – The method to use to inform customer of the SEPA mandate.
  • wc_stripe_allow_prepaid_card *boolean* – Whether to allow prepaid credit card to be used.
  • wc_stripe_elements_options – Additional options to manipulate Stripe elements.
  • wc_stripe_elements_styling – Additional options to manipulate the Stripe elements styling.
  • wc_stripe_elements_classes – Additional options to add classes to the Stripe elements.
  • wc_stripe_params ($params) – Localized JS key/value pair.
  • wc_stripe_payment_request_params ($params) – Localized JS key/value pair.
  • wc_stripe_checkout_label – Label that shows up on the Stripe Checkout (Popup modal).
  • wc_stripe_hide_display_order_fee ($bool, $order_id) – Whether to hide the display order fee in orders view.
  • wc_stripe_hide_display_order_payout ($bool, $order_id) – Whether to hide the display order payout in orders view.
  • woocommerce_stripe_request_headers ($headers_args) – Headers parameters for cURL requests.
  • wc_stripe_idempotency_key ($key_string, $request) – The string for the idempotency key on request.
  • woocommerce_stripe_request_body ($request, $api) – The request body to pass when doing a request
  • wc_stripe_customer_metadata ($metadata, $user) – The meta data used when creating a customer.
  • wc_stripe_create_customer_args ($args) – The arguments used when creating a customer.
  • wc_stripe_localized_messages ($localized_messages) – The messages used from Stripe responses.
  • wc_stripe_logging ($bool, $message) – Whether to log a specific message when logging is enabled.
  • wc_stripe_webhook_review_change_order_status ($bool, $order, $notification) – Whether to change the order status when order review event happens.
  • wc_stripe_PAYMENT_METHOD_supported_currencies ($currencies) – The supported currencies for that specific payment method.
  • wc_stripe_payment_request_total_label_suffix ($suffix) – Label suffix to use when Payment Request is engaged.
  • wc_stripe_payment_request_total_label ($label) – The total label to use when Payment Request is engaged.
  • wc_stripe_payment_request_supported_types ($types) – The product types Payment Request supports.
  • wc_stripe_hide_payment_request_on_product_page *boolean* – Whether to hide Payment Request button on product detail page.
  • wc_stripe_show_payment_request_on_checkout *boolean* – Whether to show Payment Request button on checkout page.
  • wc_stripe_payment_request_hide_itemization *boolean* – Whether to show itemizations when using Payment Request.

Removing the Extension ↑ Back to top

If you decide this extension is not for you then you can delete it of course. When you go to deactivate then delete the extension, we have in place logic to remove all Stripe settings from the options table however we have put in place a safeguard just in case you didn’t really mean to delete it. So if you would like to “really” delete everything from this extension, you just need to add this code to your wp-config.php file. define( WC_REMOVE_ALL_DATA, true );. This code needs to be in place before you click on delete. Once you have deleted the extension and all settings removed, you can remove that code.

Frequently Asked Questions ↑ Back to top

The Stripe payment method is not showing. ↑ Back to top

In live mode, an SSL certificate must be installed on your site to use Stripe. In addition to SSL encryption, Stripe provides an extra JavaScript method to secure card data. If this is correct, and you have recently updated to Stripe 4.0.0, please uncheck the “Payment Request Buttons” box, save Stripe settings, then check the box again, and save again.

The Payment Request Button is not showing. ↑ Back to top

The customer must have a compatible device and payment method in a supported region, otherwise, the option is unavailable.
Please see the support pages for full details:

What type of Products can be purchased with the Payment Request Button? ↑ Back to top

Currently, Simple and Variable products are supported. The buttons won’t show for other Product types (such as Bookings) and won’t work with custom product fields.

Can I test Apple Pay? ↑ Back to top

Yes, please follow the link here for instructions Apple Pay Testing.

Can I test Google Pay? ↑ Back to top

Yes, save a Stripe test card to your device, and view a product page.

Can I hide the Payment Request button on the single Product page? ↑ Back to top

You can remove the Payment Request button from the Product page with this filter: add_filter( 'wc_stripe_hide_payment_request_on_product_page', '__return_true' );

Can I hide the Payment Request button on the Cart page? ↑ Back to top

Yes, you would need to remove the actions:

remove_action( 'woocommerce_proceed_to_checkout', array( WC_Stripe_Payment_Request::instance(), 'display_payment_request_button_html' ), 1 );
remove_action( 'woocommerce_proceed_to_checkout', array( WC_Stripe_Payment_Request::instance(), 'display_payment_request_button_separator_html' ), 2 );

Can I show the Payment Request button on the Checkout page? ↑ Back to top

Yes, although the Payment Button has been removed for clarity on the Checkout Page, a filter has been added to allow you to show this again: add_filter( 'wc_stripe_show_payment_request_on_checkout', '__return_true' );

Can a single customer have multiple subscriptions? ↑ Back to top

Using the WooCommerce Stripe extension and WooCommerce Subscriptions, you can have multiple subscriptions in your WooCommerce store. It should be noted that WC Subscriptions and the WC Stripe extension don’t use Stripe’s Recurring Plan feature, but instead manage subscriptions in WooCommerce and use token billing for each recurring payment.

How can I change the style of the Stripe Form? ↑ Back to top

With 4.0, we moved to an iframe method of including the payment form on your site. This provides extra security and is required for how we implement Stripe now. If you target the iframe with CSS you will find it doesn’t work. What you need to do instead is target the wrapping div element. Here’s some sample CSS that can help you:

Note: You can style the size, margin, padding, and background color of the boxes.

You can also add custom Stripe Elements styles using the wc_stripe_elements_styling filter. Here’s an example of how you can do that:

What version of the Stripe API does this extension use? ↑ Back to top

We try to use the latest possible. We’ll update it whenever we can. Note that you can usually update the API version on your Stripe dashboard without affecting our extension. For clarification, you can find which version we’re using in code on GitHub.

Does this extension support Bitcoin? ↑ Back to top

As of version 4.1.2 Bitcoin is no longer offered as a payment method. This is due to Stripe dropping support for processing Bitcoin payments as of 23rd April 2018.

Does this extension support Stripe Connect? ↑ Back to top

No, not currently; we’re unable to integrate at this time.

Does Stripe use AVS – Address Verification System? ↑ Back to top

Yes! This is enabled in your Stripe account dashboard and will then work in WooCommerce. See Stripe’s documentation about Avoiding fraud and disputes.

Does Stripe Support Authorization and Capture? ↑ Back to top

Yes! This is an option in the extension settings. Charges can be captured from within the WooCommerce dashboard. Please note that un-captured authorizations will expire after 7 days.
When the Stripe payment gateway is set to authorize, orders made via Stripe will have the status on hold and the following note:
2016-08-01_10-03-30
Change the order status to processing or completed to capture the payment or cancel the order to remove the pre-authorization.

Does Stripe allow refunds inside WooCommerce? ↑ Back to top

Yes, please see more info on our WooCommerce Refunds documentation page.

Does Stripe Support ACH? ↑ Back to top

Not currently but Stripe are actively working on this. For more details, please follow this GitHub Issue.

Why aren’t my subscriptions displayed on the Stripe Dashboard? ↑ Back to top

WooCommerce Subscriptions does not use the Stripe Subscriptions feature. Instead, it uses a Stripe Customer and Card token and controls the processing of recurring payments.
This avoids any potential issues that could occur by trying to keep two copies of each subscription’s data in sync on two different systems (one in your store and one at Stripe). It also and makes it possible for Stripe to support all of WooCommerce Subscriptions’ features, like payment date changes, rather than only those the Stripe Subscriptions allows.
Because of this, you will not see subscriptions created with WooCommerce in your Stripe Dashboard as Subscriptions. This does not mean recurring payments will not be processed. As long as your store is running correctly, recurring payments will be processed correctly and will show up in the Stripe Dashboard as Payments.

Do I need to enable “Saved Card” to process subscriptions? ↑ Back to top

The WooCommerce Subscriptions extension has its own mechanism for saving credit card details. When a customer buys a subscription product, Stripe will create a special payment token that will use the same credit card details for future subscription payments. Saving the same card again on the customer’s account is not necessary unless you want to allow the customer to reuse the card for other purchases in your store.

How can I change the payment icons used such as Visa, Mastercard…etc? ↑ Back to top

You can change it via a built-in hook. Here is an example showing the use of the hook changing out the Visa logo.

add_filter( 'wc_stripe_payment_icons', 'change_my_icons' );
function change_my_icons( $icons ) {
        // var_dump( $icons ); to show all possible icons to change.
    $icons['visa'] = '<img src="https://mysite.com/wp-content/plugins/woocommerce/assets/images/icons/credit-cards/visa.svg" />';
    return $icons;
}

How can I change the width of the Payment Request button? ↑ Back to top

You can target the button div using #wc-stripe-payment-request-button and the “OR” separator using #wc-stripe-payment-request-button-separator

Troubleshooting ↑ Back to top

Root Relative URLs ↑ Back to top

There are known issues with the Root Relative URLs plugin. You will not be able to use this with Stripe.

I get an error when placing an order telling me to enable JavaScript. ↑ Back to top

This error may be caused by non-standard/poorly coded themes and JavaScript (JS) issues. Common issues include:

  1. Javascript errors on the checkout page – To view the error, open up your browser error console (in Chrome: View > developer > javascript console) and look for red errors. This should indicate where the error is located and lead you to the problem, i.e., loading jquery wrong
  2. Failing to load scripts – Stripe loads 2 JS files which it needs to function. If these are not loaded you will see errors. The most common reasons for not loading are:
    • A theme missing wp_head() or wp_footer() calls
    • Old overridden template files from WooCommerce inside your theme
    • Loading headers/footers in a non-standard way. WooCommerce uses get_header()’s get_header action to init the checkout and load scripts. If you are not using get_header() you either need to do so, or you need to trigger the get_header action manually using: do_action( ‘get_header ); in your custom header loader.

Apple Pay – I am getting this error “Error: Unable to copy domain association file to domain root” ↑ Back to top

That could mean your server configuration is not allowing files/paths to be written in that location. You would have to manually do this by following the step outlined here.

Apple Pay – I am getting this error “Error: Unable to verify domain – Bad Request” ↑ Back to top

Try manually doing this by following the step outlined here.

I’m getting an API error. ↑ Back to top

Ensure that you have entered the correct keys. If you are in live mode, you should have entered live keys (not test keys).

  • If you are using test mode, keys are prepended with sk_test and pk_test.
  • If you are using live mode, keys are prepended with sk_live and pk_live.

I’m seeing the error “Could not find payment information.” ↑ Back to top

This usually means that test mode is still enabled while using live keys, or that test keys are being used in live mode. For more details, please check the Stripe logs under WooCommerce > Status > Logs

Questions and Feedback ↑ Back to top

Have a question before you download? Please fill out this pre-sales form.

Already using Stripe and need some assistance? Get in touch with a Happiness Engineer via the Help Desk.

Have a suggestion regarding a feature you’d like to see included in this product? Add it to our Ideas Board.

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top