Stripe Payments & Subscriptions

Transcription

1 Stripe Payments & Subscriptions Installation and Configuration Guide Table of Contents Stripe Payments... 2 Installation... 2 Configuration... 3 Testing Cards... 6 Saved Cards... 7 Issuing Refunds... 9 Capturing Authorized Only payments Capturing telephone orders from the back office Enabling the Address Verification System (AVS) Translations for multi-language websites Stripe Subscriptions Installation Configuration How subscriptions work Creating a subscription plan Setting up recurring orders with Stripe Webhooks Creating a configurable subscription Reviewing and updating customer subscriptions How pausing and resuming subscriptions works Adding or updating subscription plans Coupons Creating subscription orders from the back office (Mail/Telephone Orders or MOTO) Translations for multi-language websites Troubleshooting Customer Support Module Upgrades Thanks

2 Stripe Payments 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 our website at or through the 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, 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. 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.tgz file in your Magento s root directory or uploading the files by FTP. A single page refresh of your website will set up the module and its database dependencies. 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: If you have installed the module manually, please refer to the Troubleshooting section for manual uninstall instructions. 2

3 Upgrading You can always download the latest version of the module from Once you have the latest version, simply uninstall and re-install the module using the same instructions as above. Important: If you have Stripe Subscriptions installed as well, always upgrade both modules to their latest version. Configuration 1. Go to System > Configuration > Payment Methods 2. Expand the section Stripe Payment Gateway as shown in the following screenshot 3

4 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. Stripe.js This configuration option sets the method by which cardholder data is used to create a charge. If this is disabled, the Stripe API is used to create charges, which means that cardholder data travels through your server (but is not saved) and gets tokenized to create a one-off charge. This method is compatible with the majority of one page checkout modules, as well as heavily customized desktop themes and mobile themes. The disadvantage is that if your business operates in a country that enforces PCI compliance regulations, then in order to be compliant you will need to select a hosting provider that is also PCI compliant (i.e. that had a vulnerability scan by an Approved Scanning Vendor ). Do have in mind that if you are not PCI compliant, authorities do not fine your business but your bank may receive the fine instead. It is up to your bank to pass any fees down to their customers. If this option is enabled, then cardholder data never travels through your webserver. It will instead go to Stripe s servers from your customer s machine, which means that you are fully PCI compliant. The downside of this option is that if your checkout page is customized in a way that does not follow Magento s best coding practices, then you may come across compatibility issues (typically javascript errors). If Stripe.js has any issues with your customized checkout page, the Stripe API is usually used as a fallback. Finally, when this option is enabled, Stripe.js is used in both the front end as well as the back office to ensure 100% PCI compliance. 7. 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. 8. 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 back-office 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. 9. Address Verification Check Enable if you want to check the customer s billing address during checkout before processing the card payment. If the postcode of the billing address is different from the postcode of the card owner, then you can configure your Stripe account to decline the charge. You can also enable this only for performing the checks but not declining the charges. Please see the Enabling the Address Verification System section of this document for more information. 10. 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. 4

5 11. 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. 12. New Order Status This is the order status that will automatically be assigned to each new order. 13. 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: 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: 14. 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. 15. 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 16. 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. 5

6 Testing Cards You can use the following card details to try out the module while in test mode. To Test Successful Payment Use Card Details Name on card: Any Card number: Expiry Date: Must be in the future CVC: Any 3 digit number Unsuccessful Payment Same as a successful payment, but with card number 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 Expired Card Same as a successful payment, but with card number Wrong Billing Address with enabled Address Verification System (AVS) Same as a successful payment, but with card number Processing Error Same as a successful payment, but with card number 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. Also note that if you are testing AVS in live mode, your bank may suspect you of fraud and block your card, so testing AVS in live mode is discouraged. You can also find an up to date list of all testing options at 6

7 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. Saved cards will also work with IWD OnePage checkout and other one page checkout modules with no problems. 7

