Stripe Payments - Magento 1 - Documentation

  1. About
  2. Installation
    1. Recommended Method
    2. Manual Installation
    3. Uninstalling
    4. Upgrading
  3. Configuration
  4. Testing Cards
  5. Stripe Webhooks Configuration
  6. How to test Stripe Webhooks offline (in development)
  7. Configure Apple Pay, Android Pay and Pay with Google
  8. Saved Cards
  9. Issuing Refunds
  10. Capturing «Authorized Only» payments
  11. Capturing telephone orders from the admin area
  12. Enabling fraud prevention features (Stripe Radar)
  13. Setting up 3D Secure
  14. How to style the payment form
  15. Translations for multi-language websites
  16. Troubleshooting
    1. Enable Error Logging
    2. Front-End Crash (Website does not load)
    3. Missing required param: number.
    4. Unable to use Stripe.js
    5. Verify that Stripe.js is enabled
    6. Continue to Next Step button does not work (stuck spinner)
    7. Continue to Next Step button redirects to the shopping cart
    8. Tracking down conflicts with other modules
    9. Broken Admin Area
    10. Stripe no longer supports API requests made with TLS 1.0.
    11. Failed/Partial/Corrupted Installations
    12. The CSS/styling of the payment form is broken
  17. Thanks

About

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

Installation

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 your customer account section or through the email that was sent to you when you purchased the module.
  2. Log into your website's magento admin section.
  3. Make sure that compilation is disabled from System > Tools > Compilation.
  4. Go to System > Magento Connect > Magento Connect Manager and log in.
  5. If you have been evaluating any other Stripe modules not developed by Cryozonic, please uninstall them now to avoid obscure conflicts between the modules.
  6. Under «Direct package file upload», upload the .tgz file that you downloaded from our website.
  7. Click the «Install» button when the module has uploaded successfully.
  8. Check the black console to make sure that there were no errors.
  9. If you had compilation enabled, recompile from System > Tools > Compilation.
  10. Under System > Cache Management, flush all of your caches, including Merged CSS/JS if those are enabled
  11. Proceed to Stripe Webhooks Configuration in your Stripe dashboard.

Manual Installation

If for any reason the above procedure did not work (usually because the web server has no write permissions in your Magento directory), then you can install the module manually by simply extracting the module in your Magento's root directory.

  1. Double click the .tgz file to uncompress it. If you are on a version of Windows that does not support this, we recommend using the 7-Zip file archiver to uncompress the module.
  2. Upload the extracted files by FTP to your website, inside your website's root Magento directory. If you do not have an FTP client already, you can use FileZilla.
  3. A single page refresh of your website will set up the module and its database dependencies.
  4. Flush your site's caches, merged CSS and Javascript, and re-run compilation if necessary.
  5. Proceed to Stripe Webhooks Configuration in your Stripe dashboard.

Uninstalling

If you have installed the module from Magento Connect Manager, it should be just as simple to uninstall through the same interface as shown in the following screenshot:

Magento Stripe Payments Uninstall

If you have installed the module manually, you will need to manually delete each file and directory listed in the Failed/Partial/Corrupted Installations section.

Upgrading

Important: If you have Stripe Subscriptions installed as well, always upgrade both modules to their latest version.

You can always download the latest version of the module from your account. Once you have the latest version:

  1. If you have installed the module through Magento Connect Manager: Simply uninstall and re-install the module using the same instructions as above.
  2. If you have installed the module manually: Since v2.3.0 of the module, template files have moved to different directories. To uninstall the module, it is necessary to remove old module files manually before installing the newer version. If you simply overwrite them, you may run across template fallback issues. You should delete all of the old files from disk, but do not drop any database tables as part of the upgrade. Once the files are removed, we always recommend the magento connect manager installation method, otherwise you can re-install using the manual method.

