Stripe Payments - Magento 2 - Documentation

About

Stripe Payments 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/
    tar -xvf cryozonic_stripepayments-1.5.2.tgz
  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:6.1.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.

  7. Proceed to Stripe Webhooks Configuration in your Stripe dashboard.

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.
  9. Proceed to Stripe Webhooks Configuration in your Stripe dashboard.

Uninstall

If you purchased from our website

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

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

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 Configuration Section

  1. Enabled - Change to “Yes” to enable the module
  2. Title - Change this to whatever you would like to display to the customer at the checkout page.
  3. 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.
  4. 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”
  5. Security Method: This configuration option sets the method by which card details are transmitted from the customer's browser to the payment network. There are 3 possible options here:
    • None: The card details are sent directly to your website, where the Stripe API is used to tokenize them and charge the customer. Although the card details are not saved on your website, this is considered an insecure method of handling cardholder details. The reason this is supported is because it is the most compatible method with heavily customized checkout pages. If you decide to use this method in production, we recommend that you select a hosting provider that is also PCI compliant (i.e. that had a vulnerability scan by an «Approved Scanning Vendor»). Otherwise, you can use this method during development until your website is stable and you are ready to switch to the javascript-based Stripe.js or Stripe Elements methods.
    • Stripe.js v2: The card details are sent from the customer's browser directly to Stripe's secure servers where they are tokenized for security. Using this method will both provide increased security and also enable you to use Apple Pay and Stripe Radar. If you use this method, PCI guidelines require that you validate your PCI compliance annually using SAQ A-EP, instead of the simpler SAQ A.
    • Stripe.js v3 + Stripe Elements: This is a new security method from Stripe which is different in that the form fields of the card details are hosted directly on Stripe's servers using an embedded iframe on your website. Merchants that use this method are eligible for the simplest PCI validation method: Self-Assessment Questionnaire A (SAQ A). Using this method will both provide increased security and also enable you to use Apple Pay, Stripe Radar and 3D Secure. For CSS styling of Stripe Elements, please refer to the section How to style the payment form.
  6. 3D Secure: Please see here for details on how to correctly enable 3D Secure.
  7. Apple/Android Pay: Enabling this feature will display an Apple Pay or Android Pay button at the checkout. See this section for details on additional steps necessary to enable this feature.
  8. 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.
  9. Expired Authorizations: If you decide to «Authorize Only» your customer's transactions, have in mind that Stripe will expire authorizations after 7 days. Under «Expired Authorizations», you can decide what to do in the admin area after authorizations have expired. Capturing the amount will work fine within 7 days but Stripe will give you an error after that. With the Stripe Payments module, you can configure it to try and re-create the original payment using one of your customer's saved cards. If you enable this feature, make sure to also enable the saved cards feature.
  10. Automatic Invoicing: If you have "Payment Action" configured to be "Authorize Only", then an invoice is not normally created because a charge is not created at the checkout. However, if you need to force generate an invoice at the checkout, either because you need to email it to the customer before the charge is created, or because you need the order status to be Processing instead of Pending, then you can enable this option. Once enabled, an invoice will be created in "Pending" status instead of the normal "Paid" status. Then, after you capture the payment, the invoice will switch to "Paid" status and the order status will change to "Complete".
  11. Stripe Radar: Enabling Stripe Radar will place orders under manual review if they are marked as Elevated risk by Stripe. Please see the section Enabling fraud prevention features (Stripe Radar) for additional details.
  12. Save Customer Cards: Enable if you want Amazon-style saved cards on your website, so that customers do not enter their details more than once. This feature does not store cards or card tokens on your server and is fully PCI compliant. For more details, please see the «Saved Cards» section in this document.
  13. 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.
  14. New Order Status - This is the order status that will automatically be assigned to each new order.
  15. Enable Stripe email receipts: This setting will force the module to always send the customer email to Stripe, even for guest customers, which is a requirement if you have Stripe Email Receipts enabled in your Stripe account. Enabling email receipts will allow you to send customized payment emails to your customers through Stripe. Deliverability of these emails is higher than many Magento setups, and can be used without setting up a mailing system on your Magento server.
  16. 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”
  17. Payment From Specific Countries Select the countries for which this payment method should appear at the checkout.
  18. 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.

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 

Stripe Webhooks Configuration

Webhooks allow the modules to verify 3D Secure payments, create recurring orders with Stripe Subscriptions, issue invoices for SEPA Direct Debit and other asynchronous payment methods like Bitcoin and SOFORT. They will also change the order status from Pending to Processing when a charge has succeeded, or to Cancelled when a charge has failed. This is especially important with redirect-based payment methods where a customer may close the browser tab and never return to your website after they authorize a payment.