8 Customers can also add or remove cards by logging into their account and navigating to the My Saved Cards section. Please note that if you enable this feature 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. If you have Stripe.js enabled, adding cards from this section is also PCI compliant. 8

9 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 From the left sidebar, click Invoices, then click on the invoice to refund 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. 6. 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. 9

10 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. 4. If you need to issue a partial invoice, adjust the invoice items as shown on the screenshot. 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. 10

11 Capturing telephone orders from the back office 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: 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 Issuing invoices and capturing Authorized Only payments for instructions on how to create this invoice. Finally, if you have the Address Verification System (AVS) enabled, then placing orders from the back office will also validate the customer s billing address against the card owner s address. 11

12 Enabling the Address Verification System (AVS) When the Address Verification System is enabled, the customer s billing address (address line 1 and postcode) will be sent to Stripe during the last checkout step. Stripe will forward the billing address to the customer s bank where they will be checked against the card owner s registered address. The AVS check is typically made using only the numbers in the address line and in the postcode. If these numbers do not match the card owner s address, then the card payment will be declined. We recommend to enable this feature if your website is under attack by robots performing fake purchases with automatically generated card numbers. Enabling AVS is a two-step process; you will have to first enable it from System > Configuration > Payment Methods > Stripe Payment Gateway > Address Verification System (AVS) Do have in mind that not all banks support AVS so if you cannot test the feature, check the Stripe dashboard for an unchecked flag next to the AVS verification lines: 12

13 When AVS is enabled, the customer s address will be sent to Stripe along with the payment details, and the response will be logged against the order as shown in the following screenshot: If the address checks fail, you may wish to investigate further before proceeding to fulfill the order. If you wish to automatically decline payments with failed AVS checks, you can do this by changing your AVS settings from your Stripe account at We generally do not recommend declining payments unless your website is a victim of frequent fraudulent transactions. The reason is that customers may misspell something and it is not uncommon for Stripe to return false positives with this feature. 13

14 Once you have enabled AVS at both ends, you can test a transaction with the card number The card will be declined with a user-friendly error message and it will show in Stripe s dashboard like the following screenshot: Warning: We discourage testing AVS in live mode as your bank may block your card for fraud. 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 like Italian, you can copy the file under: /app/locale/en_it/cryozonic_stripe.csv Make sure to replace IT with the code of the target language. 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. One thing you should have in mind is that the translations file contains strings that are hardcoded in the module as well as error messages coming from the Stripe API. If we release an upgrade with modified hardcoded strings, we will update the translations file too. However if Stripe for any reason decides to change the error responses on their API, you may need to update those yourself according to the API changes. We believe this is a rare scenario but we will also make sure to add any changes we come across with each new release. 14

15 Stripe Subscriptions Installation Stripe Subscriptions is an add-on to the Stripe Payments module. This means that both modules must be installed for the subscriptions to work. For the latest version of Stripe Subscriptions, please make sure that you also have the latest version of Stripe Payments installed before installing the subscriptions add-on. The installation procedure is similar to Stripe Payments: 1. Make sure you have downloaded the module from our website at or through the 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. Under Direct package file upload, upload the.tgz file that you downloaded from our website. 6. Click the Install button when the module has uploaded successfully. Check the black console to make sure that there were no errors. 7. If you had compilation enabled, re-compile from System > Tools > Compilation. Both modules should now appear in the modules list as shown in the screenshot. You are now ready to create your first subscriptions plan. Manual Installation If for any reason the above procedure does not work (usually because the web server has no write permissions on your Magento directory), then you can install the module manually by simply extracting the.tgz file in your Magento s root directory or uploading the files by FTP. A single page refresh of your website will set up the module and its database dependencies. 15

16 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: If you have installed the module manually, please refer to the Troubleshooting section for manual uninstall instructions. Upgrading You can always download the latest version of the module from Once you have the latest version, simply uninstall and re-install the module using the same instructions as above. 16

