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 (domains) to a single BlueSnap account for streamlined account management. You can also connect other shopping carts to the same BlueSnap account.

Supported Features

3D Secure
Auth/Capture and Separate Auth and Capture
Built-in Fraud Prevention and Risk Management
Chargeback Management
Multiple Currencies and Multiple Languages
Partner Sandbox Testing
Payment Analytics and Reporting
Payment Methods: ACH/ECP, Apple Pay, Credit/Debit Cards, Google Pay, and Splitit
Payment Optimization
Vaulted Shoppers
WooCommerce Pre-orders
WooCommerce Subscriptions

Requirements

Software

This guide assumes that 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.
• WooCommerce software installed and uploaded to your server.
  If you need the plugin, go to https://wordpress.org/plugins/woocommerce/ or to http://www.woothemes.com/woocommerce/ to download the WooCommerce plugin.
• If you want to use the Pre-Orders or Subscription functionalities, make sure that the respective plugins are also installed in your WordPress website:
  • Pre-Orders:
    http://www.woothemes.com/products/woocommerce-pre-orders/
  • Subscriptions:
    http://www.woothemes.com/products/woocommerce-subscriptions/

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; however, the following versions have been tested to ensure compatibility.

Supported Currencies

BlueSnap supports the currencies listed here. We recommend configuring your store to only accept currencies supported by BlueSnap.

Supported Countries

BlueSnap supports the countries listed here. If a shopper is located in one of these supported countries, they will be able to purchase with the BlueSnap payment module.

PCI Compliance

A PCI compliance level of SAQ-A is required.

WooCommerce Setup

Step 1: Configure your BlueSnap account settings

Complete these steps in your Merchant Portal for production or sandbox.

1. Get your BlueSnap API credentials and define the authorized IP addresses for your server. Both of these actions are performed on the same page; for instructions click here.

