WooCommerce Setup

Learn how to connect your BlueSnap and WooCommerce accounts

WooCommerce is an open source, e-commerce platform for businesses around the globe. Connect your WooCommerce store to BlueSnap to benefit from the ability to accept card payments worldwide.

Note: You can connect multiple WooCommerce stores (i.e. domains) to a single BlueSnap account for streamlined account management. You can also connect other shopping carts to the same BlueSnap account.


Make sure you have finished preparing your BlueSnap account for a shopping cart integration before you begin.
A PCI compliance of SAQ-A is required.


Before you get started:

  • A few steps need to be taken internally to prepare your BlueSnap account. Contact an Implementation Specialist, requesting your account be prepared for integration.
  • Latin America (LatAm) is not supported.

Recommended Versions

We recommend that you use the following versions when using the BlueSnap plugin for WooCommerce. The plugin may work when using older versions of PHP and MySQL as well, but we cannot guarantee it.

Recommended Version


5.6 or higher


5.6 or higher


4.5.3 or higher


2.6.7 or higher

WooCommerce Pre-Orders

(minimum version supported)

WooCommerce Subscriptions

(minimum version supported)

Setup Steps

Step 1: Plugin Installation and Configuration

Install and configure the WooCommerce BlueSnap Payment Gateway plugin, as follows:

  1. Make sure you have finished preparing your BlueSnap account for a shopping cart integration.

  2. Make sure you have a working WordPress platform. WooCommerce is a WordPress plugin that is installed on top of the WordPress platform. If you don't yet have a working WordPress installation, you may want to contact your website hosting provider, as many of them supply a quick-install process for WordPress.

  3. Make sure you have the WooCommerce Plugin installed. Go to: https://wordpress.org/plugins/woocommerce/ or to http://www.woothemes.com/woocommerce/ to download the WooCommerce plugin.

  4. If you wish to use the Pre-Orders or Subscription functionalities, make sure that the respective plugins are also installed in your WordPress website:

  5. Install the BlueSnap Payment Gateway plugin on top of your WordPress platform. Click Plugins > Add New in the left menu. Search for BlueSnap in the search box in the top right side. Click the BlueSnap Payment Gateway plugin and install it.

  1. Now you are ready to activate the plugins. Click Plugins > Installed Plugins in the left menu. In the installed plugin screen, activate the following plugins, in this order:
    • WooCommerce
    • WooCommerce Subscriptions (optional)
    • WooCommerce Pre-Orders (optional)
    • BlueSnap Payment Gateway


In order for the installation to be performed properly, you must activate them in the order listed above.

  1. Click the CSE Settings link below the BlueSnap Payment Gateway plugin. The BlueSnap Card Payments page appears.
  1. Configure the following settings in this page:
    • Select the Enable BlueSnap payment using credit/debit card checkbox.
    • If you wish to use your BlueSnap Sandbox account, select the Sandbox mode for Credit/Debit Card checkbox. Leave it unselected if you wish to use your BlueSnap Production account.
    • API Username: Enter your BlueSnap API username, including the "API_" prefix.
    • API Password: Enter your BlueSnap API password. Important: Any time you change this password in BlueSnap, you must also update it here.
    • Merchant ID: Enter your BlueSnap Merchant ID.
    • Store ID: Enter the relevant store ID.
    • Order Contract ID: Enter the ID of the contract for one-time orders.
    • Subscriptions Order ID: Enter the ID of the contract for recurring orders.
    • CSE Key: Enter the Client Side Encryption Key from your BlueSnap account.

Finding your BlueSnap settings

You can find your BlueSnap API credentials, store ID, contract IDs, Merchant ID, and CSE Key in the BlueSnap Merchant Console. For instructions, see Preparing your BlueSnap account for a shopping cart.

  1. Click Save Changes.

  2. Verify that your WooCommerce installation complies with what is described in the filename section in https://docs.woothemes.com/document/jquery-cookie-fails-to-load/.
    Otherwise, your shoppers might experience errors that will prevent their transactions from going through.
    In addition, please check that there are no Javascript errors in your browser’s console (usually accessed via F12 on Windows or command+option+i on MAC-OS).

Step 2: Setting the Default Currency

Configure the default currency settings for WooCommerce by going to WooCommerce > Settings > Checkout > BlueSnap Card PMTS and define the settings under Currency Options.

Step 3: Currency Conversion Configuration

BlueSnap works with many currencies (see a complete list here). The BlueSnap plugin for WooCommerce includes a built-in currency converter that you must configure in order to enable successful purchasing via BlueSnap. Follow these steps:

  1. In the left menu of the WooCommerce admin console, go to WooCommerce > Settings.

  2. From this page, select "Checkout" on the top tab, and "BlueSnap Card Payments" from the options within this page.

  1. Verify that the Enable BlueSnap currency converter checkbox is selected.

  2. Select the currencies to use in your store. Make sure you select all the currencies that the WooCommerce store supports.

  3. Click Update Rates Now. This enables the BlueSnap currency conversion.

  4. Click Save Changes.