17 Configuration Before you configure Stripe Subscriptions, you must first enable saved cards in the Stripe Payments module. This is necessary because the Stripe API will only accept a plan ID and a customer ID to create the subscription. If that customer does not already have a saved card, then creating the subscription will fail. Stripe Subscriptions uses the same configuration options from Stripe Payments. In addition to those options, you can find a Stripe Subscriptions configuration section under Payment Methods as shown in the screenshot below: Subscription Group and Cancelled Subscription Group - These options allow you to automatically assign or un-assign users from specific customer groups when they buy or cancel a subscription. The same groups will be used when they pause or resume a subscription. Failed Payments Group This group will be used when a invoice.payment_failed event is sent by Stripe to us using their Webhooks feature. If you plan on using this group, please make sure that you have configured Webhooks correctly according to the instructions in the Other 17

18 necessary configuration section. This feature can be used in combination with Magento rules to allow access to specific sections of the website, apply discounts for subscriber and anything else you can do with Magento rules. If you have configured Webhooks, then Stripe Subscriptions will also be able to handle invoice.payment_succeeded events coming from Stripe. When one such event is received, an order is re-created based on the original customer subscription at the time the event is sent. This new order can be viewed under Sales > Orders and will have an order status depending on the value of Recurring Order Status in the configuration. Send Recurring s If this option is enabled, then a customer will be sent for the newly created order after a recurring billing event has occurred. Pause/Resume Subscriptions Enable this if you would like your customers to be able to pause or resume a subscription which they have purchased. More information about how this works can be found on page 29 under the section How pausing and resuming subscriptions works. Hide grand total when zero - If a user purchases a subscription on its own (i.e. with no regular products in the cart), then Magento will display a Grand Total of zero in the shopping cart and the checkout page. This is because the Grand Total only applies to regular products. Enable this option to let Stripe Subscriptions override Magento to hide the Grand Total if it is zero, as shown in the screenshot below: 18

19 How subscriptions work Subscriptions can be created for both physical products as well as for virtual services. The difference is that during the checkout process, physical products will ask the user for a shipping address and a shipping method. Virtual products on the other hand will go straight from the billing address to the payment method and then the order review. An example of a virtual product checkout is shown in the screenshot below: The module supports several one page checkout modules out of the box, which may be used for simplifying the checkout page: 19

20 When a product like this is purchased from your website, the Stripe Subscriptions module will set up the customer profile and the subscription plan on Stripe s servers, without ever redirecting the customer away from your website. The entire process happens in the background between your server and the Stripe API (or Stripe.js API when Stripe.js is enabled). Once a subscription has been set up, a payment is taken immediately unless a trial period has been set. If there is a trial period, the first payment is taken the day that the trial expires. The subscription can be canceled from 3 different locations: by the user through their Magento account by the Magento administrator through the back office by the Stripe account holder through the Stripe dashboard A configured subscription will look like so in Stripe s dashboard: 20

21 Creating a subscription plan To create a subscription plan: 1. Go to Catalog > Manage Products 2. Click the Add Product button 3. For the product type, select Simple Product if you need to collect shipping details, or Virtual Product if you do not need a shipping address or shipping method. These are the only two types of products that can have a recurring profile, however you can associate simple and virtual products with bundled, grouped or configurable products. 4. Under the General set the Tax Class to what you like. The module will add any variable fees such as tax and shipping into the final Stripe subscription plan price, which is automatically created for you during the customer checkout. This means that the module may create multiple Stripe subscription plans for every Magento recurring product that you create. 5. Under the Recurring Profile tab, enable the recurring profile and fill in each section as follows: a. Schedule: Do not change; leave everything to their default value. b. Billing: Set the billing period to day, week, month or year. Stripe does not support half-months. If you want to charge your customers every month, set the Billing Period Unit to month and the Billing Period Frequency to 1. Leave the maximum billing cycles empty. c. Trial Period: Stripe only supports days when setting a trial period, but the module will attempt to convert the input from here into days based on the values of Trial Period Unit and Trial Billing Frequency. The remaining 2 fields are ignored by the module; however Magento requires them to be set in order to allow the customer to buy the subscription. Set the Maximum Trial Billing Cycles to 1 and the Trial Billing Amount to 0. d. Initial Fee: If you have any initial/setup costs, you can set these here. The module will make sure that these are added in the very first payment from the user as soon as the subscription is set up. 6. If you have created a virtual product, don t forget to disable stock management under the Inventory tab. You may also want to set the Maximum Qty Allowed in Shopping Cart to 1, unless it makes sense for the customer to buy the same subscription in multiple quantities. If this is the case, then the Qty in the shopping cart will be taken into consideration by the module when setting up the subscription. 7. Fill all other product options in any way you like and save the product. Once the product has been created, test a purchase on your website and make sure that a subscription plan has been created in your Stripe dashboard. An order will also have been created under Sales > Orders. This order can re-occur for every billing period when you configure Stripe Webhooks as explained in the next section. 21