Configuration

  1. Go to System > Configuration > Payment Methods
  2. Expand the section «Stripe Payment Gateway» as shown in the following screenshot:
    Magento Stripe Payments Configuration
  3. Enabled: Change to «Yes»
  4. 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. 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.
  6. 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.
  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. 3D Secure: Please see Setting up 3D Secure for details on how to correctly enable 3D Secure.
  9. 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.
  10. 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. More on invoicing later in this document.
  11. 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.
  12. 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".
  13. 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.
  14. Email Copy of Invoice: At the checkout when an order is placed, Magento will send an order email by default. If you need to additionally send an invoice email, then enable this setting. Please note that invoices are created only when the Payment Action is set to Authorize and Capture. If it is set to Authorize Only, then invoices must be manually created from the admin area. This setting will be ignored in the admin area because admins can email invoices when they create them manually.
  15. 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.
  16. New Order Status: This is the order status that will automatically be assigned to each new order.
  17. 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.
  18. Show Accepted Card Icons: This setting will display and auto-detect the accepted card types at the checkout page. If you set this to «Show all accepted card types», then you will see a row of accepted card icons during checkout:

    Magento Stripe Payments Accepted Card Icons

    As the customer types their card number, the correct card type icon will be highlighted.

    If you set this to «Show only the detected card type», then the detected card type icon will appear in the Card Number input box:

    Magento Stripe Payments Card Type Auto-detect

  19. Enable Stripe email receipts: When this option is enabled, the customer email will be sent to Stripe API along with every purchase made on your website. The email can be used together with pre-configured Stripe Email Receipts which can be sent to your customer by Stripe's servers instead of your own. This can be useful if your web server is not configured to send emails, or with subscription purchases that are billed monthly and you'd like to notify your customers about the payment. Please note that if you enable Stripe Email Receipts but you forget to enable this option, Stripe may fall back to the customer email for customers that have registered on your website, but it will not work for guest customers as they do not have an email on Stripe's servers.
  20. Accepted Card Types: Enables or disables specific card type icons for the checkout page. You may want to configure this based on the country of your Stripe account.
  21. 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»
  22. Payment From Specific Countries Select the countries for which this payment method should appear at the checkout.
  23. 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 Cards

You can use the following card details to try out the module while configured to be 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.

As of Stripe Payments v2.8.0 onwards, you can configure a single endpoint in your Stripe Webhooks section which replaces all previous webhooks that were required with older versions of 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 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.

Saved Cards

No customer cards are ever saved on your servers. This feature works by creating a customer object on Stripe's servers and saves the cards used on your store on that customer object. The following is a screenshot of the checkout page after saved cards have been enabled and the customer has previously used at least one card.

Magento Stripe Payments Saved Cards

Saved cards will also work with IWD OnePage checkout and other one page checkout modules with no problems.

Magento Stripe Payments Saved Cards with IWD OneStepCheckout

Customers can also add or remove cards by logging into their account and navigating to the «My Saved Cards» section.

Magento Stripe Payments Saved Cards Customer Account Section

Please note that if you enable Saved Cards, it may add 1-2 seconds of lag on the checkout page for fetching saved card details from Stripe, which is the reason that this is disabled by default.

The module will always save the customer card if:

  1. The "Save cards without asking" option is selected. From v2.2.2 onwards, this works for guest customers too.
  2. You have Stripe Subscriptions installed and a subscription is purchased on the front-end. The card will be used for recurring billing events.

If you have Stripe.js enabled, adding cards from the customer account section is also PCI compliant. Stripe.js is used on the checkout page, admin area and the customer account section.

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

    Magento Stripe Payments Live 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 $184.98 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

  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 Stripe Payments Capturing Authorized Payments

  4. If you need to issue a partial invoice, adjust the invoice items as shown on the screenshot.

    Magento Stripe Payments Partial Invoicing

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

You should now see the funds transferred to your account from Stripe's 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.

Capturing telephone 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. When you are ready to submit the order, fill in the card details as shown in the screenshot:

    Magento Stripe Payments Admin Orders

  5. Don't forget to select a shipping method as well.
  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 Capturing «Authorized Only» payments for instructions on how to create this invoice.

