WooCommerce Bambora

Overview ↑ Back to top

WooCommerce Bambora (formerly Beanstream) allows you to process payments directly on your site at checkout via Bambora’s payment processing services. A Bambora account is required to use this plugin.

This extension supports WooCommerce Subscriptions and Pre-Orders, and can also allow customers to save payment methods to their accounts. This document will show you how to setup and configure the extension to work with your Bambora account.

WooCommerce Bambora does not currently support the following features:

  • Interac debit via Bambora
  • 3D Secure

As such, please ensure that the Verified by Visa option is disabled in your Bambora account, or Visa payments may not process properly.

We do have these on our roadmap for the plugin and we’re gathering votes to gauge interest in these features. If you have some feedback on which is important to you, we’d love to hear it! Get in touch to let us know.

An SSL certificate is required when using the legacy gateway by Bambora to protect customer payment information.

Gateway Mode Comparison ↑ Back to top

Merchants who previously used this plugin with Beanstream’s payment processing will use the legacy payment gateway mode by default. New installs should not use this legacy mode.

For existing merchants, you can “switch” to the new Bambora payment method, which adds tons of new features, such as refunds, voids, saved payment methods (and Subscriptions support), and more. To do so, please go back through the setup documentation below, as you need to generate an API Passcode to use the new Bambora API.

Once you’ve done so, you’ll be able to switch over to the newer gateway mode from the Plugins menu by clicking “Use the Bambora gateway”, and then re-enter your settings to use the newer features.

WooCommerce Bambora gateway switcher

Installation ↑ Back to top

  1. Download the extension from your WooCommerce dashboard
  2. Go to Plugins > Add New > Upload and select the ZIP file you just downloaded
  3. Click Install Now, and then Activate
  4. Go to WooCommerce > Settings > Payments > Bambora Credit Card and read the next section to learn how to setup and configure the plugin.

Requirements ↑ Back to top

Setup and Configuration ↑ Back to top

In order to process payments via Bambora in your WooCommerce stores, you need to have an active gateway account with Bambora. Log into your account, and follow these steps to get your credentials.

  • In the top left, click on “Administration”, then “Company Info”
  • Once you’ve gotten to this screen, copy your Merchant ID and paste this into the plugin settings:
    WooCommerce Bambora - get merchant ID
    Get Merchant ID
  • Now go to “Account Settings”, then “Order Settings”. Scroll down to the Security/Authentication section.
  • Click “Generate New Code” for the API Passcode, save the Bambora settings, and paste the code into the plugin settings.
    WooCommerce Bambora generate API passcode
  • Finally, you must also paste this API passcode elsewhere in your account, especially if you want to enable tokenization or saved profiles for customers. Go to “Configuration”, then “Payment profile settings”, and paste your API passcode here as well, then save your Bambora settings. This will allow the plugin to use saved cards for customers as well as process transactions.
    WooCommerce Bambora API passcode settings

Extension Settings ↑ Back to top

The settings for the plugin are located under WooCommerce > Settings > Payments > Bambora Credit Card:

WooCommerce Bambora settings
Extension settings
  • Enable / Disable – This will enable the gateway to be used by customers to checkout.
  • Title – This is the text shown for the payment during checkout and on the Order Received page.
  • Description – This is the text shown under the title during checkout. Limited HTML is allowed. If you enable test mode, this section will also display a notice along with test credit card numbers.
  • Transaction Type – This controls how transactions are submitted to Bambora. You may choose either “Charge” or “Authorization”. If you select “Authorization”, you must manually capture and settle payments in your Bambora control panel or on the WooCommerce orders screen after the transaction has been submitted. This defaults to “Charge”.
  • Charge Virtual-Only Orders – (Shown if Transaction Type is set to “Authorization”) Enable this to force charges on order containing only virtual items so they’re captured immediately instead of authorized (for example, to grant download access right away)
    WooCommerce Bambora capture settings
  • Enable Partial Capture – (Shown if Transaction Type is set to “Authorization”) Enable this to allow multiple captures per order, up to 100% of the order total.
  • Capture Paid Orders – (Shown if Transaction Type is set to “Authorization”) Enable this to automatically attempt to capture transactions when orders change to a paid status.
  • Accepted Cards – This controls the card logos that display during checkout. This is purely cosmetic and has no affect on the cards actually accepted by your merchant account.
  • Tokenization – Enable this to allow customers to save their payment methods for future use at checkout. This must be enabled if you use Subscriptions or Pre-Orders.
  • Detailed Decline Messages – Enable to display detailed messages to customers to provide reasoning for declines when possible instead of a generic error message.
  • Debug Mode – Enable this is you are having issues correctly processing transactions. You can either log API requests / responses directly to the checkout / thank you page, save them to the WooCommerce Error Log (found under WooCommerce > System Status > Logs) or both. All debugging messages are cleaned of sensitive information before display, but as a best practice, please do not enable this unless you are having issues with the plugin.

