Stripe Payments & Subscriptions - Magento 2 - Documentation

About

Stripe Payments & Subscriptions is a module for Magento 2 which allows merchants to accept payments using the Stripe payment gateway. This is the documentation for installing, configuring and using this module on Magento 2.

For the most up to date documentation, you can always visit the online version of this documentation by clicking here.

Installation

If you purchased from our website

Warning: We recommend that you test the module on a testing server before installing it on your live web server. Please see the Troubleshooting section if you come across any installation issue.

  1. If you haven’t done so already, please download the module from the account section or through the email that was sent to you when you purchased the module.
  2. Extract the file into your Magento root directory. The module will be installed under app/code/Cryozonic/StripePayments/
  3. Enable the module by running the following commands:
    php bin/magento setup:upgrade
    php bin/magento cache:flush
  4. If you are running Magento in production mode, you will also need to deploy the module's static files using the following command:
    php bin/magento setup:static-content:deploy
  5. If you are upgrading from a previous version, you will also need to run:
    php bin/magento module:enable Cryozonic_StripePayments
  6. Important: If you are using compilation, which is also automatically enabled when you switch to production mode, then you will need to run the following commands before compilation starts:
    rm -rf app/code/Cryozonic/StripePayments/lib/stripe-php/
    composer require stripe/stripe-php:~4.4.0
    php bin/magento setup:di:compile

    Note: If you don't have composer installed, follow these installation instructions. During the installation, you may be asked for your Magento 2 authentication keys. You can get these by following the instructions here.

If you purchased from the Magento marketplace

Warning: We recommend that you test the module on a testing server before installing it on your live web server. Please see the Troubleshooting section if you come across any installation issue.

  1. As a minimum requirement, you will need cron running and fully functional for the installation. If you have not set up cron already, please follow the official instructions from Magento before proceeding.
  2. Ensure that your web server has full write access to the entire Magento directory. Official instructions can be found here. However the simplest way is to change the ownership of the Magento directory to the same user under which the web server is running. This can be done with:
    $ chown –R <www-username> /magento_directory
  3. Navigate to the Setup Wizard at http://yourdomain.com/admin/admin/backendapp/redirect/app/setup/
  4. To access your purchase from the marketplace, you will need to enter your Magento Marketplace authentication keys. If you haven't done so already, please follow these instructions.
  5. From the Setup Wizard page, click the Component Manager icon
  6. In the top section of the page, you will see a New Purchases section with an Install link underneath. Click the Install link and follow the instructions to install the module. The available versions are in the format 10x.x.x where x.x.x represents the actual version number of the module.
  7. The installation can take up to 5-6 minutes for cron to run its full cycle, upgrade Magento, re-deploy the static assets, recompile the code etc. Please be patient and leave the installation to finish without closing the window.
  8. If for any reason the installation takes unusually long, or it gets stuck at "Update pending", check for errors in var/log/update.log. Alternatively, you can run the cron commands manually from a shell without the pipes at the end so that errors are be displayed in the shell. If the command succeeds, the contents of the files under var/.update_* will also be updated. If any errors occur, simply contact us at info@cryozonic.com with details on what happened so that we can help you complete the installation.

Uninstall

If you purchased from our website

  1. From a terminal, run the following commands:
    php bin/magento module:disable --clear-static-content Cryozonic_StripePayments
    composer remove stripe/stripe-php
    rm -rf app/code/Cryozonic/StripePayments
  2. If you are uninstalling PERMANENTLY (i.e. not upgrading to a newer version), you should also:

    1. Remove the "Stripe Subscriptions" attribute group from:
      Stores > Attributes > Attribute Set > Default (or whatever attribute set you are using)
    2. Run the following database SQL statements:
      DELETE FROM eav_attribute WHERE attribute_code like "cryozonic_%";
      DELETE FROM eav_attribute_group WHERE attribute_group_code like "stripe-%";
      DROP TABLE cryozonic_stripe_customers;
      DELETE FROM setup_module WHERE module = 'Cryozonic_StripePayments';

