BBG partner API reference
These docs show the BBG request format, BBG signing headers, BBG endpoint paths, and the request payload fields expected by BBG partner API flows.
Endpoints are documented with BBG partner paths only. Use your configured {{baseUrl}} plus the BBG route shown in each endpoint card.
Request body fields follow the BBG schema shown in each endpoint section, alongside BBG-specific transport paths and headers.
All examples below use the recommended BBG success and error wrapper so the docs stay consistent across endpoints and flows.
Environment base URLs
Prefix every BBG partner endpoint path shown in this reference with the base URL for your target environment. Use Sandbox for integration and testing, and Production for live traffic.
Use this base URL for integration and testing.
Use this base URL for live traffic.
Standard BBG request headers
Every BBG request is signed. The public headers below are the only authentication headers documented in this reference.
Canonical request signing flow
BBG signs each request using the HTTP method, the request path, timestamp, nonce, and a SHA-256 hash of the raw body. Keep the client secret on your server and never transmit it as a public request header.
- 1. Generate a Unix timestamp in seconds and place it in
x-timestamp. - 2. Generate a random hex nonce and place it in
x-nonce. - 3. Hash the raw request body with SHA-256. For empty bodies, hash the empty string.
- 4. Build the canonical string using the HTTP method, path only (without the query string), timestamp, nonce, and body hash.
- 5. Sign the canonical string with HMAC-SHA256 using your BBG client secret and send the result in
x-signature.
Replay protection and safe retries
Use a unique x-idempotency-key for every create, update, or delete request. Reuse the same key only when retrying the exact same mutation after a network timeout or transport failure.
Recommended pattern
- Use a UUID or a domain-scoped key such as
create-cardholder-user-1029. - Pair idempotency with your own retry policy so duplicate clicks or network retries do not create duplicate records.
- Treat timestamp, nonce, and signature as per-request values, even when reusing an idempotency key for a legitimate retry.
Do not do this
- Do not reuse the same idempotency key for different payloads.
- Do not cache or reuse a nonce across requests.
- Do not send your client secret as a request header; it is only used to calculate
x-signature.
Recommended success and error envelopes
The endpoint sections below use this response shape consistently. Endpoint-specific examples change the contents of data while keeping the wrapper stable.
Sections and endpoints
These sections document the BBG paths, headers, request bodies, and example responses used by BBG partner API flows.