Connection settings

WooCommerce Bambora connection settings

  • Environment – Switch between “Test” and “Production” credentials. Enable “Test” to send transactions to your Bambora Test Account. Note: This is an entirely separate sandbox environment that requires a separate login. You can sign up for a test account here. Once you have done this, you can enter a separate Merchant ID and API Passcode for your test account.
  • Merchant ID – Your Bambora account merchant ID. Follow the steps above to get this.
  • API Passcode – Your Bambora account API passcode. Follow the steps above to get this. Be sure your API passcode is set for your Bambora order settings as well as your payment profile configuration.

Merchant Usage ↑ Back to top

Capture Charges from WooCommerce Order Admin ↑ Back to top

Using version 2.0+ of the extension allows you to authorize charges during checkout, then manually capture them later. You can do this via your Bambora control panel, or can easily do so from the WooCommerce Edit Order page.

You can read more about capturing charges with Bambora here.

Partial Captures ↑ Back to top

Bambora also allows for partial payment captures when enabled in the plugin settings. This provides the ability to perform more than one capture on an existing authorization from within WooCommerce.

To perform a partial capture, edit the order, and click “Capture charge” for the order actions.

WooCommerce Bambora start capture

You can then enter the desired amount for the capture, and can process the capture. You can repeat this action until the total possible capture amount has been used.

WooCommerce Bambora process capture

Automatic Refund Support ↑ Back to top

Version 2.0.0 of Bambora adds automatic refund support. This means that refunds can be processed directly in WooCommerce without the merchant logging into his or her Bambora account.

You can read more about performing refunds with Bambora here.

Void Transaction Support ↑ Back to top

Transactions can be voided by using the same workflow as refunds. A void will occur if the transaction has been authorized, but not captured. In the case of Bambora, voids will also occur for authorized & captured transactions that have not yet been settled. As funds haven’t been transferred, a refund can’t truly be processed.

Voided transactions must be voided in full; partial voids are not accepted by Bambora. You can read more about voiding transactions here.

Customer Experience ↑ Back to top

Checkout Experience ↑ Back to top

When checking out with Bambora, customers will see the secure, hosted payment fields from Bambora. While these fields appear to be part of your checkout form, they’re iframes served directly from Bambora, making this checkout PCI-compliant (meeting SAQ-A standards). This will allow customers to enter payment information, and if they’re logged into your store, offer to save payment methods for future use (when Payment Profiles and Tokenization are enabled).

WooCommerce Bambora checkout

If existing customers have saved payment methods with your store, then they’ll be offered the option to use these saved payment methods, or to add a new card.

WooCommerce Bambora checkout with saved cards

Saved Payment Methods ↑ Back to top

Customers can save payment methods during your checkout process or from the account section to use them in future checkouts, with Subscriptions, or for Pre-Orders. Note that customers cannot save payment methods if they checkout as a guest since there’s no account to assign cards to.

Customers can manage their saved payment methods by going to their My Account page and scrolling to the “My Payment Methods” section. From here they can set any available saved payment method as the default, add nicknames for payment methods, or click the “Delete” action to delete the payment method.

WooCommerce Bambora enhanced saved payment methods
Saved payment methods

Customers can also add cards by clicking “Add Payment Method”. This will give them a form to securely save a payment method for future use without going through checkout. You can read more about adding saved payment methods from the account here.

WooCommerce Intuit Payments: Add payment
Customer Add Saved Payment

Other Information ↑ Back to top

Subscriptions / Pre-Orders Support ↑ Back to top

This gateway fully-supports all features of WooCommerce Subscriptions and WooCommerce Pre-Orders with credit cards and eChecks. You should confirm that tokenization is enabled under the extension’s settings in order to use Subscriptions or Pre-Orders, and that your API passcode has been generated for order settings as well as payment profile configuration.