If you purchased from the Magento marketplace

  1. Navigate to the Setup Wizard at http://yourdomain.com/admin/admin/backendapp/redirect/app/setup/
  2. Click the Component Manager icon
  3. On the right hand side column, you will see a dropdown with an Uninstall link. Click the Uninstall link and follow the instructions to uninstall the module.

    Magento 2 Uninstall Module

  4. If you are uninstalling PERMANENTLY (i.e. not upgrading to a newer version), you should also:

    1. Remove the "Stripe Subscriptions" attribute group from:
      Stores > Attributes > Attribute Set > Default (or whatever attribute set you are using)
    2. Run the following database SQL statements:
      DELETE FROM eav_attribute WHERE attribute_code like "cryozonic_%";
      DELETE FROM eav_attribute_group WHERE attribute_group_code like "stripe-%";
      DROP TABLE cryozonic_stripe_customers;
      DELETE FROM setup_module WHERE module = 'Cryozonic_StripePayments';

Upgrade

You can always download the latest version of the module from the account section or through the email that was sent to you when you purchased the module. Once you have the latest version, and

Configuration

Navigate to Stores > Configuration > Sales > Payment Methods. There you will find a configuration section for the Stripe module:

Magento 2 Stripe Payments and Subscriptions Configuration Section

Enabled - Change to “Yes” to enable the module

Title - Change this to whatever you would like to display to the customer at the checkout page.

Mode - If you would like to test a payment, leave the mode to “Test”. When you are ready to accept live transactions, you can change this to “Live”. Testing cards are provided in the next section.

Stripe.js - If this is disabled, the Stripe API is used to create charges, which means that cardholder data travels through your web server (but is not saved) and gets tokenized to create a one-off charge. If your checkout page is customized, keeping this disabled will increase compatibility with your customizations. The disadvantage is that if your business operates in a country that enforces PCI compliance regulations, then in order to be compliant you will need to select a hosting provider that is also PCI compliant (i.e. that had a vulnerability scan by an “Approved Scanning Vendor”). If this option is enabled, then cardholder data never travels through your webserver. It will instead go to Stripe’s secure servers directly from your customer’s browser, which means that you are fully PCI compliant. The downside of this option is that if your checkout page is customized in a way that does not follow Magento’s best coding practices, then you may come across compatibility issues (typically javascript errors). If Stripe.js has any issues with your customized checkout page, the Stripe API is used as a fallback. Finally, when this option is enabled, Stripe.js is used in both the front end as well as the admin area to ensure 100% PCI compliance.

Keys - You will also need to fill in your test and live keys that Stripe has provided to you when you created your account. You can get these by logging into Stripe, navigating to your account settings and clicking on “API Keys”

Payment Action - Select “Authorize and Capture” if you would like the customer cards to be charged immediately after a purchase. This is the default option and it does not require you to do anything else after the customer has placed the order. If you prefer to finalize the payment later, you can choose “Authorize Only” which will lock/authorize the order amount on the customer’s card so that you can capture the amount later by issuing an invoice. You can find out more on how to capture these payments by clicking here.

Pay in store currency - If you are running a multi-currency / multi-language website, then you can charge your customers either in the configured base currency or in the foreign currency that they see in the checkout. This is enabled by default, but if you have reason to prefer the base currency (i.e. some Canadian Stripe accounts have currency restrictions) then you can disable this.

New Order Status - This is the order status that will automatically be assigned to each new order.

Payment Applicable From - If you only want to provide this payment option to certain countries, you can optionally change the “Payment Applicable From” to “Specific Countries”

Sort Order - If you have multiple payment methods enabled, this setting will determine the order of the Stripe payment method at the checkout page. For example, if you also have PayPal enabled and would like Stripe to appear after PayPal, then set this number to something larger than what is configured in the PayPal configuration section.

Subscriptions Specific Configuration

If you will be selling subscriptions, make sure to also configure the Stripe Webhooks system as explained in this section.

Testing

You can use the following card details to try out the module while in test mode.

To Test

Use Card Details

Successful Payment

Name on card: Any

Card number: 4242424242424242

Expiry Date: Must be in the future

CVC: Any 3 digit number

Unsuccessful Payment

Same as a successful payment,

but with card number 4000000000000002

Wrong Expiry Date

Same as a successful payment,

but with expiry date in the past

Wrong CVC number

Same as a successful payment,

but with card number 4000000000000101

Expired Card

Same as a successful payment,

but with card number 4000000000000069

Wrong Billing Address with enabled