Webhooks can be configured in your Stripe Webhooks section which will handle all events for Stripe Payments and the following add-ons:

  • Stripe Subscriptions
  • Stripe Euro Payments
  • Stripe China Payments
  • Stripe Bitcoin

The webhook URL should be https://www.yourdomain.com/cryozonic-stripe/webhooks and it should be configured to send all events to your website. Once added, this should look like so:

If you have any webhooks that were configured in the past as part of an older add-on, you should remove those webhooks from your Stripe dashboard and only have a single endpoint to https://www.yourdomain.com/cryozonic-stripe/webhooks

If you have multiple domain names or multiple store views under the same Magento installation, you will only need to configure a single webhook endpoint. So for example if the following endpoints are available:

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

then you can pick any of the two endpoints and configure just that one. The module is smart enough to notify all modules and add-ons across your Magento installation about the received webhook event.

How to test Stripe Webhooks offline (in development)

If you are working on a development environment that cannot externally accept webhook requests, you can still test with the following manual method:

  1. In your Stripe dashboard, configure the test webhook URL to your live endpoint. If you still don't have a live server, you can use a http://requestb.in/ endpoint.
  2. Place an order with any of the module's payment methods.
  3. From your Stripe Events section, locate the source.chargeable event for the order you placed:

    Magento Stripe Source Chargeable

  4. From the event page, scroll to the bottom, expand the webhook request and copy the Request body under the successful webhook request:

    Magento Stripe Source Chargeable Event

  5. Using the Chrome Postman extension, create a POST request to http://yourdomain.dev/cryozonic-stripe/webhooks with a request body that is the same as the one you copied above.
  6. Trigger the request from Postman and check if the order status was updated to Processing under Sales > Orders.

Configure Apple Pay, Android Pay and Pay with Google

Magento 2 Apple Pay

When Apple/Android Pay is enabled, and your customer is using a device that supports Apple Pay, Android Pay, or Chrome's Payment Request API, then a payment button will appear as shown in the screenshot on the right →

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

Minimum Requirements Checklist

  1. 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.
  2. Authenticate your domain name using Stripe's instructions.
  3. Make sure that Stripe.js is enabled in the module's configuration section and verified by placing a test order.
  4. Check that Apple/Android Pay is also enabled in the module's configuration section.
  5. For Apple Pay, use Safari on an iPhone running iOS 10 and above (not an iPad; Safari doesn't support them yet).
  6. For Android Pay / Pay with Google, use Chrome Desktop or Chrome Mobile with a logged in Google account.
  7. 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).
  8. Test if your iOS device supports Apple Pay by visiting https://stripe.com/apple-pay.
  9. Test if your Android device supports Android Pay and Pay with Google by visiting the Payment Request Button documentation.
  10. If you are using a OneStepCheckout module, you may additionally need to configure the OSC module to refresh the payment form when a billing address has been entered by a guest customer. In most cases, this would be unnecessary.

Enabling fraud prevention features (Stripe Radar)

The module supports three fraud prevention features, the standard CVC check, Stripe Radar and 3D Secure. CVC is always enabled as a bare minimum security feature. Stripe Radar and 3D Secure can be enabled or disabled from the module's configuration section. Stripe Radar must be additionally activated from your Stripe fraud section.

The module will always send the customer's entire billing address (address, postcode, country, telephone etc) to Stripe during the card tokenization step. Stripe will forward the billing address to the customer's bank where it will be compared to the real card owner's registered address. If Stripe Radar detects a high risk payment based on the provided information, then the payment may be placed under review with an Elevated risk status. If you wish to automatically decline charges based on custom Stripe Radar rules, you can create a rule from your Stripe Radar dashboard. You can also create custom rules that can place payments under review even if they do not have an Elevated risk status. Any orders that are placed under review, will be marked as "Suspected Fraud" in Magento when Stripe Radar is enabled from the module's configuration section:

You may wish to investigate these further before proceeding to fulfill the order. You can do this by checking the address verification results in your Magento admin area, as shown in the following screenshot:

If you think that the order is not fraudulent, you can simply click on the Invoices tab on the sidebar and "Capture" the invoice. This will transition the order status to "Processing" or "Complete" and you can fulfil the order normally.

As soon as the invoice is captured, the payment will also be captured in your Stripe dashboard, and the order status in Magento will change from "Suspected Fraud" to either "Processing" or "Complete", depending on whether the order items need to be shipped or not.

To test this feature, switch the module to Test Mode from the configuration section, and then place an order using the card number 4000000000009235.

