Menu STRIPE PAYMENTS FOR MAGENTO 2 - DOCUMENTATION Table of Contents 1. About 2. Install 3. Uninstall 4. Upgrade 5. Configuration 6. Testing Cards 7. Admin Area a. Issuing Refunds b. Capturing «Authorized Only» Payments c. Creating orders from the admin area
8. Troubleshooting a. Switching to Developer Mode b. Error Logging c. Upgrades / Caching Issues d. Stuck loading spinner at checkout page e. Composer Authentication Required (repo.magento.com) f. PHP7 Invalid Stripe Secret Key 9. Customer Support ABOUT Stripe Payments is a module for Magento 2 which allows merchants to accept payments using the Stripe payment gateway. This is the documentation for installing, configuring and using Stripe Payments on Magento 2. INSTALL Warning: We recommend that you test the module on a testing server before installing it on your live web server. Please see the Troubleshooting section if you come across any installation issue.
1. If you haven t done so already, please download the module from the account section or through the email that was sent to you when you purchased the module. 2. Extract the file into your Magento root directory. The module will be installed under app/code/cryozonic/stripepayments/ 3. Ensure you have composer installed by running the composer command from a terminal. If you don't, follow the these installation instructions. You cannot use the module if you skip this step. During the installation, you may be asked for your Magento 2 authentication keys. You can get these by following the instructions here. 4. If you are installing v0.7.2 or newer, skip this step. For versions 0.7.1 and earlier, install the Stripe PHP library by running the following command from a shell at your root Magento directory: composer require stripe/stripe php:3.11.0 5. Finish the setup by running the following commands: php bin/magento setup:upgrade php bin/magento setup:static content:deploy php bin/magento cache:clean 6. If you are upgrading from a previous version, you will also need to run
php bin/magento module:enable Cryozonic_StripePayments 7. If you are using compilation, you will need to have the module disabled during compilation like so: php bin/magento module:disable Cryozonic_StripePayments php bin/magento setup:di:compile php bin/magento module:enable Cryozonic_StripePayments This will compile Magento without compiling the module. Compilation mode will be supported with a future module release. UNINSTALL 1. From a terminal, run the following commands: php bin/magento module:disable clear static content Cryozonic_StripePayments composer remove stripe/stripe php 2. Delete the module from app/code/cryozonic/stripepayments
UPGRADE You can always download the latest version of the module from the account section or through the email that was sent to you when you purchased the module. Once you have the latest version, simply uninstall and re-install the module using the same instructions as above. CONFIGURATION Navigate to Stores > Configuration > Sales > Payment Methods. There you will find a configuration section for Stripe Payments:
Enabled - Change to Yes to enable the module
Title - Change this to whatever you would like to display to the customer at the checkout page. Mode - If you would like to test a payment, leave the mode to Test. When you are ready to accept live transactions, you can change this to Live. Testing cards are provided in the next section. Stripe.js - If this is disabled, the Stripe API is used to create charges, which means that cardholder data travels through your web server (but is not saved) and gets tokenized to create a one-off charge. If your checkout page is customized, keeping this disabled will increase compatibility with your customizations. The disadvantage is that if your business operates in a country that enforces PCI compliance regulations, then in order to be compliant you will need to select a hosting provider that is also PCI compliant (i.e. that had a vulnerability scan by an Approved Scanning Vendor ). If this option is enabled, then cardholder data never travels through your webserver. It will instead go to Stripe s secure servers directly from your customer s browser, which means that you are fully PCI compliant. The downside of this option is that if your checkout page is customized in a way that does not follow Magento s best coding practices, then you may come across compatibility issues (typically javascript errors). If Stripe.js has any issues with your customized checkout page, the Stripe API is used as a fallback. Finally, when this option is enabled, Stripe.js is used in both the front end as well as the admin area to ensure 100% PCI compliance. Keys - You will also need to fill in your test and live keys that Stripe has provided to you when you created your account. You can get these by logging into Stripe, navigating to your account settings and clicking on API Keys Payment Action - Select Authorize and Capture if you would like the customer cards to be charged immediately
after a purchase. This is the default option and it does not require you to do anything else after the customer has placed the order. If you prefer to finalize the payment later, you can choose Authorize Only which will lock/authorize the order amount on the customer s card so that you can capture the amount later by issuing an invoice. You can find out more on how to capture these payments by clicking here. Pay in store currency - If you are running a multi-currency / multi-language website, then you can charge your customers either in the configured base currency or in the foreign currency that they see in the checkout. This is enabled by default, but if you have reason to prefer the base currency (i.e. some Canadian Stripe accounts have currency restrictions) then you can disable this. New Order Status - This is the order status that will automatically be assigned to each new order. Payment Applicable From - If you only want to provide this payment option to certain countries, you can optionally change the Payment Applicable From to Specific Countries Sort Order - If you have multiple payment methods enabled, this setting will determine the order of the Stripe payment method at the checkout page. For example, if you also have PayPal enabled and would like Stripe to appear after PayPal, then set this number to something larger than what is configured in the PayPal configuration section. TESTING
You can use the following card details to try out the module while in test mode. To Test Use Card Details Name on card: Any Successful Payment 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
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 ADMIN AREA Issuing Refunds 1. Go to Sales > Orders, then find and click the order you would like to refund. 2. If the module is configured in Authorize Only mode, all you need to do is press the Cancel button at the top of
the page. If on the other hand the module is in the Authorize and Capture mode, continue to step 3. 3. From the left sidebar, click Invoices, then click on the invoice to refund. 4. At the top right hand corner, click Credit Memo 5. Adjust the amount if necessary and click Refund at the bottom of the page to perform a live refund. If you click Refund Offline, the refund will only be issued in Magento but not in Stripe (an offline refund).
6. The amount should now be fully or partially refunded in Stripe and a note should appear in the Comments History of the order. It is also perfectly fine to perform a refund directly from Stripe s dashboard; however doing so will not update Magento s dashboard figures on the total amount of sales, nor will it update the order status, so we recommend to perform refunds through Magento whenever possible. Capturing «Authorized Only» payments When the module performs an Authorization for an order, what that means is that we have requested from the customer's bank to lock the order amount in the customer's bank account so that it cannot be spent elsewhere. The actual transfer of funds does not happen, so the customer will not see the payment in their bank statement. However, their available balance will be reduced and they will not be able to spend that amount even if they have the funds in their bank account. When the merchant ships the product, they can manually capture the payment through the admin area. This can be done with the following steps: 1. Go to Sales > Orders. 2. Find and click on the order for which you would like to capture a payment. 3. Click on the Invoice button as shown in the screenshot:
4. If you need to issue a partial invoice, adjust the invoice items as shown on the screenshot. The item quantity can only be reduced, not increased.
5. Click on the Submit Invoice to capture and finalize the payment. You should now see the funds transferred to your account from your Stripe dashboard. Warning: An authorized only payment will expire after 7 days, so make sure to capture your payments early to avoid creating new charges for the customer. Your customers will also be happier if you provide a speedy service. CREATING ORDERS FROM THE ADMIN AREA It is possible to create an order and charge a customer s card with details that you have received over the telephone. This feature is also known as Mail Order/Telephone Order (MOTO). To create a MOTO order: 1. Go to Sales > Orders. 2. At the top right hand side, click the Create New Order button. 3. Follow the steps and choose a customer, the store and the products for that order. 4. Select a shipping method (if applicable) before filling the payment details.
5. When you are ready to submit the order, fill in the card details as shown in the screenshot: 6. Click the Submit Order button.
If the module is configured for Authorize and Capture, then the customer s card will have now been charged and the funds transferred to your account. However, if the module is configured for Authorize Only, you will need to also capture the payment by manually creating an invoice. Please refer to the section Issuing invoices and capturing Authorized Only payments for instructions on how to create this invoice. The admin area uses Stripe.js if enabled and is fully PCI compliant. TROUBLESHOOTING Switching to Developer Mode First and foremost, before debugging any kind of Magento 2 issue, you must make sure that you have switched to the developer Magento mode. It is very hard to debug Magento 2 errors when running in production mode. Please review these steps on how to switch to developer mode. In addition to the official documentation, some people may set the Magento mode using the $MAGE_MODE environment variable from the web server's configuration files, i.e. inside Nginx's site configuration files or in Apache's.htaccess files. Make sure that if you have this configuration, it does not interfere with the mode that was set from the command line. Error Logging and 500 Server-Side Errors Magento logs Errors and Exceptions thrown during application runtime in the var/log directory. The module will
also throw Exceptions in a similar manner which will be also be logged there. To take advantage of this feature, you will need to enable logging from Stores > Configuration > Developer > Log Settings. You can find errors in the following two files: var/log/system.log var/log/exception.log If you do not have shell access, just download the file, open it with your favourite text editor and search for Stripe. Alternatively if you are on a shell, clear the console (Ctrl-L on Linux, Cmd-K on OSX) and run the following command: tail f var/log/system.log This will show live errors as they happen. You can refresh the problematic page in your browser and if there are any errors, you will see them appear in the console. Upgrades / Caching Issues If you have upgraded the module but for some reason you don't see the new changes, you can manually clear the Magento 2 cache by deleting the contents of the following directories:
var/cache/* var/page_cache/* var/di/* var/generation/* var/view_preprocessed/* var/composer_home/cache/* pub/static/* Once the above have been cleared, run the following commands: php bin/magento setup:upgrade php bin/magento cache:clean php bin/magento setup:static content:deploy Sometimes browsers also cache Magento 2 requests, if you still have caching issues, try with a different browser. Stuck loading spinner at checkout page This may happen because of one of two reasons. Possible reason 1: A server side crash
Server side crashes are logged in the Magento log files under var/log (see the above section on how to enable error logging). If you enabled error logging and still cannot see the error, please bear in mind that it may sometimes be logged in your web server's log files. If you are using a php-fpm variant, make sure to also check the log files of your fastcgi backend. If the error is not logged in any of the above places, try inspecting the network request from your browser's debug console (you can find it having a red 500 Internal Server Error response code). The error will sometimes appear in the response text of the request at the bottom of the response. For example, if the server's response ends with the following error: <b>fatal error</b>: Class 'Stripe\Stripe' not found in <b>/home/user/public_html/app/code/cryozonic/stripepayments/model/paymentmethod.php</b> on line <b>59</b><br /> Then the reason for this is because you forgot to run the composer require stripe/stripephp:3.11.0command from the installation steps. Possible reason 2: A front end javascript crash Magento 2 and the Stripe Payments 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: Errors such as the above, even if they are not caused by the module itself, they may prevent the customer from navigating or using the checkout page successfully. To make sure everything works as expected, make sure that the debugging console is always free of javascript errors. Composer Authentication Required (repo.magento.com) If you are installing composer for the first time, you may get this message in your console before installing the Stripe PHP library. The keys that you need to use are your Magento 2 marketplace keys. Please follow the instructions on this page to get your authentication keys.
PHP7 Invalid Stripe Secret Key Magento versions 2.0.0-2.0.6 have a known issue with PHP7 where obscured/password fields are not decrypted correctly. You can either upgrade to Magento 2.0.7 or if not possible, please see this commit on how to apply a patch in your existing Magento installation. CUSTOMER SUPPORT If you have any other issues installing, configuring or using the module, please contact us at info@cryozonic.com MODULES LINKS ADDRESS ABOUT CUSTOMER SU PPORT DOMAIN LICEN SES DOCUMENTATI ON UPGRADE CONTACT US TERMS & COND ITIONS REFUND POLIC Y PRIVACY POLIC Y HAMILTON HUB 80 STOKES CRO FT BRISTOL BS1 3Q Y, UK CRYOZONIC LTD IS A UK REGISTERED COMPANY WITH REGISTRATION
NUMBER 07753199 Cryozonic Ltd. All Rights Reserved.