Step 4: Force secure checkout (SSL)

In order to use BlueSnap, you must use SSL and force secure checkout in WooCommerce.

There are two methods available:

  • Setup for WooCommerce versions earlier than 3.4
  • Setup for WooCommerce versions 3.4 and later

Please complete these two requirements for versions earlier than 3.4:

  1. Install SSL on your server.
  2. In WooCommerce, go to Settings > Checkout and select the Force secure checkout option. This means that WooCommerce will force an SSL check.

For versions 3.4 and above, please complete the following requirements:

  1. Install SSL on your server.
  2. In WooCommerce, go to Settings > Advanced and set the woocommerce_force_ssl_checkout option to "yes."
  1. If applicable, set up the woocommerce_force_ssl_checkout option to display while the site is loading via HTTPS; otherwise, it will be hidden (see explanation below).


The Force SSL option only appears if the site is not already loading via HTTPS.

If the site does load over HTTPS, the Force SSL option will be hidden. If you’d like to toggle this option regardless of whether the site is loading via HTTPS, then go to https://<yourwebsite.com>/wp-admin/options.php and set the woocommerce_force_ssl_checkout option to either Yes or No. (Remember to change <yourwebsite.com> to your actual domain.)

For example, the following screen shot of the options.php page displays where you can toggle the option:


Only advanced users should use the options.php page – it allows you to change settings directly on your database, so make a backup before making this change.

Step 5: Crontab Setup

It is recommended that you add a line to your crontab. The crontab is an application that runs in the server operating the WordPress application, and is in charge of periodic actions. It ensures that subscriptions continue to charge on time even if your WooCommerce store has no traffic, stores automatic renewals, handles pre-orders, and handles rate updates and log cleanups.

The crontab file is available to you in most UNIX/Linux based machines, and often can be found in /var/spool/cron. If you are not sure where your crontab file is, please reach out to your IT team or hosting provider for more details.

You should add the following line to your crontab file:
*/15 * * * * {wget path} -q -O – {Web domain of your WooCommerce Store}/wp-cron.php?doing_wp_cron

For example:
*/15 * * * * /usr/bin/wget -q -O - http://shoppingcarts.bluesnap.com/wordpress/wp-cron.php?doing_wp_cron

If you have multiple WooCommerce Stores running on the same server, you should add this line for each one of them.

Note: */15 makes the crontab run every 15 minutes. You can change the cron frequency if you wish.

For additional help, please contact Merchant Support.

Best Practices & Tips

Base Currency

BlueSnap enables you to take payments in multiple currencies. Each store has a single base currency, in which you define the price of your products.


We do not recommend changing the store’s base currency.

If you allow your shoppers to place an order in a different currency, the price is converted from your base currency and the shoppers pay the amount they see in their local currency. You will then see this sale reported in your dashboard in your base currency, via BlueSnap conversion rates. If this is an ongoing subscription, your shoppers will keep paying the same amount in their selected currency. This means you will receive a different amount (in your base currency) with each payment.

When your shoppers access their account via “My Account”, they will see their previous purchases listed in the store’s base currency, which may be different from the currency they paid in. The shopper will be able to see the currency and price they paid in only if they access a specific order.


You may want to consider having different stores, each with a different base currency, so you can view the sales amounts correctly in each currency.

Supported Currencies

Some card brands have restrictions regarding the currencies they can process. If the transaction fails due to unsupported currency, it is most likely due to the shopper attempting a combination of card type and currency that is not available. Visa and Mastercard should work with most currencies. Please note that Brazilian Real is not supported.

Refunds & Cancellations

All refunds and cancellations must be performed directly through the shopping cart console to avoid having WooCommerce and BlueSnap out of sync with each other.
Note: Pending orders that you cancel in WooCommerce will still appear to be pending in BlueSnap, although they are in fact cancelled.

Supported WooCommerce Plugins

BlueSnap supports:

  • WooCommerce Subscriptions, for subscription billing
  • WooCommerce Pre-Orders, for capturing payment information prior to product availability, and then processing those payments automatically when the pre-order becomes available.
    Note: Uncaptured authorizations/pre-orders will expire after 7 days. If you are unable to deliver during the 7 days you'll need to perform a subsequent authorization.

Process Logs

Process logs can be a useful tool for developers, particularly for troubleshooting. To access process logs for the BlueSnap plugin, go to WooCommerce > System Status. Once on this page, select the Logs tab.

WooCommerce Setup

Learn how to connect your BlueSnap and WooCommerce accounts

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.