Placing orders from the admin area will also validate the customer's billing address against the card owner's address.

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 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 demo.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/design/frontend/base/default/template/cryozonic/stripe/form/standard.phtml. If you need to change this file, copy it under your theme directory, for example, under app/design/frontend/packageName/designName/template/cryozonic/stripe/form/standard.phtml 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.

Please have in mind that every time you upgrade the module, you must check if anything has changed in standard.phtml 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 skin/frontend/base/default/cryozonic_stripe/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:

  • Flush your merged Javascript cache if Merged JS is enabled
  • Flush your merged CSS cache if Merged CSS is 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.

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/locale/en_US/Cryozonic_Stripe.csv

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

/app/locale/languagecode_COUNTRYCODE/Cryozonic_Stripe.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.

Troubleshooting

Enable Error Logging

The module will log any problems during checkout in Magento's System Log file. To take advantage of this feature, you will need to enable logging from System > Configuration > Developer > Log Settings.

You can easily filter the log file to only the relevant messages using the following command (if you have shell access):

$ grep Stripe var/log/system.log

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

Enabling error logging will also write under var/log/exception.log and under var/report/. Make sure that these directories are writable by your Magento installation. To check the last 100 lines of the exception.log file, you can run the following command:

$ tail -100 var/log/exception.log

If you are testing on a development website, you can also set Magento to display exceptions at the front-end by running the following command:

$ cp errors/local.xml.sample errors/local.xml

Front-End Crash (Website does not load)

If for any reason the installation has caused the entire Magento site to crash, causing your website to not load, the first thing you need to do is to check for a maintenance.flag file in your Magento root directory. This file gets created if a critical error has occurred with Magento. Just delete this file to restore website functionality.

Missing required param: number.

Please see the Stripe.js section below.

Unable to use Stripe.js

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

Unable to use Stripe.js

Make sure to flush your configuration cache after disabling Stripe.js and before performing another test.

Disabling Stripe.js will increase compatibility with One Step Checkout modules or heavily customized themes and checkout pages. However to ensure increased security and PCI compliance, we do not recommend disabling Stripe.js. We instead warn the website developer about the issue by displaying the error that links to this page. In older versions of Stripe Payments, a fallback mechanism existed for convenience that would use the server-side Stripe API if Stripe.js could not be used, however in newer versions of the module, this is now enabled by default and the fallback mechanism was removed. The only reason for keeping Stripe.js disabled would be until a developer fixes the issue.

There are usually two common causes for this error:

  1. Javascript crashes: 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.
  2. One Step Checkout modules:

    Compatible

    The module has been tested with and integrated for with the following OSC modules:

    • IWD OnePage Checkout 4.0.4, 4.0.8, 4.3.4
    • Idev OneStepCheckout 4.1.4, 4.5.4, 4.5.5
    • AheadWorks OneStepCheckout 1.3.5
    • FireCheckout 3.2.0, 3.7.1, 4.0.2
    • MageGiant OneStepCheckout 4.0.0
    • AwesomeCheckout 1.5.0 (you must additionally whitelist the module's JS and CSS from AwesomeCheckout's configuration section)
    • MageStore OneStepCheckout 3.5.0
    • MageBay OSC 1.1.5
    • Amasty OneStepCheckout 3.0.5
    • NextBits OneStepCheckout 1.0.3
    • Magecheckout OSC 2.2.1
    • AdvancedCheckout OSC v2.5.0
    • Magesolution Athlete Ultimate Magento Theme v1.1.2
    • MageWorx OneStepCheckoutPro v3.4.4
    • GoMage LightCheckout v5.8, v5.9
    • MageCloud Clarion OSC v1.0.2
    • PlumRocket OneStepCheckout 1.3.4
    • Apptha 1StepCheckout v1.9

    The above modules (and newer versions of them) will work with no modifications. You can check the changelog on the bottom of the product page to see if support for one of the above modules was only recently added.

    Integration Step Necessary

    If you are using a OSC module from the following list, an integration step will be necessary:

    Incompatible

    The following modules are known to be incompatible with Stripe Payments:

    • IWD Checkout Suite 6.0.2

    Other OSC modules tested by our clients work correctly with no modifications.