22 Setting up recurring orders with Stripe Webhooks Some 3 rd party subscription modules implement subscriptions by requiring the setup of a cron job to create charges manually on a recurring basis. Stripe Subscriptions does not follow this approach - it instead uses Stripe s native subscription features. This means that once the customer signs up to a subscription plan, it is up to Stripe to continue charging the customer s card for every billing period. But how would a merchant know that a recurring billing event has succeeded or failed so that an order can be fulfilled? Stripe provides an event emission mechanism called Stripe Webhooks which can notify the merchant s website about a billing event. When a successful billing event occurs, Stripe emits an invoice.payment_succeeded event, whereas when a payment fails, Stripe emits an invoice.payment_failed event. Both of these events can be received by Stripe Subscriptions on the merchant s website and be acted upon in the following way: invoice.payment_succeeded When this event occurs, Stripe Subscriptions has an advanced feature which will find the original order of the customer and re-create it using the same order items, tax information, shipping details and coupons. If the subscription product has any initial fees configured, these will be removed from the recurring order. Furthermore, if the customer used a coupon and Stripe did not discount the billing amount for this period (i.e. because the coupon has expired), then the discount will also be removed from the recurring order. Stripe Subscriptions will automatically invoice the order offline (because the payment has succeeded) but will not mark the order as shipped. The merchant can then view this order as any other regular order coming into their website and fulfill it accordingly. If the merchant desires to mark recurring orders into a particular order state when they are created, then Stripe Subscriptions will respect a configuration setting called Recurring Order Status and will mark the order as the merchant wishes. If this setting is not set, then the order will be marked as complete. Finally, if configured, the module can also send a recurring order to the customer similar to the original that they received the first time that they have placed their order. invoice.payment_failed Stripe is very good at trying to avoid failed payments by automatically updating expired cards with the customer s bank instead of requiring the customer to enter new card details manually. However, payments may still fail if for example the customer s bank account has run out of funds. When this event is received by Stripe Subscriptions, then the module will move the customer into a Failed Payments Group that is configured from the module s configuration section. No order will be created in the Magento back office for this customer. It is up to the merchant to periodically check if any customers have been moved to the failed payments group and act according to the business needs. 22

23 Stripe Subscription sets up the following endpoint to accept Stripe Webhooks events: To connect Stripe with your Magento setup, go to your Stripe dashboard and under Account Settings > Webhooks, add the above endpoint as shown in the following screenshot: For more information about Stripe Webhooks, please refer to Developers Tip If your website is not live yet and you would like to test the Stripe webhooks, you can simulate a Stripe webhook request using the following steps: 1. First place a subscription order on your website. Note the subscription ID, e.g. sub_7coq8xn4kp9req for later use. 2. In your Stripe dashboard, configure the test webhook URL to a endpoint. 3. Send a test webhook event from your Stripe dashboard and capture the request body from request.in. Save that request body for later use. 4. Using the Chrome Postman extension, create a POST request to with a request body that is the same as the one you captured earlier. 5. Modify the subscription ID in the request body to be the same as the subscription ID of your placed order, e.g. sub_7coq8xn4kp9req. 6. Trigger the request from Postman and check if a new order was created under Sales > Orders. 23

