Shift 4 (formerly Bambora)

Setting up Bambora

You need three values from your Bambora account. Get all three first, then enter them in the Foxy admin in one pass.

1. Merchant ID

Log in to your Bambora member area. Your merchant ID is shown in the top right.

2. Payment Profile passcode

1. 1

   In your Bambora admin, go to Configuration > Payment Profile Configuration.

If you do not see this option under the Configuration menu, it is not enabled on your account. Contact Bambora and ask them to turn it on — you cannot proceed without it.

1. 1

   Uncheck Do not allow profile to be created with card data duplicated from an existing profile.

2. 2

   Uncheck Require card validation. This one is optional, but recommended.

3. 3

   Click Update at the bottom to save.

4. 4

   Go to Configuration > Payment Profile Webform. Under the Form Setup checkboxes, uncheck everything except Include credit card Information.

This step is not cosmetic. If, for example, billing phone is left checked, the Foxy checkout will throw an error unless a customer supplies a phone number.

1. 1

   Copy the Payment Profile passcode from this section.

3. API passcode

In your Bambora account, go to Administration > Account Settings > Order Settings. Scroll down the page to find the API access passcode.

4. Enter the credentials in Foxy

1. 1

   In the Foxy administration at https://admin.foxy.io, go to Settings > Payments.

2. 2

   Select the payment method set you want to use. If you only have one, it will be the Default Payment Method Set.

3. 3

   Click Add payment method + and choose Bambora.

4. 4

   Fill in the Live setup block:

   • Merchant ID — from step 1

   • API passcode — from step 3

   • Payment Profile passcode — from step 2

5. 5

   Click Create to save the payment method and enable it for your store.

The panel is split into a Live setup block and a Test setup block carrying the same three fields. The Live heading reads "Live setup (inactive)" while the payment method set has Use live credentials switched off — that reflects the current state of the set, not a different set of fields.

Legacy Beanstream API

Only use this path if your store is already running on it. New integrations should use Bambora above.

The legacy option appears in the Foxy admin as Bambora (formerly Beanstream, deprecated) and takes two values: Merchant ID and SHA-1 Hash Key.

To configure the Beanstream side:

1. 1

   Enable the Require hash validation on all Payment Gateway transaction requests option.

2. 2

   Put the hash key you want to use into the Hash key field, and enter the same value into the SHA-1 Hash Key field in Foxy.

3. 3

   Choose SHA-1 as the hash algorithm.

4. 4

   If you want to allow pre-authorization transactions, select Purchase or Pre-Authorization only under Transaction Validation Options.

The legacy API has no payment profile passcode, which is why it cannot support the stored-profile features the modern API can.

Testing

Foxy provides shared test credentials for Bambora, so you can run test transactions without setting up your own sandbox account. Leave the Test setup fields as they are.

Those shared credentials only exercise the integration itself. If you need to test against your own account configuration — your own payment profile settings, your own enabled card types, your own currency — get a test account from Bambora and fill in the Test setup fields with its credentials.

Obtaining a test account

You can create a test account self-serve at https://docs.na.worldline-solutions.com/plan-your-integration/create-a-test-account/. The form asks for your name, company, business type, country (Canada or USA) and currency (CAD or USD). Software providers receive a test merchant and a partner account.

Once created, follow the same setup steps above, but enter the values into the Test setup fields rather than the Live ones.

Test card numbers

Use any name, any future expiry date, and the following address — the address matters, because it is what returns an approved AVS response:

Address: 2659 Douglas St, V8T 4M3

Visa — use CVD/CVV code 123

• 4030000010001234 — Result: Approved

• 4504481742333 — Result: Approved under $100, declined at $100 and above

• 4123450131003312 — Result: Approved, VBV — VBV passcode 12345

• 4003050500040005 — Result: Declined

Mastercard — use CVD/CVV code 123

• 5100000010001004 — Result: Approved

• 5194930004875020 — Result: Approved

• 5123450000002889 — Result: Approved

• 5123450000000000 — Result: Approved, 3D Secure — passcode 12345

• 5100000020002000 — Result: Declined

American Express — use CVD/CVV code 1234

• 371100001000131 — Result: Approved

• 342400001000180 — Result: Declined

Discover — use CVD/CVV code 123

• 6011500080009080 — Result: Approved

• 6011000900901111 — Result: Declined

Bambora also publishes a Mastercard 2-series test card, 2223000048400011 (CVV 123, approved), and a large 3D Secure card list, at https://docs.na.worldline-solutions.com/build-your-integration/payment-apis/payment-api/test-cards.

Advanced features

• Authorize only. Bambora supports authorization-only transactions, so you can authorize at checkout and capture later. This applies to both the modern and the legacy API. On the legacy Beanstream API you must first select Purchase or Pre-Authorization only under Transaction Validation Options in the Beanstream admin.

• Payment profiles. The modern Bambora API stores card data as payment profiles on Bambora's side, which is what the Payment Profile passcode is for. This is required for subscriptions and saved payment methods.

• 3D Secure. Foxy exposes no 3D Secure configuration for this gateway. Any 3DS behaviour is whatever your Bambora account is configured to do.

• Multi-currency. Not supported on this gateway.

Important notes and caveats

Endpoint migration — read this

Following the Shift4 acquisition, the legacy Bambora and Beanstream API hostnames are being retired and replaced with Shift4-owned hostnames under *.bam.shift4api.net. The published schedule is that the new endpoints become active on 25 August 2026 and the old ones are retired after 31 December 2026. Bambora states this is a domain change only — API functionality, credentials and data are unaffected.

The connection between Foxy and Bambora is Foxy's responsibility, not yours — there is no setting in the Foxy admin for you to update. If you also call Bambora directly from your own systems, you will need to update those hostnames yourself before the deadline.

Other caveats

• Payment Profile Configuration must be enabled on your account. It is not always on by default, and Bambora has to switch it on. Discover this at the start rather than halfway through setup.

• Leave only "Include credit card Information" checked on the Payment Profile Webform. Extra required fields there will cause checkout errors on Foxy, and the error will not obviously point back at this setting.

• The two passcodes are different values from different screens. The API passcode lives under Administration > Account Settings > Order Settings; the Payment Profile passcode lives under Configuration > Payment Profile Configuration. Mixing them up is the most common setup mistake.

• Do not start new work on the legacy Beanstream option. It is flagged deprecated in Foxy.

Troubleshooting

Interpreting response codes. Contact Bambora for response code definitions — they own them and can see transaction detail that Foxy cannot. Support is at https://help.na.bambora.com/hc/en-us, now operating as Shift4 North America Support.

Platform status. Bambora publishes live platform status at https://status.na.bambora.com/. Check it before troubleshooting a sudden, widespread failure.