If you would like to attempt an integration yourself with a new OSC module, please refer to the initOSCModules() method in skin/frontend/base/default/cryozonic_stripe/js/cryozonic_stripe.js for examples on how to perform an integration.

For any other issues, please get in touch with customer support at info@cryozonic.com.

Verify that Stripe.js is enabled

With Stripe Payments v2.3.2 and newer, Stripe.js is enabled by default in the module's configuration section. For older versions, make sure that it is enabled from the configuration section. Once enabled, if you try to place a test order and Stripe.js is not working, then an error will be thrown directing you to this documentation. A successful order means that Stripe.js is working correctly.

If Stripe.js is not working on your site, please see this section for possible troubleshooting solutions.

To additionally verify that Stripe.js was used from your Stripe dashboard, you can look into https://dashboard.stripe.com/logs/overview for requests to /v1/tokens. In the request body of that request, you should be able to see Stripe.js in the following form:

{
    ...,
    "payment_user_agent": "stripe.js/c437b32",
    ...,
}

Continue to Next Step button does not work (stuck spinner)

Possible reason 1: A front-end javascript crash

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

Possible reason 2: A server side crash

A server side error is a request which returns with code 500. To check if it is a 500 error, you can use 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:

Magento Stripe Subscriptions Troubleshooting

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:

Magento Stripe Subscriptions Troubleshooting

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.

If you can't find the error from the browser console, you can additionally check in your web server's error log files and in Magento's error log files under var/log/.

Once you find the cause of the error, if you think that it is a crash with the Stripe module, send us the full error report to info@cryozonic.com to receive further help. Otherwise if the error is thrown by another 3rd party module, you may be able to solve it faster by contacting the support team of that module.

Continue to Next Step button redirects to the shopping cart

This is the same as above – a 500 server side error, please see the above section for instructions. The main difference for finding the error cause will be that you will need to check the «Preserve log» checkbox in the debugging console so that the error message does not disappear after the redirect.

Tracking down conflicts with other modules

Occationally merchants come across unusual errors that cannot be easily traced back to a specific cause. A common reason is when a 3rd party module is modifying Magento in a way that breaks functionality in our Stripe modules. Some examples would be for a 3rd party module to:

  • overwrite the same models as our Stripe modules
  • be changing the behaviour of how a checkout page submits information to Magento
  • splitting orders into two
  • caching asset files in a way that prevents the correct initialization of javascript dependencies
  • etc...

If you suspect that another module may be getting in the way, we recommend disabling all suspected 3rd party modules using a specific method - by renaming their xml file under app/etc/modules/Vendor_ModuleName.xml into app/etc/modules/Vendor_ModuleName.xml.bak. This is the only effective way of disabling a module that overwrites Magento models, i.e. if the same module was simply disabled from the admin area, it would have no effect on resolving the issue.

To trace the cause of the issue effectively, we recommend to disable as many suspected modules as possible, sometimes going as far back to a barebones Magento setup with no enabled modules other than the Stripe module. If this approach fixes the issue, you can re-enable the modules one by one until you find the one causing the problem. Once the cause has been traced back into a conflict with a specific module, feel free to contact us with more details about the issue so that we can advice on the best approach to resolve it.

Broken Admin Area

If your Magento admin has broken (i.e. receiving a white screen of death) immediately after the installation, you may have forgotten to disable compilation mode before the installation. If you've got shell access, try running the following command to disable compilation:

$ php shell/compiler.php disable

If that doesn't work, try commenting out the two define function calls in:

includes/config.php

The above should fix the issue if it is compilation-related.