24 Creating a configurable subscription The simplest way to create configurable subscriptions is to use the Custom Product Options tab under your product s configuration page: This will allow your customers to customize the product (and the subscription price) before adding it to their cart. Custom Product Options are suitable if you need to only adjust the price of the subscription. If you would like your customers to be able to adjust the billing frequency of the subscription (i.e. monthly, weekly etc), then you need to follow a different approach involving Magento s configurable products. To achieve configurable billing frequencies, you must first create a subscription attribute that will be used by the configurable product. You can do this from Catalog > Attributes > Manage Attributes. An example of how to set up this attribute can be viewed on the demo server on this page. You can set the labels of the attribute to whatever you want your customer to see on the product page as shown in the following screenshot: 24

25 Save the attribute and add it to your Default attribute set from Catalog > Attributes > Manage Attribute Sets. Then create a simple or virtual product for each one of the labels that you specified above, and set the recurring profile billing cycle to match the labels that you have chosen. You can see how we created the Coffee Beans subscription on our demo server by inspecting the configuration of its associated simple products in the product catalog. For each simple product that you create, make sure to set the Subscription attribute accordingly: Then, create a master configurable product, which will be associated with all the simple products. When you create this configurable product, choose the Subscription attribute as the common denominator, which has been created by the module during its installation: 25

26 When you are done setting up the master configurable product, go to it s Associated Products tab and select all the simple products that you need to associate with it: Finally, depending on how you would like the customers to select the billing frequency from the product page, go to the Stripe Subscriptions tab and select one of Dropdown/Radio Buttons/Checkbox: 26

27 This setting is specific to each individual subscription product that you create and overrides the global setting, which can be set from the module s configuration section: Reviewing and updating customer subscriptions Once a customer has purchased a subscription, they can review their plan from their account as shown in the following screenshot: 27

28 The customer can cancel, pause or resume a subscription by clicking on one of the recurring profiles and then updating its state using the top right hand buttons: Subscriptions can also be reviewed and updated from the Magento back office. To find all of the subscriptions, just navigate to Sales > Recurring Profiles. From here, you can cancel/pause/resume any subscription in the same manner as your customers can. 28

29 How pausing and resuming subscriptions works Customers can view their purchased subscriptions by logging into their customer account section: Once there, your customers can cancel the subscription, pause or resume (suspend or activate), or view the related order for that subscription. The subscription ID is the same that is used in your Stripe dashboard. Under the Subscription Schedule, your customer can view when their subscription started and based on the billing period, estimate when the next payment will happen. With Stripe Subscriptions, when a subscription is paused or resumed, a full unsubscribe and re-subscribe to the subscription plan is happening behind the scenes. This is in accordance with Stripe s official recommendations. When the customer is re-subscribed, the module moves the next billing period into the future by adding trial days on the subscription. For example, consider the scenario where you have a 1 month subscription and your customer subscribed on the 10 th of January to that subscription. The next billing date would normally be on the 10 th of February. If your customer decided to pause the subscription at any time for 5 consecutive days and then resume it, then when they resume, their next billing date will be on the 15 th of February. No payment will be charged until the 15 th of February. If the same subscription product had any trial days set, then the trial days would also be shifted in the same way and you will receive the very first payment at the end of the shifted trial days. 29

