Stripe China Payments - Magento 2 - Documentation

About

Stripe China Payments is a add-on to our popular Stripe Payments & Subscriptions module for Magento 2 which allows merchants to securely accept online payments with the Alipay and WeChat Pay payment methods.

This is the documentation for installing, configuring and using this module on Magento 2.

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. Before installing this module, make sure that you have the latest version of Stripe Payments & Subscriptions installed. You can check which is the latest version from the Changelog section towards the bottom of the product page. You can check which version you have installed from the app/code/Cryozonic/ChinaPayments/CHANGELOG.txt file in your Magento directory.
  2. If you haven't done so already, please download the Stripe China Payments add-on from your customer account section or through the email that was sent to you when you purchased the module.
  3. Extract the file into your Magento root directory with the following command:
    tar -xzvf Cryozonic_ChinaPayments-1.0.0.tgz
    The module will be extracted under app/code/Cryozonic/ChinaPayments/
  4. Enable the module by running the following commands:
    php bin/magento setup:upgrade
    php bin/magento cache:flush
  5. If you are upgrading from a previous version, you will also need to run:
    php bin/magento module:enable Cryozonic_ChinaPayments
  6. If you are running Magento in production mode, you will also need to run:
    php bin/magento setup:static-content:deploy
    php bin/magento setup:di:compile
  7. Continue to Necessary configuration in Stripe

Uninstall

From a terminal, run the following commands:

php bin/magento module:disable --clear-static-content Cryozonic_ChinaPayments
rm -rf app/code/Cryozonic/ChinaPayments

Upgrade

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

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:

Necessary configuration in Stripe

Because most of the payment methods redirect the customer away from the merchant's website, there must be a way to know whether a payment authorization has succeeded or failed. This is important because some customers never return to the merchant's website after they authorize the payment with their bank (simply because they don't think it is necessary).

To alleviate the problem, Stripe provides an event emission mechanism called Stripe Webhooks which can notify the merchant's website when a payment has been authorized, failed or canceled by the customer. To enable Stripe Webhooks, go to your Stripe dashboard and under API > Webhooks, add the module's webhooks endpoint as shown in the following screenshot:

  • URL to be called: https://yourdomain.com/cryozonic-stripe/webhooks. If you have multi-store views configured with different URLs, then you must pick one of those URLs for the webhooks. For example if you have a store view at https://en.yourdomain.com/shop/, then the webhook URL will be https://en.yourdomain.com/shop/cryozonic-stripe/webhooks. You only need to configure one webhook for your entire site.
  • Events to send: You will need to create 2 separate endpoints, one for your live website and one for your testing environment
  • Webhook version: You can use either your current one or upgrade to the latest. If you are concerned about backwards compatibility, you can check https://stripe.com/docs/upgrades for the green "MAJOR" tags in the version upgrades.
  • Filter event: Only 3 events are currently supported by the module - source.canceled, source.chargeable and source.failed. We recommend to only enable these 3 to avoid flooding your website with unnecessary requests, and so that you keep clean logs in Stripe which you can easily debug if necessary.

Once configured, your webhook endpoint will appear in Stripe like so:

One final configuration is to set your Business Name correctly from your Stripe Account section, as this is what will be displayed in the mandate for the SEPA Direct Debit payment method.

Configuration in Magento

  1. Go to System > Configuration > Payment Methods
  2. Expand the section of any payment method you need to configure as shown in the following screenshot:

    Magento 2 Alipay configuration

  3. Enabled: Enable or disable the payment method.
  4. Title: This is the name of the payment method as it will be seen by the customer at the checkout page.
  5. Optional Statement Descriptor: This is an optional small description of the source of the payment which will be shown in the customer's bank statements. If left empty, the default descriptor that is configured from https://dashboard.stripe.com/account will be used instead.
  6. Payment From Applicable Countries: Determines whether the payment method will be available to the customer at the checkout based on the country they set in their billing address. You can select "All Allowed Countries" if you want to show the payment method for all countries. An appropriate error message will be displayed at the final checkout step if the customer's country is not supported.
  7. Payment From Specific Countries: Each payment method is only available in specific countries. The supported countries of each payment method are pre-selected by default based on Stripe's documentation. We do not recommend changing this setting unless a new supported country is announced by Stripe.
  8. Currencies Applicable For: Determines whether the payment method will be available to the customer at the checkout based on the currency in which their order is placed. For the most up to date supported currencies, please refer to Stripe's documentation for Alipay and WeChat Pay.
  9. Sort Order: If you have many payment methods enabled, this setting will determine the order of this payment method at the checkout page. This is a global sort order that can be set for any payment method, including PayPal and the original Stripe Payments & Subscriptions method.

You are now ready to test the payment methods.

Testing Payment Methods

To test any of the payment methods, you can set the "Mode" of the Stripe Payments & Subscriptions module to "Test". The setting will be read and respected by all add-ons.

How to test Alipay and WeChat Pay

Before you can use Alipay, you must activate it in your Stripe Dashboard.

The payment methods do not request any input from the customer during the checkout:

Magento 2 Alipay

If the Stripe Payments & Subscriptions module is configured to be in Test Mode, then you will be redirected to a Stripe testing page for the selected payment method. An order will also be created in your Magento admin with the "Pending" order status. From the Stripe testing page, you can select to either Authorize or Fail the payment. If Stripe Webhooks have been configured correctly, then as soon as the payment is authorized, the order status will change based on the following rules:

  • Pending: The order has not been invoiced and the payment was not authorized yet. This is the initial status set when the order is created for the first time.
  • Processing: If Stripe Webhooks have been configured correctly, then as soon as the payment is authorized by the customer's bank, the module will automatically charge the customer and invoice the order. The order status will be set to Processing in Magento if the order items need to be shipped, or to Complete if the order is for a virtual product.
  • Complete: The payment was authorized, charged, invoiced, and the order items were shipped.
  • Canceled: The payment has failed or the customer canceled the payment or mandate with their bank.
  • Closed: The order has been refunded or canceled by an admin.

How to test offline (in development) without Stripe Webhooks

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.

Issuing Refunds

Because this is an add-on to Stripe Payments & Subscriptions, you can issue refunds in exactly the same way. For instructions on how to perform a refund in Stripe Payments & Subscriptions, click here.

Translations for multi-language websites

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

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

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

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

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

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

Troubleshooting

General Guidelines

Most issues can be resolved using the Troubleshooting instructions of the Stripe Payments & Subscriptions module. If anything is missing from these, please contact us at info@cryozonic.com.

Unsupported currencies

Alipay supports the following currencies: aud, cad, eur, gbp, hkd, jpy, nzd, sgd, or usd - reference

WeChat Pay supports the following currencies: aud, cad, eur, gbp, hkd, jpy, sgd, or usd - reference

The module can be configured to display the payment method or not based on the currency that is used on the checkout.

If you are testing with a supported currency but you are still receiving an unsupported currency error, it's probably be cause Alipay supports like-for-like settlement only. This means that the currency of Alipay sources must match your account’s default currency - reference. You can get in touch with Stripe to check if a specific currency can be enabled for your Stripe account.

Order stuck in Pending status

When an order is initially created, it will have a status of Pending. This is to indicate that the authorization of the payment by the customer's bank is still pending. For all redirect-based payment methods, when an authorization happens, Stripe has to notify your website through a mechanism called Stripe Webhooks. If your orders do not change from Pending to Processing, this may indicate that you have not yet configured webhooks for your website. To configure Stripe Webhooks, please see the section Necessary configuration in Stripe.