Please also confirm that tokenization is available for your Bambora account with your representative (Bambora calls these “Profiles”). There may be a service charge to enable this.

When Subscriptions is used, the enhanced “My Payment Methods” table is also active to prevent deleting cards associated with a subscription. You can read about subscription saved methods here.

Enhanced Checkout Form ↑ Back to top

Bambora supports an enhanced checkout form, which improves both mobile and desktop checkout. You can read about the enhanced payment form here.

WooCommerce Bambora Enhanced Checkout Form
Credit Card Checkout (Twenty Sixteen theme)

Detailed Decline Messages ↑ Back to top

When detailed decline messages are enabled, they will provide informative error messages to the customer at checkout when Bambora returns a useful response.

You can read more about detailed decline messages here.

Storing Credit Cards ↑ Back to top

Credit card information is not stored on your server, rather it is tokenized and stored on Bambora’s secure servers, which reduces your PCI compliance burden. Learn more about Payment Profiles. You can enable the “Tokenization” setting in the plugin to allow securely saving cards.

You can read more about managing saved card tokens within your website here.

Test Transactions ↑ Back to top

Bambora has testing cards available that you can use with your account to confirm set up is done correctly. Please refer to the testing document for card numbers to use along with the expected responses for each.

Troubleshooting ↑ Back to top

Refund Issues ↑ Back to top

You may see an error message that looks something like this when trying to process an automatic refund:

Oops, you cannot partially void this order. Please use the full order amount.

This means that you’re trying to perform a partial refund, but the charge has not been settled (typically when you try to refund within a day of the purchase). The plugin tries to void this order since the funds have not been transferred (to cancel the order instead of refunding it), but Bambora does not permit partial voids.

Please wait until the charge has settled (about one day after the charge was made) to refund this transaction.

Known error responses ↑ Back to top

There are a few errors in Bambora that indicate common setup issues:

  • Duplicate match on payment information: This indicates that a setting under Configuration > Payment profile configuration is enabled. The setting is, “Do not allow profile to be created with card data duplicated from an existing profile” enabled, and the same card information exists for a different customer. You can disable this setting if you’d like to allow duplicate profiles.
  • Maximum number of credit cards is reached: Bambora has a setting to limit the number of saved profiles per customer. You can change this in your Bambora account under Configuration > Payment profile configuration by adjusting the “Maximum number of cards shown” setting and changing it to a higher number.

Other troubleshooting ↑ Back to top

Having trouble with something else? Follow these steps to make sure everything is setup correctly before posting a support request:

  1. Check that your Merchant ID and API Passcode are entered correctly
  2. Double-check that your Merchant ID and API Passcode are entered correctly šŸ˜‰
  3. Make sure that Verified by Visa is disabled in your Bambora account if your Visa transactions in particular aren’t going through
  4. Enable debug mode to the checkout page and review the errors messages that Bambora is providing. Please check these error codes with the Bambora Response Code Reference. In some cases, such as a transaction being held for review or declined, the plugin cannot change the issue and it must be resolved in your Bambora account.
  5. Submit a help request and include the debug information for further troubleshooting.

Frequently Asked Questions ↑ Back to top

Q: My base country does not use State / Province – what do I do?
A: If your base country does not require State / Province on orders or receive orders from other countries, you can disable it in Bambora. In your Bambora dashboard, go to Administration > Account Settings > Order Settings, then check the field “Billing address optional” so that customers can check out without using a State/Province.


Q: Why is my WooCommerce currency ignored by Bambora?
A: The base currency for Bambora is set by the Merchant ID and visible in the Bambora dashboard, and will not be pulled in from WooCommerce. In order to change base currency for your site, you need to request a new Merchant ID with the target base currency, then update your WooCommerce Bambora Payment Gateway settings to use the new Merchant ID.


Q: Can I turn off the CVV?
A: Afraid not, sorry about this! CVV is a required field for the Bambora integration, so there is no option to turn off this field.


Q: Does the plugin useĀ Bambora’s email notifications?
A: No, the plugin does not interact with Bambora’s email notifications.

Questions & Support ↑ Back to top

Have a question before you buy? Please fill out this pre-sales form.

Already purchased and need some assistance? Please have a look at our troubleshooting steps to see if the issue can be resolved independently, then get in touch with support via the help desk.

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top