30 Furthermore, when the customer resumes the subscription, the Start Date field under the Subscription Schedule section will be updated to be their next billing date (i.e. 15 th of February in the above example). This is to prevent customer confusion about when their next billing date is. Hiding or renaming the Suspend/Activate buttons Please note that if you disable pausing/resuming subscriptions from the module s configuration section, then the module will not hide the default Suspend/Activate buttons. This is left to your theme and can easily be done with either CSS or template editing. If this feature is disabled but the buttons are not hidden, then the customer will receive a warning when they try to suspend the subscription: If you would like to rename the labels of these buttons to Pause/Resume, you can do so by editing the module s locale files under app/locale/en_us/cryozonic_stripesubscriptions.csv. Simply add the following two lines at the end of the file: "Suspend","Pause" "Activate","Resume" 30

31 Adding or updating subscription plans When you create a new plan, you should be aware that the plan is only created in your Magento store, not on Stripe. When the customer checks out with that plan in their cart, the module automatically creates the plan if it doesn t already exist. Notice how in your Stripe dashboard plans have IDs in the following format: This example plan ID is comprised of the following elements: 167 The product ID in your Magento store that has a recurring profile. GBP The currency code of your store. 900 The amount in cents/pence, i.e MONTH The billing period unit 1 The billing frequency, i.e. every 1 month This means that if you change any of the above values when updating a product with a recurring profile, a new plan will be created with a different ID. The reason for this is that Stripe does not allow plan modifications for anything other than the plan s name. It also means that customers who are already subscribed to a plan do not get affected if you decide to change something on the plan from your website. Since Stripe Subscriptions 1.3.0, if there are any variable fees such as taxation, shipping cost or qtys during the checkout, these will be added to the total amount, so multiple Stripe plans may be created for each magento recurring product depending on the checkout amount. 31

32 Coupons Stripe Subscriptions implements coupons for subscriptions, however there are some differences between Magento coupons and Stripe coupons which you must be aware of. Stripe s coupons only support the following basic features: 1. Discounts by percentage of total value. 2. Discounts by a fixed amount on total value. 3. Expiration after a certain amount of time. 4. Expiration after a certain amount of redemptions. 5. Expiration at a specific date. On the other hand, Magento can have very flexible rules on coupons and discounts, which are not supported by Stripe. You can explore all the different options by creating a Magento coupon under Promotions > Shopping Cart Price Rules. The coupons implementation by Stripe Subscriptions works by matching the Magento coupon Code with the Stripe coupon ID when a subscription order is placed. If a coupon exists in Stripe with the same ID as the Magento coupon code, then the Stripe coupon is added on the user s subscription, which means that the customer will receive a recurring discount until that coupon expires. None of the Magento rules is applied on the discount, i.e. you can only effectively apply the Stripe coupon. Please have in mind the following important points in order to configure coupons correctly: 1. Under Promotions > Shopping Cart Price Rule > Actions, you must set the Apply and Discount Amount fields to match the Stripe coupon discount. Apply can only be a percent or a fixed amount. Fixed amount does not report correctly with multi-currency. 2. Always make sure that the Magento coupon Code exists in both your live and test modes in Stripe. If a coupon is deleted from your Stripe account and a customer tries to use it, it will be silently ignored. It is up to you to keep the Stripe coupon IDs and the Magento coupon Codes in sync. 3. Stripe always applies the coupon discount on the entire Stripe invoice amount. A Stripe invoice will include both the initial fee (if any) and the recurring subscription amount. The recurring subscription amount includes shipping costs and tax. If you have any special discount rules in your Magento configuration, they will be ignored the discount is always 32

33 applied on the final Stripe invoice sum. Stripe Subscriptions modifies the Magento totals in the shopping cart, checkout screen, sales s, admin order totals, recurring webhook orders and recurring webhook s to reflect the Stripe behavior, so that your customer knows exactly what they will be charged. 4. When a Stripe webhook event causes an order to be recreated, Stripe Subscriptions will check if a discount has been applied by Stripe and if not, the recurring order will be created without the original discount coupon. Initial fees are always removed from recurring orders. Our coupons implementation will also work with a mixture of regular products and subscriptions as shown in the following screenshot: 33