If you are using Stripe Radar and would like to add a custom message in sales emails for suspicious orders, you can edit the New Order email template from System > Transactional Emails. Open up the email template and add the following at the place where you would like the message to appear:

    {{if order.getPayment().getIsFraudDetected()}}
    <table cellspacing="0" cellpadding="0" class="message-container">
        <tr>
            <td>Your order needs to be reviewed before it can be fulfilled. Thank you for your patience.</td>
        </tr>
    </table>
    {{/if}}

Setting up 3D Secure

Stripe offers a card authentication feature called 3D Secure (also known as Verified by Visa, MasterCard SecureCode, J/Secure or American Express SafeKey) which can help merchants reduce fraud on their websites. Due to a liability shift to the authorizing bank, you will no longer receive any chargebacks if you have 3D Secure enabled and a fraudulent card is used on your website.

You can enable 3D Secure from the module's configuration section. The differences between the 3 settings are as follows:

  • Disabled - Cards which require that a 3DS verification is performed will be declined. A required 3DS verification is set from Stripe or from the customer bank based on many different factors that may increase the likelyhood of the customer using a stolen card.
  • Required - When 3DS is required, the customer will be redirected to the authorizing bank for verifying the card. In this case there will be no charge to the card until the customer successfully authorizes the payment.
  • Required or Optional - This will trigger a 3DS verification check for all supported cards, even if it is optional. This will incur an additional API call which may slow down your checkout page. Based on the result of this API call, the customer may or MAY NOT be redirected to their authorizing bank. If the API response is that the card can be charged without an authorization, then the module will just charge the card during the checkout without a redirect.

Important: 3D Secure is a redirect-based payment method. This means that there is always a risk for customers to not return to the merchant website after an authorization, because they just close their browser tab assuming that the order is placed. For this reason, it is important that you also configure Stripe Webhooks, so that your website is notified by Stripe when an authorization has been carried out successfully. If webhooks are not configured, your customer cards may never be charged after a successful authorization.

To test a 3D Secure payment, you can use the 3D Secure testing cards from https://stripe.com/docs/testing#3ds-cards on our demo server at magento2.cryozonic.com.

How to style the payment form

Please note that the payment form will look different depending on which security method you are using. Customizing Stripe.js v3 + Stripe Elements is more involved than other security methods, because the payment form is hosted on Stripe's servers.

A quick warning before we start - Styling any section in Magento is a theme designer's job, so if you have not done this in the past, we always recommend to delegate this to an experienced Magento theme designer. Any adjustments that you make to the payment form will need to be implemented in your theme, not directly into the module. This is so that when you upgrade the module, your changes are not lost.

There are 3 aspects of customizations to the payment form: HTML, CSS and JavaScript. If you are using the Stripe Elements security method, you will be concerned of all 3. If you are using a different security setting, you only need to be concerned about HTML and CSS.

Customize HTML Markup

You can find the payment form HTML markup under app/code/Cryozonic/StripePayments/view/frontend/web/template/payment/form.html. If you need to change this file, copy it under your theme directory, for example, under app/code/VendorName/ThemeName/view/frontend/web/template/Cryozonic_StripePayments/payment/form.html before making any changes to it. You may need to edit this file if for example, you want to split Stripe Elements fields into separate lines in the payment form. You can see how this is done in examples 2 and 3 of the Stripe Elements styling guides.

Then to make this file load instead of the default module form, find your theme's requirejs-config.js file, and add a mapping similar to the one below:

var config = { "map": { "*": { "Cryozonic_StripePayments/template/payment/form.html": "VendorName_ThemeName/template/Cryozonic_StripePayments/payment/form.html" } } };

For example, the default Magento Luma theme's requirejs-config.js file is located under vendor/magento/module-theme/view/frontend/requirejs-config.js. Your theme vendor will have a similar file in the theme, or you can alternatively use the same technique in a custom module on your website.

Please have in mind that every time you upgrade the module, you must check if anything has changed in the original payment/form.html and manually transfer the changes to your copied theme file. This is because the markup includes functionality that is important to things like saved cards, Apple Pay, initialization of Stripe.js etc.

Customize CSS Stylesheets

If you only need cosmetic customizations, this is by far the easiest and safest way to customize the payment form. You can apply CSS customizations anywhere you like in your theme, the only concern is to avoid adding your CSS changes inside the module files. When you upgrade the module, if you need to re-adjust the CSS, it will be immediately noticeable at the checkout page.

Customize Javascript

Javascript editing is only relevant if you are using Stripe.js v3 with Stripe Elements. The main use case is if you want to split Stripe Elements fields into separate lines in the payment form. You can see how this is done in examples 2 and 3 of the Stripe Elements styling guides. Another use case is if you want to pass CSS styling through the javascript code, however we recommend to avoid this whenever possible. It is safer to perform all CSS customizations through CSS additions in your theme, and only revert to this method as a last resort for something that is not possible.

