WooCommerce Bambora

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

This extension supports tokenization, which lets your customers save their payment methods to their account for faster checkout, as well as enabling support for WooCommerce Subscriptions and Pre-Orders, and can also allow customers to save payment methods to their accounts.

• An active Bambora account
• An SSL certificate
• PHP 7.0+ (you can find this under WooCommerce > Status)
• WooCommerce 3.5+
• WordPress 5.2+

1. Ensure your store meets the plugin requirements.
2. Download the extension from your WooCommerce dashboard.
3. Go to Plugins > Add New > Upload and select the ZIP file you just downloaded.
4. Click Install Now and then Activate.
5. Click Configure and read the below section to learn how to set up the plugin.

Bambora has retired their legacy Beanstream payment API on March 31, 2021, so we have removed support for the legacy gateway mode in the plugin. Switch to the new Bambora payment method to enjoy features like tokenization (enabling Subscriptions and Pre-Orders support) and automated refunds and voids from within WooCommerce.

To switch to the new Bambora payment method, go to the Plugins page, find the WooCommerce Bambora plugin, and select Use the Bambora Gateway.

Then, follow the below setup documentation to generate the API Passcode needed to use the new Bambora API.

Follow the steps below to setup WooCommerce Bambora:

1. Login to your Bambora account.
2. Copy your Merchant ID at the top of the screen.
3. Go to Administration > Account Settings > Order Settings.
4. Under the Security/Authentication section, find the API Access Passcode and click Generate New Code to create a new code, if needed.
5. Copy the API Access Passcode.



6. Click Update.
7. Go to Configuration > Payment Profile Configuration.
8. Under the Security Settings section, select the API Access Passcode and paste the copied API access passcode from step 4 in that field.



9. Click Update.
10. In WooCommerce, go to the plugin settings and paste the Merchant ID and API Passcode in their respective fields.

You can configure the following settings for the Bambora gateway under WooCommerce > Settings > Payments > Bambora Credit Cards:

• Enable / Disable: Allow customers to use this gateway to checkout.
• Title: The name shown for the payment during checkout and on the Order Received page.
• Description: The text shown under the gateway’s title during checkout. Limited HTML is allowed.
• Transaction Type: Controls how transactions are submitted to Bambora. Select “Charge” to automatically capture payments. 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. Click here to read more about capturing transactions.
  • Charge Virtual-Only Orders: If Transaction Type is set to “Authorization”, enable this to automatically capture charges for orders with only virtual products. For downloadable products, this will grant downloads access right away.
  • Enable Partial Capture: If Transaction Type is set to “Authorization”, enable this setting to allow orders to be partially captured multiple times. Click here to read more about partial captures.
  • Capture Paid Orders: If Transaction Type is set to “Authorization”, enable this to automatically capture charges when orders move to a paid status.
• Accepted Card Logos: Determines which card logos are displayed during checkout. This has no impact on which cards are accepted by your merchant account.
• Tokenization: Let customers save their payment methods for future use at checkout. This is required for Subscriptions or Pre-Orders. Click here to read more about saving payment methods.
• Detailed Decline Messages: Display detailed messages to customers to provide reasoning for declines instead of a generic error message when possible. Click here to read more about detailed decline messages.
• Debug Mode: Enable when you’re having issues processing transactions. You can choose to log API requests directly on the checkout page, save them to the WooCommerce > Status > Logs page, or both. As a best practice, please do not enable this setting unless you’re having issues with the plugin.
• Environment: Switch between “Test” and “Production” credentials. Set to “Test” to send transactions to a Bambora test account for setup / troubleshooting. Click here to sign up for a test account.
• Merchant ID: Follow the steps above to retrieve your Merchant ID.
• API Passcode: Follow the steps above to retrieve your API Passcode.

As a site administrator, you can use the WooCommerce Bambora gateway to manually capture charges and automatically refund / void transactions as needed.

If the Transaction Type setting is set to “Authorization”, you can manually capture these payments from the WooCommerce Orders page. Click here to read more about capturing charges.

Bambora also allows partial payment captures when enabled in the plugin settings. This lets you perform multiple captures on an authorized order from within WooCommerce. Click here to read more about partial captures.

You can process credit card refunds directly in WooCommerce without needing to log into your Bambora account. Click here to read more about issuing automatic refunds from WooCommerce.

You can void transactions directly in WooCommerce in the following circumstances:

• If your Transaction Type setting is set to “Authorization”, you can void when the transaction has been authorized but not yet captured.
• If your Transaction Type setting is set to “Charge”, you can void when the transaction has not yet been settled (e.g. funds haven’t been transferred from the customer’s account to your Bambora account).

Bambora does not accept partial voids. If a transaction is no longer eligible to be voided, you must refund the order. Click here to read more about voiding transactions in WooCommerce.

Your customers can take advantage of the following features when your site uses WooCommerce Bambora.

⚠️ Please 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. Learn more about Payment Profiles

Customers can save payment methods during the checkout process or from their My Account area. This lets them quickly select payment details during future checkouts and also lets your site support Subscriptions and Pre-Orders.

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).

Bambora supports an enhanced checkout form that improves the checkout experience on mobile and desktop devices. Click here to read about the enhanced payment form.

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 are my customers getting a ‘CALL HELP DESK ERROR’ when they try to submit payment?
A: If the “Validate Referring Host” setting is enabled in your Bambora dashboard, Account settings> Order settings> Security/Authentication, orders will fail, listing 401 errors in the log and the ‘Call Help Desk’ error on the frontend. This setting should be “unchecked”.

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 Card Verification Value (CVV) / Card Security Code (CSC) at checkout?
A: Afraid not, sorry about this! CVV / CSC is a required field for the Bambora integration, so there is no option to turn off this field.

Q: Can I use a different merchant account based on the currency of the cart?
A: Yes! While we do not have a setting within the plugin to switch between accounts based on the currency, we do have a code snippet for this feature. Note: Customization is not covered under our support policy, so we will not be able to further modify or implement this code directly.

Click here to view and copy the code snippet.

Q: Does the plugin use Bambora’s email notifications?
A: No, the plugin does not interact with Bambora’s email notifications, but instead relies upon WooCommerce email notifications.

You may see an error message 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.

There are a few errors that indicate common setup issues:

• Duplicate match on payment information: This indicates that the “Do not allow profile to be created with card data duplicated from an existing profile” setting is enabled in your Bambora account under Configuration > Payment Profile Configuration, and that a customer is attempting to use a card that is saved to another customer profile (e.g. perhaps they are checking out without logging into their account on your site). Disable this setting 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 to a higher number.

Having a different problem? Follow these steps to make sure everything is setup correctly before posting a support request:

1. Please ensure that your site meets the plugin requirements.
2. Check the FAQs to see if they address your question.
3. Confirm that your Merchant ID and API Passcode are correct.
4. Enable debug mode and review the errors messages provided by Bambora. Click here to review the error codes in 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.

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

Already purchased and need some assistance? Please check out our troubleshooting tips and frequently asked questions for common issues or get in touch with support if you need more help.