34 Creating subscription orders from the back office (Mail/Telephone Orders or MOTO) Magento normally treats a subscription (or recurring profile) as an item that needs to be purchased on its own (i.e. it must be the only item in the customer s shopping cart). This is so that the customer is able to cancel or pause/resume individual subscriptions from their account without canceling an entire order s subscriptions. To convenience your customers, Stripe Subscriptions 1.5+ adds functionality to Magento that allows your customers to place orders that contain both subscription products and regular products. To achieve this, the order is split into multiple orders in the back office to comply with Magento s core features. If for example the order contains 2 subscription products and 2 regular products, then the order will be split into 3 orders in the back office one for each subscription and one with the other 2 regular products. In addition to the above, up until the latest version of Magento 1.9.x, creating orders from the back office that contained products with recurring profiles was not fully supported. Magento doesn t have a Create Recurring Profile button in the Recurring Profiles (beta) section. Stripe Subscriptions v1.6+ adds extra functionality that allows you to create orders with subscription products and allows admins to successfully capture the payments from the Magento back office. Creating subscriptions from the back office is similar with the order splitting that the customer experiences in the front-end, i.e. subscription products must be purchased on their own. However there is no order splitting in the back office. The admin is responsible for creating the subscription orders separately from the regular product orders. If the admin attempts to add both subscription products as well as regular products in a new back office order, then they will receive an error notice. 34

35 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_stripesubscriptions.csv Note: If you were using the Stripe Payments translation file before installing Stripe Subscriptions, you will have to copy your translated strings into this file. The Stripe Payments translation file stops being used after installing this add-on. To create a translation file for a different language like Italian, you can copy the file under: app/locale/en_it/cryozonic_ StripeSubscriptions.csv Make sure to replace IT with the code of the target language. 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. One thing you should have in mind is that the translations file contains strings that are hardcoded in the module as well as error messages coming from the Stripe API. If we release an upgrade with modified hardcoded strings, we will update the translations file too. However if Stripe for any reason decides to change the error responses on their API, you may need to update those yourself according to the API changes. We believe this is a rare scenario but we will also make sure to add any changes we come across with each new release. 35

36 Troubleshooting 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 Subscriptions. 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. 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 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. Broken Admin 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. Have a look at for instructions on how to disable compilation mode manually. If the CSS/JS of your Magento admin have broken, it may be a merged CSS/caching issue. Have a look at on how to disable merged CSS manually. You can then flush all the caches. 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: 36

37 Stripe Payments module app/code/community/cryozonic/stripe/ app/design/adminhtml/default/default/template/cryozonic/ app/design/frontend/base/default/template/cryozonic/ app/design/frontend/base/default/layout/cryozonic_stripe.xml app/design/adminhtml/default/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 Stripe Subscriptions module app/code/community/cryozonic/stripesubscriptions app/design/frontend/base/default/template/cryozonic_stripesubscriptions app/design/frontend/base/default/layout/cryozonic_stripesubscriptions.xml app/etc/modules/cryozonic_stripesubscriptions.xml app/locale/en_us/cryozonic_stripesubscriptions.csv 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. Usage Issues If there are no crashes but the buttons on the checkout page don t respond, make sure that you do not have any javascript errors on the checkout page by inspecting from your browser s console. If you can t get any shipping methods to appear with subscriptions and you are not using a Magento default shipping method, please check with your shipping module developer, for example WebShopMatrix s shipping module has a known problem with recurring profiles that can be fixed with an upgrade see 37

38 Customer Support If you have any other issues installing, configuring or using the module, please contact us at Module Upgrades We periodically update our module to fix bugs, add new features and to make it compatible with newer versions of Magento. All customers receive lifetime access to these upgrades. To download the latest version, please log into our website at Once you have logged in, click on My Downloadable Products from the left sidebar. You will find here the download links for the latest version of the module. Thanks Thank you for choosing our Stripe modules. If you like the modules, we would much appreciate a review on magento connect. Cryozonic Ltd Hamilton Hub, 80 Stokes Croft Bristol BS1 3QY United Kingdom 38