Address Verification System (AVS)

Same as a successful payment,

but with card number 4000000000000010

Processing Error

Same as a successful payment,

but with card number 4000000000000119

 

Warning: If you prefer testing in live mode, make sure to set the payment method to “Authorize Only”, otherwise currency conversion fees may be incurred.

You can also find an up to date list of all testing options at https://stripe.com/docs/testing 

Paying with Apple Pay

Magento 2 Apple Pay

When Apple Pay is enabled, and your customer is using a device that supports Apple Pay, then the Apple Pay button will appear as shown in the screenshot on the right →

Apple Pay can also be tested on our demo server. Before using Apple Pay on your own website, you must first meet the minimum requirements listed in the checklist below:

Apple Pay Requirements Checklist

  1. Stripe.js is enabled in the module's configuration section and verified by placing a test order.
  2. Apple Pay is also enabled in the module's configuration section.
  3. Use Safari on an iPhone running iOS 10 and above (not an iPad; Safari doesn't support them yet).
  4. Make sure that you have at least one card in your Wallet (you can add one by going to Settings → Wallet & Apple Pay).
  5. Test if your device supports Apple Pay by visiting https://stripe.com/apple-pay.
  6. You must serve your page over HTTPS using a valid TLS 1.2 certificate. This can be checked from your browser or from SSL Labs.
  7. Authenticate your domain name using Stripe's instructions.
  8. Additionally, if you are using a OneStepCheckout module:
    1. Configure the OSC module to refresh the payment form when a billing address has been entered by a guest customer.
    2. Place an order yourself as a guest customer and ensure that when you enter a billing address, the payment form is refreshed. If you have any card details in the form, these will disappear.

Admin Area

Issuing Refunds

  1. Go to Sales > Orders, then find and click the order you would like to refund.
  2. If the module is configured in Authorize Only mode, all you need to do is press the Cancel button at the top of the page. If on the other hand the module is in the Authorize and Capture mode, continue to step 3.
  3. From the left sidebar, click Invoices, then click on the invoice to refund.
    Magento 2 Stripe Refunds

  4. At the top right hand corner, click Credit Memo
  5. Adjust the amount if necessary and click Refund at the bottom of the page to perform a live refund. If you click Refund Offline, the refund will only be issued in Magento but not in Stripe (an offline refund).


  6. For a partial refund, you can adjust the "Adjustment Fee". The amount you enter here is the amount that will not be refunded. In the screenshot above, when the adjustment fee is $10, then $53.87 will be refunded and $10 will be kept as a fee. You can ignore the "Adjustment Refund" field because Stripe cannot refund an amount that is greater than the original payment of the customer.
  7. The amount should now be fully or partially refunded in Stripe and a note should appear in the Comments History of the order.

It is also perfectly fine to perform a refund directly from Stripe’s dashboard; however doing so will not update Magento’s dashboard figures on the total amount of sales, nor will it update the order status, so we recommend to perform refunds through Magento whenever possible.

Capturing «Authorized Only» payments

When the module performs an Authorization for an order, what that means is that we have requested from the customer's bank to lock the order amount in the customer's bank account so that it cannot be spent elsewhere. The actual transfer of funds does not happen, so the customer will not see the payment in their bank statement. However, their available balance will be reduced and they will not be able to spend that amount even if they have the funds in their bank account.

When the merchant ships the product, they can manually capture the payment through the admin area. This can be done with the following steps:

  1. Go to Sales > Orders.
  2. Find and click on the order for which you would like to capture a payment.
  3. Click on the “Invoice” button as shown in the screenshot:
    Magento 2 Stripe Capture Authorized Only Payments

  4. If you need to issue a partial invoice, adjust the invoice items as shown on the screenshot. The item quantity can only be reduced, not increased.
    Magento 2 Stripe Capture Authorized Only Payments

  5. Click on the Submit Invoice  to capture and finalize the payment.

You should now see the funds transferred to your account from your Stripe dashboard.

Warning: An authorized only payment will expire after 7 days, so make sure to capture your payments early to avoid creating new charges for the customer. Your customers will also be happier if you provide a speedy service.

Creating orders from the admin area

It is possible to create an order and charge a customer’s card with details that you have received over the telephone. This feature is also known as Mail Order/Telephone Order (MOTO). To create a MOTO order:

  1. Go to Sales > Orders.
  2. At the top right hand side, click the Create New Order button.
  3. Follow the steps and choose a customer, the store and the products for that order.
  4. Select a shipping method (if applicable) before filling the payment details.
  5. When you are ready to submit the order, fill in the card details as shown in the screenshot:

    Magento 2 Stripe order from admin area

  6. Click the Submit Order button.

If the module is configured for Authorize and Capture, then the customer’s card will have now been charged and the funds transferred to your account. However, if the module is configured for Authorize Only, you will need to also capture the payment by manually creating an invoice. Please refer to the section Issuing invoices and capturing “Authorized Only” payments for instructions on how to create this invoice.

The admin area uses Stripe.js if enabled and is fully PCI compliant.

Subscriptions

How to enable and configure

Subscriptions for any Magento product can be enabled very simply from the product configuration page. When creating or editing a product, scroll down until you see the «Stripe Subscriptions» section:

Here, you have the following options:

  • Subscription Enabled: Turn this on to convert this product into a subscription.
  • Billing Interval: Can be Days, Weeks, Months or Years. Whatever you choose here will be displayed to the customer in the front end, so if you prefer to display "30 Days" instead of "1 Month", set this to Days instead. If Days are specified, the subscription will also be created in Days in your Stripe account.
  • Billing Interval Count: How often the billing should occur, so if you specify 30 here, a billing event will occur every 30 Days or whatever unit you chose in the previous setting.
  • Trial Days: The amount of days before the first charge for the subscription.

You do not need to do anything else, like creating a subscription plan in your Stripe account. An appropriate subscription plan will automatically be created for this product when your customers checkout. For more details, see the next section.

How subscriptions are created in your Stripe account

When a customer places an order, a subscription plan is created in your Stripe account in a way that the product price, tax and ordered Qty are used in the subscription plan price. Here is an example of how subscription plans will be created in your Stripe account:

Notes on the above:

  1. The product name at the time of the purchase is used as the plan's name.
  2. If another customer purchases the exact same product, Qty and has similar price and tax, then no new plan will be created. That customer will be subscribed to the already existing plan for that product.
  3. You will notice that the newly created subscriptions to these plans will have a Trial status. This is because a payment has already been taken for the entire purchase during the checkout. This is done so that if the customer purchases a regular product together with a subscription, they will only see a single transaction in their bank statement for their order. If the subscription billed the customer separately, this may cause confusion to them as they wont be able to match the amount to the order from your website.

When you click on a subscription to view it, you will notice that a lot of Metadata are saved on the subscription as shown in the below screenshot:

These metadata are used for both informational and functional purposes, so don't delete any of them.

To change the shipping address of a subscription, you can edit the subscription's Shipping metadata shown above.

How can customers view, cancel and edit subscriptions

When customers navigate to their account, they can view their purchased subscriptions by clicking the «My Subscriptions» link on the sidebar:

Customers can view or cancel their subscriptions from here, as well as edit their shipping address. The displayed shipping address is not the same as the customer's address in Magento. The customer's Magento shipping address is used during the checkout and saved on the subscription's metadata as shown in the previous section. When a customer edits the shipping address from this section, only the metadata is updated on the actual subscription. The customer's Magento shipping address will remain the same.

How can admins edit subscriptions

You have seen from the previous section what customers can see in their account about their subscriptions. All of that information is pulled directly from the Stripe API, i.e. nothing is saved on your own server about the customer's subscription. What this means for admins is that whatever changes are made to a subscription from the Stripe dashboard, they will automatically be reflected into the customer's account section:

The following things can be edited from your Stripe dashboard:

  • Rename the subscription plan
  • Cancel customer subscriptions
  • Apply discount coupons
  • Add, change or remove trial periods
  • Edit the shipping address through the subscription's metadata

For switching customers from one subscription plan to another, please see this section.

How to create recurring subscription invoices using Stripe Webhooks

When you create a monthly subscription for a customer, then Stripe will issue an invoice every month which is automatically paid in your Stripe account. Stripe Payments & Subscriptions can receive notifications from Stripe that an invoice has been created, and it will automatically create the same invoice against the original order in your Magento admin area. Merchants can navigate to the Invoices section of that specific order to view all payments received for that specific order:

Merchants can also view all generated invoices for all orders by navigating to Sales > Invoices. Once the invoice has been generated, customers will be able to view and download their invoices when they log into their Magento customer account.

The method used for generating these invoices is an events notification system called Stripe Webhooks. When Stripe Webhooks are configured, Stripe will send a notification to your web server every time an invoice is generated and a payment is processed for the customer's subscription. To configure Stripe Webhooks, navigate to https://dashboard.stripe.com/account/webhooks and add the following endpoint URLs for your Test and Live modes:

http://yourdomain.com/cryozonic-stripe/webhooks

Once added, your Stripe account should look like the following:

The only event that you need to configure for the webhooks is the invoice.payment_succeeded event. Make sure to not add any other events apart from invoice.payment_succeeded.

DEVELOPERS TIP – If your website is not live yet and you would like to test Stripe Webhooks, you can simulate a Stripe Webhook request using the following steps:

  1. First place a subscription order on your website.
  2. Navigate to https://dashboard.stripe.com/account/webhooks and click on the "Send test webhook" button.
  3. Click "Send test webhook" in the popup. The request will be for the last placed subscription order on your website.
  4. If you expand the subsequent dropdown, you will be able to view the request body. You can copy that to reuse it with the Chrome Postman extension.
  5. Once you have Postman configured, you can browse https://dashboard.stripe.com/events to find older webhook events and use their request body to test those as well.
  6. Newly generated invoices from the webhook request will be generated under Sales > Orders > View Order > Invoices, or alternatively at Sales > Invoices.

Recurring billing notifications

If you would like your customers to receive email notifications when a recurring billing event occurs, you will need to do the following:

  1. From Stores > Configuration > Sales > Payment Methods > Stripe Payments - set the «Email Stripe email receipts» configuration option to Yes
  2. From your Stripe dashboard, enable email receipts from https://dashboard.stripe.com/account/emails
  3. Customize your email receipts from https://dashboard.stripe.com/account/public

Creating subscription orders from the admin area

In Magento 1, where recurring profiles are used to enable subscriptions, merchants cannot create subscription orders from the admin area. However, with our Magento 2 Stripe module, merchants can now add subscription products to any order they create from the admin area:

There absolutely no limitations compared to how Magento 1 works, so feel free to add subscription products to orders just like other regular products.

Switching customers from one subscription to another

The recommended method of switching a customer from one subscription to another is from the Magento admin area. Although you can also switch customers to different subscriptions from the Stripe dashboard, if you do so, you'll get the following side effects:

  • The metadata that are saved against a subscription will not be updated.
  • The customer wont be able to find the original order number that was used to create the subscription from their account's My Subscriptions tab.
  • If you have configured recurring invoicing using Stripe Webhooks, these will no longer be created and the Stripe Webhooks events will no longer work for those subscriptions.
  • Your customer will not receive an updated order email that breaks down the itemized billing.

Because of the above issues, a better way to switch a customer from one subscription to another is to create a new order from the admin area. At the payment method section, the following options will be presented to the merchant:

In the above screenshot, all of the customer's active subscriptions will be loaded from the Stripe API. You can select the one you want to cancel before creating the new subscription. In the dropdown, you will see the subscription name, the recurring billing amount, as well as the date at which the next payment will be attempted. This billing date is used to automatically pre-populate the following date field which will be used to set a trial for the subscription. The subscription trial will end on the date in this date field.

No payment details are necessary for switching subscriptions. The customer's default card (which will normally be the same as the one used for the existing subscription) will be used to create the new subscription. If for any reason the customer needs to use a new card, you can update that from https://dashboard.stripe.com/customers.

If you don't see the above subscription switching options in the admin, make sure to only have a single subscription product in this order.

Creating a configurable subscription

Two examples of configurable subscriptions can be found on the demo server. These two products have been created in Magento as Configurable Products which have both Customizable Options and Configurations under each of their product pages.

Customizable Options are used when you need to offer different prices of the same product, i.e. in the Coffee Beans example, this is the "Bag Size" customization which will increase the subscription price if a larger bag is selected.

Configurations are used when you need to offer subscriptions of different billing intervals to the customer, i.e. this is the Dropdown and Text Swatch controls that allow the customer to select between One-off, Monthly or Quarterly subscriptions.

You can review how these products have been configured at the admin area:

In the above example, each subscription is enabled and configured on each of the Simple Products (these are created automatically by Magento). The configurable products (which you create manually) is where the simple products are grouped together through Configurations.

To create a configurable product similar to the above:

  1. Create a new product from the Catalog (it can be of simple or virtual type)
  2. Scroll down and find the Configurations tab

  3. Create a new configuration. The following screen will appear:

  4. Create a new attribute called "subscription" and make sure it is "Global" under the "Advanced Attribute Properties" tab (example). You can also select here whether you would like this attribute to be a Dropdown or a Text Swatch (example).
  5. Make the attribute required
  6. Under "Manage Options", add the values that will appear in the dropdown or text swatch. For text swatches, there will be an additional column called "Swatch" which must be completed.

  7. Under the "Manage Labels" tab, add whatever you would like to show to the customer on the product page, i.e. "Subscribe and save 5%"
  8. If you are configuring the attribute as a Text Swatch, you can optionally enable "Used in product listing" under advanced attribute properties in order to make it appear in the catalog similarly to the demo server
  9. Save the attribute. It should now appear in the attributes list where you can select it and press the "Next" button
  10. Select all of the attribute values on the next page and complete the steps until you are back on the product page

  11. Magento will then create the simple products for you based on the attribute options. You can set the prices and product images at this step from the Configurations tab
  12. Navigate back to the products catalog and select each of the newly created subscription products
  13. Make sure that the Subscription attribute of each product has the correct value:

  14. Enable and configure each product's subscription from the Stripe Subscriptions tab

Tax & shipping for subscriptions

Newly created subscriptions will:

  • Include the Magento tax in the Stripe subscription plan price
  • Exclude the shipping cost of the order from the subscription plan price

The reason for this is that with the Magento 2 shipping methods, the shipping cost is calculated per order, not per cart item. Magento 2 does not provide a breakdown of shipping costs for each item row on an order. There is no way of calculating the shipping cost of a specific item in an order. The shipping cost calculation is performed inside the module of the shipping method that the customer selected during the checkout, and is performed for the entire order.

The merchant has a number of options to deal with this:

  1. Include a fixed shipping cost in the subscription price.
  2. Configure similar subscription products with different fixed shipping prices, which are made available only to specific countries / stores / shipping addresses.
  3. Offer all subscription products with "Free Shipping" so that customers have an incentive to buy a subscription instead of buying the product individually.
  4. Charge the shipping cost separately from your Stripe account when a subscription item is shipped.

When a subscription is created as a Virtual Product, then Magento will not ask for a shipping address from the customer. This means that shipping will be free for the subscription.

However when a subscription is created as a Simple Product, then a shipping address will be collected and if you have a shipping module configured, it may calculate a shipping cost for a subscription, which will only be charged at the initial checkout session but not in subsequent subscription cycles. If you would like to exclude this shipping cost from the initial order completely, you can create a promotion rule from:

Marketing > Promotions > Cart Price Rules > Add New Rule

Under the "Actions" tab, select Free Shipping for matching items only:

Under "Apply the rule only to cart items matching the following conditions", create a rule based on the Subscription Enabled attribute

Translations for multi-language websites

The module contains a translations file that can be used with multi-language Magento configurations. You can find this file under:

app/code/community/Cryozonic/StripePayments/i18n/en_US.csv

To create a translation file for a different language, you can copy the file under:

app/code/community/Cryozonic/StripePayments/i18n/languagecode_COUNTRYCODE.csv

Make sure to replace languagecode_COUNTRYCODE with the locale code of the target locale language. This would be the same language that you selected under System > Configuration > General > General > Locale Options > Locale. If you must set your Locale configuration for the first time, make sure to also flush your Configuration Cache after doing so.

Once you have copied the file, you can simply edit the file and replace the second string on each row with the translation of the first string. There is nothing else you need to do for translations.

For full configuration instructions, please see our online documentation at http://store.cryozonic.com/documentation/magento-2-stripe-payments-subscriptions

Troubleshooting

Switching to Developer Mode

First and foremost, before debugging any kind of Magento 2 issue, you must make sure that you have switched to the developer Magento mode. It is very hard to debug Magento 2 errors when running in production mode. Please review these steps on how to switch to developer mode. In addition to the official documentation, some people may set the Magento mode using the $MAGE_MODE environment variable from the web server's configuration files, i.e. inside Nginx's site configuration files or in Apache's .htaccess files. Make sure that if you have this configuration, it does not interfere with the mode that was set from the command line.

Error Logging and 500 Server-Side Errors

Magento will log any Errors and Exceptions thrown during application runtime in the var/log directory. The module will also throw Exceptions in a similar manner which will be also be logged there. You can find these errors in the following two files:

var/log/system.log
var/log/exception.log

If you have SSH access, you can quickly filter the error messages using the following command:

grep -i Stripe var/log/system.log

To monitor errors live as they happen, clear the console (Ctrl-L on Linux, Cmd-K on OSX) and run the following command:

tail -f var/log/system.log

This will show errors live. You can refresh the problematic page in your browser and if there are any errors, you will see them appear in the console.

If you do not have shell access, just download the file, open it with your favourite text editor and search for “Stripe”.

Upgrades / Caching Issues

If you have upgraded the module but for some reason you don't see the new changes, you can manually clear the Magento 2 cache by deleting the contents of the following directories:

var/cache/*
var/page_cache/*
var/di/*
var/generation/*
var/view_preprocessed/*
var/composer_home/cache/*
pub/static/*

Once the above have been cleared, run the following commands:

php bin/magento setup:upgrade
php bin/magento cache:flush
php bin/magento setup:static-content:deploy

If you are running in production mode, you may also have to recompile:

php bin/magento setup:di:compile

If you are running Varnish, you must also restart Varnish after deleting the var/cache/* files.

Finally, sometimes browsers also cache Magento 2 requests, if you still have caching issues, try with a different browser.

Payment method not showing in admin area

If you have recently upgraded to Magento 2.1.3, you may have noticed that the module's configuration section no longer displays in the Magento admin area. This is because of a backwards incompatible change in Magento that affects all 3rd party payment modules and is documented here.

If you are affected by this issue, the solution is to edit line 12 of app/code/Cryozonic/StripePayments/etc/adminhtml/system.xml so that the sortOrder attribute is increased from 1 to 10 like so:

<group id="cryozonic_stripe" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">

Unable to use Stripe.js

This error indicates that Stripe.js is not working correctly on the page that displayed this error. You can test if this is the case by disabling Stripe.js from the module's configuration section:

Make sure to flush your configuration cache after disabling Stripe.js and before performing another test. Disabling Stripe.js will make your website insecure and non-PCI compliant, so we recommend to re-enable it as soon as the error is resolved.

The most common reason for this error is; if you are still developing the website, you are likely to have unstable modules with javascript crashes in the browser's debugging console. When a javascript crash occurs, all subsequent javascript execution is halted by the browser, resulting in Stripe.js not being initialized correctly at your checkout page. If you can see any javascript crashes in your browser console, fixing them should be the first thing to try in order for the checkout page to initialize correctly.

If your browser's javascript console is clean from errors, but you are still receiving this error, please get in touch with us at info@cryozonic.com

Compatibility with One Step Checkout modules

After requests from customers, we have tested several OSC modules with Stripe Payments & Subscriptions. Following are the testing results for the benefit of other customers:

  • IWD OSC 1.0.2 - Tested against v1.0.1 of our module on Magento 2.1.1. No changes were necessary for compatibility with our module. We did find however an incompatibility between IWD OSC and newer versions of Magento 2.1.x, which can be fixed with this patch.
  • Magestore OSC 2.0.0 - Tested against v1.1.0 on Magento 2.1.2. Works out of the box, no changes were necessary to either module.
  • Mageplaza OSC 1.1.2 - Tested against v1.1.0 on Magento 2.1.2. Incompatible!. The payment method cannot be not loaded at the checkout page. We cannot verify the cause of this at the moment.
  • Mageplaza OSC 2.1.1 - Tested against v1.1.3 on Magento 2.1.3. Works out of the box, no changes were necessary to either module.
  • Mageplaza OSC 2.3.0 - Tested against v1.4.1 on Magento 2.1.4. Works out of the box, no changes were necessary to either module.

Other OSC modules tested by our clients work correctly with no modifications. However, if you are using a OSC module that is causing problems and is not listed in the above list, please contact us at info@cryozonic.com.

An error occurred on the server. Please try to place the order again.

This error is related to a long standing open issue with Magento 2, which can be found here. There are many possible reasons for this error, and each merchant may have a completely different reason for why this happened. We have observed that our customers typically receive this because of crashes in 3rd party modules that try to do something during the checkout process, for example, marketplace modules trying to adjust the sales emails, OneStepCheckout modules crashing because of a template issue, modules trying to wrap Plugin methods around the payment module functions and so on. The reason that this appears as a generic error is because Magento 2 does not handle exceptions thrown by these modules very well. This will be fixed in newer versions of Magento 2, however if you are getting this, you will need to do a bit of manual digging to find the error.

To identify the cause of the problem, you will first need to make sure that you have Magento running in developer mode. Then, try to place an order. Before clicking the Place Order button, open your browser's web inspector (the below example is using Chrome) and navigate to the Network tab so that you can see the requests. You will see a server side error in red as shown below:

Open the network request and click on the Response tab. There, you will find the full error that caused the issue:

If there is no error backtrace here, the only other place to look is under var/log/exception.log. You should be able to get a full backtrace of the error in one of these two locations.

Once you have the full error backtrace, you can usually inspect it carefully to find which module it is coming from. You can disable any suspected module and try again to see if the error is fixed.

If however the error comes from the core Magento code, please contact our customer support so that we can offer advice.

Stuck loading spinner at checkout page

This may happen because of one of two reasons.

Possible reason 1: A server side crash

Server side crashes are logged in the Magento log files under var/log (see the above section on how to enable error logging). If you enabled error logging and still cannot see the error, please bear in mind that it may sometimes be logged in your web server's log files. If you are using a php-fpm variant, make sure to also check the log files of your fastcgi backend.

If the error is not logged in any of the above places, try using your browser's debugging console – for example in Chrome you can right-click and select Inspect.

If it is a 500 error, then under the Network tab of the console you will see a red network request as shown in the screenshot below:

To find out what is causing the error, click on the line. You will see the error under the Response tab of the network request as shown below:

The error will give some clues as to where the crash is coming from. Usually it is some incompatibility with another module that tries to interfere with the checkout process, like triggering of custom emails, reward point modules etc. You can try to disable any such suspected modules by moving their xml file from app/etc/modules/ into a different directory. Do not try to disable conflicting modules from the admin area – it doesn't always work.

Possible reason 2: A front-end javascript crash

Magento 2 and our Stripe module both use javascript to render the checkout view. If a javascript error occurs when you navigate to the checkout page, all subsequent javascript code execution stops, so the page may get stuck with a loading spinner or it may render the checkout page incorrectly. To check if a javascript crash may be causing this, you can use your browser's debugging console to check for errors, for example:

Magento 2 Stripe Payments and Subscriptions Javascript Errors

Errors such as the above, even if they are not caused by the module itself, they may prevent the customer from navigating or using the checkout page successfully. To make sure everything works as expected, make sure that the debugging console is always free of javascript errors.

Composer Authentication Required (repo.magento.com)

If you are installing composer for the first time, you may get this message in your console before installing the Stripe PHP library. The keys that you need to use are your Magento 2 marketplace keys. Please follow the instructions on this page to get your authentication keys.

PHP7 Invalid Stripe Secret Key

Magento versions 2.0.0 - 2.0.6 have a known issue with PHP7 where obscured/password fields are not decrypted correctly. You can either upgrade to Magento 2.0.7 or if not possible, please see this commit on how to apply a patch in your existing Magento installation.

Cannot create invoice for authorized order

If you have upgraded from Magento 2.0 to Magento 2.1 instead of installing 2.1 from scratch, you may face an issue where the invoice cannot be created for an authorized order - see core issue 5546 for more details. We will be waiting for an official Magento fix for this issue. For the time being, our recommendation is to install Magento 2.1 from scratch. If you are already running in production and need to migrate your data, you can use the solution described here, however this may cause system upgrade issues and must be taken into consideration when upgrading to Magento 2.1.1.

Customer Support

If you have any other issues installing, configuring or using the module, please contact us at info@cryozonic.com