To modify the javascript, find and copy the initStripeElements() method from app/code/Cryozonic/StripePayments/view/base/web/js/cryozonic_stripe.js.

Then, pick a javascript file in your theme that is loaded AFTER cryozonic_stripe.js, such as one that is loaded at the bottom of your page template. Most theme javascript files will be loaded after module javascript files. Once you have found the place to add the customization, you can overwrite the method with:

cryozonic.initStripeElements = ...paste the copied method here...

You can then make any adjustments you need to this method.

Please have in mind that just like HTML modifications, every time you upgrade the module, you must check if anything has changed in the original initStripeElements() method and manually transfer the changes to your javascript file..

Finishing up with customizations

After you have performed your customizations, you must additionally perform the following:

  • If you are running in production mode, delete var/* and pub/static/* and re-deploy your static assets with php bin/magento setup:static-content:deploy
  • If you are running in developer mode, flush your merged Javascript and merged CSS cache if Merged JS or Merged CSS are enabled
  • Flush any other caches that are implemented by 3rd party modules and caching systems
  • Flush your browser assets cache by either holding the "shift key" and pressing the refresh button, or by disabling the assets cache from your browser's web inspector. If your changes don't appear, you can also test in a different browser to check if it is a browser caching issue.

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

As of Stripe Payments v1.6.0, the subscriptions functionality has been split into a separate Stripe Subscriptions module, for which the documentation can be found here. If you are upgrading from an older version and you are looking for the subscriptions features, please contact us at info@cryozonic.com.

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.

Migration from Magento 1 to Magento 2

The Stripe Payments module is available for both Magento 1 and Magento 2. When it comes to migrating the codebase, you only need to be concerned about installing the Magento 2 version of the module on your website. The actual data migration can be performed with the Magento Data Migration Tool, a tool that is provided by Magento to migrate you store settings, customers and orders from Magento 1 to Magento 2. To migrate correctly:

  1. Follow the instructions in the Data Migration Guide, all the way to the database mapping step.
  2. Install the Stripe Payments module which will set up the needed database schema.
  3. In your map.xml.dist file, under the map > source > document_rules node, add:
                <rename>
                    <document>cryozonic_stripesubscriptions_customers</document>
                    <to>cryozonic_stripe_customers</to>
                </rename>
  4. Proceed to migrate your data using the Data Migration Tool.
  5. To finish things off, make sure that you also update your webhooks endpoint, which is different from the Magento 1 format (it has a dash instead of an underscore)

If you also have Stripe Subscriptions installed, please refer to https://store.cryozonic.com/documentation/magento-2-stripe-subscriptions#migrate for additional migration steps.

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

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. Following are the testing results for the benefit of other customers:

Compatible

  • 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.
  • Mageplaza OSC 2.1.1 - Tested against v1.1.3 on Magento 2.1.3.
  • Mageplaza OSC 2.3.0 - Tested against v1.4.1 on Magento 2.1.4.

Integration Step Necessary

  • aheadWorks OSC - The OSC module breaks the Stripe.js bindings of the "Place Order" button, which are necessary for security by tokenization. However several customers have reported having this issue resolved after contacting the aheadWorks support team, which helped to integrate the two modules.

Incompatible

  • Mageplaza OSC 1.1.2 - Tested against v1.1.0 on Magento 2.1.2. The payment method cannot be not loaded at the checkout page. We cannot verify the cause of this at the moment.
  • BSS Commerce OSC 1.0.8 - Tested against v1.5.3 on Magento 2.1.10. The Stripe API can be used to place regular orders, however when Stripe.js is enabled, the Knockout.js element bindings do not work correctly when the Place Order button is clicked.

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

Failed/Partial/Corrupted Installations

Some crashes at the checkout page or the admin area may be caused by a partial/corrupted installation. Corrupted installations may happen because of incorrect filesystem write permissions. To fix a corrupted installation:

  1. Carefully follow the Uninstall Instructions
  2. Clean the database with:
    DROP TABLE cryozonic_stripe_customers;
    DELETE FROM setup_module WHERE module = 'Cryozonic_StripePayments';
  3. Check your filesystem permissions before the re-install. Most of these problems can simply be fixed by changing the ownership of the Magento directories to the user running the webserver with:
    $ chown –R <www-username> /magento_directory
    Alternatively you can configure your webserver to run as the same user that deploys these files to your website.
  4. Carefully follow the Installation Instructions

Customer Support

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