2. Set up your statement descriptor. The statement descriptor is the description that appears on the shopper's credit card statement or bank statement for each transaction and helps the shopper identify the transaction.

   • Go to Settings > General Settings.
   • In the Branding Settings section, enter a Default Statement (Soft) Descriptor and Support Phone Number (both appear on the shopper's statement).
   • Click Submit.

3. To get paid, you need to configure your payout settings. Refer to Payout for more information.

Step 2: Install the plugin

Install the BlueSnap Payment Gateway plugin, as follows. You can also click here to go directly to the plugin.

1. In WordPress, click Plugins > Add New in the left menu.

2. Search for BlueSnap in the search box on the top-right side.

3. Click the WooCommerce BlueSnap Gateway plugin and install it.

4. Click Plugins > Installed Plugins in the left menu.

5. In the installed plugin screen, activate the following plugins, in this order:

   • WooCommerce
   • WooCommerce Subscriptions (optional)
   • WooCommerce Pre-Orders (optional)
   • WooCommerce BlueSnap Gateway

🚧

Important

If these are not activated in the specified order, the installation will not complete properly.

Step 3: Set the default currency

Configure the default currency settings for WooCommerce by completing the following steps:

1. Go to WooCommerce > Settings > General.

2. Scroll down to Currency Options and set the following:

3. Click Save Changes.

Step 4: Configure the plugin

Configure the BlueSnap plugin using the following steps:

1. Click the Settings link below the BlueSnap plugin.
   The BlueSnap page opens.

2. Configure the following settings.

📘

Note

You can find your BlueSnap information (API credentials, Merchant ID, and more) for the following settings in your Merchant Portal in Settings > API Settings.

3. Click Save Changes.

4. If you would like to accept ACH payments, enable this feature by going to WooCommerce > Settings > Payments and setting the BlueSnap ACH toggle to enabled.

5. Click Save Changes.

📘

ACH and Subscriptions

If you plan to offer ACH as a payment method for subscriptions, please note:

• You will need to contact Merchant Support to have this feature enabled.
• ACH is not supported for subscriptions with daily billing, as banks take several days to authorize these charges.

Step 5: Secure checkout

Ensure that you are using secure checkout by completing the following steps.

1. Go to WordPress > Settings > General.

2. In the following URL fields, make sure that the URL begins with https://:
   • WordPress Address (URL)
   • Site Address (URL)

Step 6: IPN Setup

Instant Payment Notifications (IPNs) are webhooks that trigger an HTTP POST message to your WooCommerce account when an important event occurs. Follow the steps below to set up IPNs.

1. Log in to your BlueSnap account and go to Settings > IPN Settings.

2. Select the Receive Instant Payment Notifications check box.

3. Update the IPN URL(s) field. The format of the URL should follow this pattern:
   https://www.yourdomain.com/?wc-api=bluesnap

4. To enable specific IPNs, click Select IPNs. In the section that opens, toggle the button next to the IPN to select it. We recommend enabling the following IPN types:

   • AUTH_ONLY
   • CANCEL_ON_RENEWAL
   • CANCELLATION
   • CANCELLATION_REFUND
   • CHARGE
   • CHARGEBACK
   • CHARGEBACK_STATUS_CHANGED
   • CONTRACT_CHANGE
   • DECLINE
   • FAILED_PAYOUT_TRANSFER
   • RECURRING
   • REFUND
   • SUBSCRIPTION_REMINDER

5. If you plan to offer ACH as a payment method for subscriptions, make sure to select the Send Subscription Charge Failure IPN.

6. Click Submit.

For more information on IPNs, refer to our IPN documentation.

Step 7: Crontab Setup

We recommend 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, and handles pre-orders.

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, 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, contact Merchant Support.

Styling your Payment Form

BlueSnap supports the ability to customize the card elements (such as text color or font size) of the payment form. To do this, edit the BlueSnap plugin's JavaScript by creating a bluesnapStyleOverrides object that contains your styling. See Supported selectors and Supported CSS properties for details. Use the code below as a starting point.

const bluesnapStyleOverrides = {
  '.invalid': {
    //style all invalid elements
    color: 'red'
  },
  '.valid': {
    //style all valid elements
    color: 'green'
  },
  ':focus': {
    //style all elements on the focus event
    color: 'orange'
  },
  '#ccn': {
    //style only the card number element
    color: 'blue'
  },
  '#cvv': {
    //style only the CVV element
    'font-size': '30px'
  }
};

Customizing Error Messages

BlueSnap allows you to customize the messages of any errors that occur, giving you full control over the error descriptions that display in the UI or in error logs. To use this feature, you'll need to add custom code to your WooCommerce account. We recommend using a plugin such as Code Snippets to accomplish this.

Use the code sample below as a starting point. You can change error descriptions and add/remove errors from the code below.

add_filter(
  'wc_gateway_bluesnap_api_errors',
  function ( $errors ) {
      $errors = array(
          '10000|INVALID_API_VERSION'        => __( 'API version is not correct...', 'woocommerce-bluesnap-gateway' ),
          '10001|VALIDATION_GENERAL_FAILURE' => __( 'This is a val.gen. failure error.', 'woocommerce-bluesnap-gateway' ),
          '14002'                            => __( 'This is the new error message for 14002', 'woocommerce-bluesnap-gateway' ),
          '14002|SYSTEM_TECHNICAL_ERROR'     => __( 'This is the new error message for 14002|SYSTEM_TECHNICAL_ERROR', 'woocommerce-bluesnap-gateway' ),
          '14016'                            => __( 'This is the new error message for 14016', 'woocommerce-bluesnap-gateway' ),
      );
      return $errors;
  }
);

More error codes can be found in our Developer Hub. See:

• Alt Transaction Errors
• Card Transaction Errors
• Wallet Errors

Managing Orders

If card charges are not automatically captured, they will result in authorizations that need to be captured later. For example, if you sell physical goods, you'll need to capture the authorization when the items are ready to be shipped out. Orders can be conveniently managed from your WooCommerce account by following these steps:

1. Go to WooCommerce > Orders and click the order that you want to manage. The order's status will be On hold.
   
   Note: ACH charges can also have a status of On hold.

2. In the Status dropdown, select one of the following:

   • If you want to capture the authorization, select Processing or Completed.
   • If you want to cancel the authorization, select Cancelled.

Best Practices & Tips

Considering shopper impact of currency conversions

While transactions are placed in your store’s base currency, you might have your store configured to display product prices in multiple currencies. To account for any differences between the currency conversion rates used to display prices on your website and the rates used by the shopper’s issuing bank, we recommend including a note on your checkout page that informs shoppers of potential price variations. For example: “The price listed is approximate and may vary slightly”.

Reporting

Use BlueSnap's reporting capabilities to gain a comprehensive understanding of your business through detailed transaction and payout reports, payment conversion reports, and much more. Reports can be viewed right in your Merchant Portal or pulled via the Reporting API to be parsed or pushed to your third-party reporting tools.