Stripe China Payments - Magento 1 - Documentation

About

Stripe China Payments is a add-on to our popular Stripe Payments module for Magento 1 which allows merchants to securely accept online payments with Alipay and WeChat Pay.

This is the documentation for installing, configuring and using this module 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. Before installing this module, make sure that you have the latest version of Stripe Payments 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 System > Magento Connect > Magento Connect Manager. If you have an older version, see the upgrade instructions here.
  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. Log into your website's magento admin section.
  4. Make sure that compilation is disabled from System > Tools > Compilation.
  5. Go to System > Magento Connect > Magento Connect Manager and log in.
  6. If you have been evaluating any other Stripe modules not developed by Cryozonic, please uninstall them now to avoid obscure conflicts between the modules.
  7. Under «Direct package file upload», upload the .tgz file that you downloaded from our website.
  8. Click the «Install» button when the module has uploaded successfully.
  9. Check the black console to make sure that there were no errors.
  10. If you had compilation enabled, recompile from System > Tools > Compilation.
  11. Under System > Cache Management, flush all of your caches, including Merged CSS/JS if those are enabled
  12. Make sure you have Stripe Webhooks configured.

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. Make sure you have Stripe Webhooks configured.

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 How to uninstall Stripe China Payments

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 Payments 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, you will need to manually delete each file and directory listed in the Failed/Partial/Corrupted Installations section before installing the newer version. If you simply overwrite them, you may run across template fallback issues. Once the files are removed, we always recommend the magento connect manager installation method, otherwise you can re-install using the manual method.

Configuration in Magento

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

    Magento Stripe China Payments Configuration Section

  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. Payment Applicable From: 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.
  6. Countries Applicable From: The payment methods are currently only available for merchants from Hong Kong, however you can accept payments from anywhere in the world. You can adjust this setting based on what your customers set in their billing address during the checkout.
  7. Currencies Applicable From: Determines whether the payment method will be available to the customer at the checkout based on the currency in which their order is placed. The supported currencies 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 currency is announced by Stripe.
  8. 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.
  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 method.

Testing Payment Methods

To test any of the payment methods, you can set the "Mode" of the Stripe Payments module to "Test". The setting will be read and respected by all add-ons, including Stripe China Payments, Stripe Euro Payments and Stripe Subscriptions. You can then place an order normally on your website, selecting the payment method you need to test. The payment methods are redirect-based, which means that they will not request any input from the customer during the checkout:

At the final step, 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. Then place an order on your website and either Authenticate it or Fail it from Stripe's redirect page. For SEPA Direct Debit, you will only be able to test a successful order.
  3. Then from your Stripe Events & Logs section, find the most recent event with the name "A source with ID src_xxxxxxxxxxxxx is now chargeable." or "A source with ID src_xxxxxxxxxxxxx has failed.". Click on the event and scroll down to the "Webhooks" section.
  4. Expand the webhook request and copy the request body which is in JSON format.
  5. Using the Chrome Postman extension, create a POST request to http://yourdomain.dev/cryozonic_chinapayments/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.

Saved Sources

If you are hoping to save Sources so that they can be used like saved cards, this is unfortunately not possible. The reason is that Sources are single-use objects similarly to Tokens, which can be used for a single charge and for a specific amount that is set when the original order is placed. This means that you cannot reuse this source for arbitrary amounts for other orders.

Having clarified the above, the module WILL save sources in the following situations:

  • When the Stripe Payments module is configured to "Always save cards"
  • When the Stripe Subscriptions add-on is also installed, which enables the above setting automatically.

Issuing Refunds

Because this is an add-on to Stripe Payments, you can issue refunds in exactly the same way. For instructions on how to perform a refund in Stripe Payments, 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/locale/en_US/Cryozonic_ChinaPayments.csv

To translate this file, you can copy it to:

app/locale/languagecode_COUNTRYCODE/Cryozonic_ChinaPayments.csv

This would be the same language code that you selected under System > Configuration > General > General > Locale Options > Locale for your available store views. If you must set your Locale configuration for the first time, make sure to also flush your Configuration Cache after doing so.

Troubleshooting

General Guidelines

Most issues can be resolved using the Troubleshooting instructions of the Stripe Payments 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.

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/ChinaPayments/
app/etc/modules/Cryozonic_ChinaPayments.xml
app/design/frontend/base/default/template/cryozonic_chinapayments
app/design/adminhtml/base/default/template/cryozonic_chinapayments
app/design/adminhtml/base/default/layout/cryozonic_chinapayments
app/locale/en_US/Cryozonic_ChinaPayments.csv

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.