If the CSS/JS of your Magento admin have broken, it may be a merged CSS/caching issue. Have a look here on how to disable merged CSS manually. You can then flush all the caches.

Finally, this can happen because of insufficient write permissions on the var/cache directories. If that's the issue, make sure that your Magento directory is owned by the same user that is running the web server before installing the module or configure your webserver to run as the same user that deploys these files to your website.

$ chown –R <www-username> /magento_directory

Stripe no longer supports API requests made with TLS 1.0. Please initiate HTTPS connections with TLS 1.2 or later.

Stripe requires TLS 1.2 as a minimum requirement for encrypting the connection between your website and Stripe. Many merchants and their hosting providers usually mistake this error message with the normal HTTPS protocol for incoming connections from the web. However, this error actually refers to outgoing connections from your website to the Stripe API. Outgoing connections will use the hosting provider's installed version of OpenSSL and the PHP curl extension that is used to initiate the outgoing connection. To check if the installed OpenSSL and curl version supports TLS 1.2, you can use this script. If this code fails, please upgrade OpenSSL and your curl version to the latest and try again. If you are unable to do that, you will need to contact your hosting provider to upgrade or reconfigure your server's installed OpenSSL and curl.

For more details, please see

Failed/Partial/Corrupted Installations

If you have received errors in the black installation console, or you get crashes during the checkout page only, you may have a partial/corrupted installation because of incorrect filesystem write permissions. For corrupted installations you will need to manually uninstall the module by deleting the following files:

app/code/community/Cryozonic/Stripe/
app/design/adminhtml/base/default/template/cryozonic/
app/design/adminhtml/base/default/layout/cryozonic_stripe.xml
app/design/frontend/base/default/template/cryozonic/
app/design/frontend/base/default/layout/cryozonic_stripe.xml
app/design/frontend/base/default/layout/customer/savedcards.xml
app/etc/modules/Cryozonic_Stripe.xml
app/locale/en_US/Cryozonic_Stripe.csv
skin/adminhtml/base/default/cryozonic_stripe/
skin/frontend/base/default/cryozonic_stripe/
lib/Cryozonic

You will also need to clean the database:

  1. Drop the mysql table cryozonic_stripesubscriptions_customers
  2. Open the mysql table core_resource, find and remove the entry for cryozonic_stripe_setup and cryozonic_stripesubscriptions_setup

A corrupted installation may be caused by incorrect Magento directory permissions. 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.

If you do not have shell access to run the above command, the only other solution would be to perform a manual installation and upload the files to your Magento directory over FTP.

The CSS/styling of the payment form is broken

The styling of the payment form depends on which security method you use.

Magento Stripe Payments Form Styling Magento Stripe Payments Form Styling

There are currently 3 security methods with the module:

  • None (The Stripe API is used from the PHP library)
  • Stripe.js v2
  • Stripe.js v3 with Stripe Elements

If you are using the Stripe API or the Stripe.js v2 security method, then the payment form template can be found inside the Stripe Payments module. To change it, you can copy app/design/frontend/base/default/template/cryozonic/stripe/form/standard.phtml inside your theme directory and modify it there.

However, if you are using Stripe.js v3 with Stripe Elements, the form is hosted directly on Stripe's servers inside an iframe for security purposes. Stripe provides some examples on how to style this payment form. You can see from the examples that the payment form can be styled with either CSS or with JS. For CSS, you can add the styles anywhere in your theme. For JS styling, you can add the styling in the initStripeElements() method of skin/frontend/base/default/cryozonic_stripe/js/cryozonic_stripe.js

If you are using a OneStepCheckout module, or a theme that changes the checkout page, it may also be worth checking the templates of the OSC module, as some OSC modules will make the payment form very narrow, squashing together the form fields.

Another common configuration options with OSC modules is to change the checkout page layout from say, 3 columns, into 2 columns, which may make the form wider to fit the Stripe Elements fields.

Thanks

Thank you for choosing our Stripe modules. If you like the modules, we would much appreciate a review on magento connect.