Troubleshooting

Check your Authorization header — it must use HTTP Basic Auth in the format Basic base64(clientId:clientSecret). Verify your Client ID and Client Secret are correct for the environment you're targeting. See the Authentication guide.

Every request requires an Authorization: Basic ... header. Omitting the header or supplying incorrect credentials returns 401. Ensure the Base64-encoded string encodes exactly clientId:clientSecret. See the Authentication guide.

Sandbox and production credentials are separate. Using sandbox credentials against the production environment (or vice versa) will fail authentication. Use the correct credential pair for each environment. See Environments.

Bamboo blocks requests from IPs that are not on your allowlist, even with valid credentials. Add your server's IP address to the allowlist via the Bamboo Client Portal or by contacting support.

Regenerating your Client Secret invalidates the old one immediately. Update every integration that uses the old secret. The Client ID stays the same — only the Client Secret changes after regeneration.

If the catalog returns an empty items array, check your filter parameters. CurrencyCode, CountryCode, or Name filters may not match any products. Try calling the endpoint without filters first, then narrow results from there. See Get catalog v2.

CountryCode must be a 2-letter ISO code (e.g., US, GB) and CurrencyCode must be a 3-letter ISO code (e.g., USD, GBP). Mixing them up or using the wrong value returns an empty result.

v1 returns a flat brands array with no filtering or pagination. v2 supports filtering by currency, country, name, product ID, and brand ID, plus pagination and target-currency display. Both versions are actively supported. See Get catalog v2 and Get catalog v1.

The sandbox catalog mirrors live catalog structure for realistic testing. Sandbox accounts, balances, and orders are fully isolated from production. Orders created in sandbox are associated with the sandbox channel. See Get catalog v2.

TargetCurrencyconverts display pricing to a single settlement currency without changing the underlying product denomination. It does not affect the product's native currency or the amount charged to your account.

Check the error reason code in the 400 response from Place Order. Common causes: InsufficientBalance (top up your account), InvalidProductIds (verify the product ID from the catalog), InvalidDenomination (value outside minFaceValue/maxFaceValue), UserNotEnabled (contact support). See Place Order.

When order status is PartialFailed, at least one card succeeded and at least one failed. Inspect each item's cards array for individual card statuses. Only cards with status Sold contain valid redemption codes. See Get Order.

Place Order returns a requestId. Use that value with Get Order to retrieve full order details and purchased card codes. If the order status is Pending, Bamboo has not finished processing — retry the endpoint or wait for the webhook callback. See Get Order.

Only deliver card codes to end users after the card status is Sold. Do not release codes from orders in Pending, Processing, or Failed state.

The clientReferenceNumber field in the Orders report equals the RequestId you submitted when placing the order. Use it to map Bamboo orders back to your internal records. See Orders.

Redeem payout requires a JSON body with wallet set to PayPal or Venmo. Provide exactly one of recipientEmail, recipientPhone, or recipientHandle. Missing body, invalid wallet, zero recipient fields, or multiple recipient fields return 400 validation errors. See Redeem payout.

PayPal payouts support only recipientEmail. Use recipientPhone or recipientHandle only with wallet: "Venmo".

Bamboo validates recipient format before submitting the payout. Phone numbers must have an optional leading + followed by 7 to 15 digits. Venmo handles may include an optional leading @ and must be 5 to 30 letters, digits, underscores, or hyphens.

Weblink is disabled means the link was manually disabled.Payout weblink expired means the link passed its expiration date. Failed to redeem weblink can mean the link was not found, the authenticated client does not own the underlying order, the payout was rejected, or the card is in a failed state.

Only the client that owns the underlying order can redeem the weblink or check payout status. Invalid or missing Basic Auth returns 401. A weblink owned by another client returns a generic 400 failure. Verify credentials and environment first. See Authentication.

Re-submitting the same weblink does not create a second payout. If a previous attempt used a different recipient, Bamboo rejects the request with Recipient ID does not match. Re-submit with the same recipient or investigate the original request.

A 429 response means another request is in progress for the same payout endpoint. Avoid sending parallel redeem attempts for the same weblink and retry only after the current request has completed.

Pending means the payout is still in progress, so check the status endpoint while processing. Unclaimed means the recipient does not have a PayPal or Venmo account and has about 30 days to register before funds are returned. See Get payout status.

Returned means an unclaimed payout was returned after the claim window expired. Reversed means PayPal reversed or refunded funds after they were claimed. Investigate the payout before treating it as successful.

Extract only the final path segment from the payout URL and preserve existing encoding. Padding must remain %3D. If your client turns it into %253D, the token was double-encoded and the API may not find the weblink.

Sandbox payouts use PayPal's sandbox environment and no real money is transferred. Phone-recipient payouts may not be fully testable in sandbox, so confirm that path with the PayPal or Venmo test environment before relying on it. See Environments.

Confirm your endpoint URL is a publicly accessible HTTPS URL. Check delivery attempts in the Bamboo Webhooks portal under Test Messages. Bamboo retries failed deliveries automatically. See Webhooks.

Bamboo has two notification systems. Svix webhooks deliver productupdated.v1 and ordercompleted.v1 events with signature verification via the Webhooks portal. Notification URL callbacks are order-status POST callbacks to a URL you configure via the API. See Webhooks and Notification.

Verify the three Svix headers — svix-id, svix-timestamp, and svix-signature — using your Webhook Secret and the Svix library. An incorrect secret or a modified request payload will cause verification to fail. See Webhooks.

Your endpoint must return HTTP 2xx to confirm receipt. Non-2xx responses cause Bamboo to retry delivery. Return 200 immediately and handle any heavy processing asynchronously.

Call GET /api/Integration/v1/notification to view the currently stored callback URL and secret key for your account. See Get Notification.

The sandbox and production environments use the same base URL structure but require different credentials. Ensure your integration uses the correct credential pair for the environment you intend to target. See Environments.

Each environment has its own Client ID and Client Secret. You cannot use sandbox credentials for production requests or vice versa. Obtain separate credentials for each environment from the Bamboo Client Portal.

Always validate new integrations in sandbox before moving to production. Sandbox orders, accounts, and balances are fully isolated from production. Sandbox reports and transactions return sandbox-only activity. See Environments.