Final statuses
Bamboo sends the callback when an order reaches Succeeded, Failed, or PartialFailed.
POST
Notification
Configure the Bamboo callback URLs and optional merchant secret key used for order status notifications.
POST
/api/Integration/v1/notificationThis endpoint configures the Notification URL callback system. For the Svix-based webhook setup guide with event delivery and signature verification, see Webhooks.
Follow this flow to place your first order
View all steps1
Get catalog
Discover available products
2
Get accounts
Retrieve your accounts
3
Place order
Create an order for your customer
4
Get order
Check order status
5
Notification
Receive webhook updates
Notification configures the callback URL Bamboo should call when an order reaches a final status. Setting notificationUrl to an empty value disables the notification feature.
secretKey is optional but recommended. Bamboo includes the value in the callback payload so you can validate the callback on the merchant side before processing it.
This endpoint requires Basic Auth using your API credentials.
Request body
Send the URLs Bamboo should use for production and sandbox callbacks, plus the secret key that Bamboo should echo back to you.
{
"notificationUrl": "https://merchant.example.com/order/notification",
"notificationUrlSandbox": "https://merchant.example.com/sandbox/order/notification",
"secretKey": "merchant-endpoint-verification-secret"
}| Field | Type | Description |
|---|---|---|
notificationUrl | string | Production callback URL for order notifications. Empty disables notifications. |
notificationUrlSandbox | string | Sandbox callback URL for sandbox order notifications. |
secretKey | string | Merchant-side verification secret returned in callback payloads. |
Configuration response and callback payload
The POST endpoint echoes the stored configuration. Bamboo also sends a callback payload when an order reaches a final state.
Configuration response fields
| Field | Type | Description |
|---|---|---|
notificationUrl | string | Configured production callback URL. |
notificationUrlSandbox | string | Configured sandbox callback URL. |
secretKey | string | Configured merchant validation secret. |
Callback payload fields
| Field | Type | Description |
|---|---|---|
orderId | number | Internal Bamboo order identifier. |
status | string | Final order status returned by Bamboo. |
totalCards | number | Total number of cards represented by the callback. |
createdOn | string | Order creation timestamp. |
completedOn | string | Order completion timestamp. |
secretKey | string | Configured secret key used for merchant-side validation. |
requestId | string | Client RequestId that should be used with Get Order. |
Examples
Full request and response examples for this endpoint.
Example request
Use this full request as the primary reference for client-side implementation.
# Generate token: echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64
curl --location 'https://api.bamboocardportal.com/api/Integration/v1/notification' \
--header 'Authorization: Basic YOUR_BASE64_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"notificationUrl": "https://merchant.example.com/order/notification",
"notificationUrlSandbox": "https://merchant.example.com/sandbox/order/notification",
"secretKey": "merchant-endpoint-verification-secret"
}'Example response
Use this sample payload to validate parsing, field mapping, and downstream handling.
200 OK
{
"notificationUrl": "https://yoururl/order/notification",
"notificationUrlSandbox": "https://yoururl/order/notification",
"secretKey": "76d247c4-015d-470e-9ff6-5c1c873d1e0d"
}Callback behavior
Bamboo sends a POST callback only when an order reaches a final state.
Example callback payload
{
"orderId": 12345,
"status": "Succeeded",
"totalCards": 10,
"createdOn": "2024-05-16T04:36:35.3673422",
"completedOn": "2024-05-16T04:36:35.4268366",
"secretKey": "merchant-endpoint-verification-secret",
"requestId": "71ac2817-e51a-438a-bb7b-5ffdda23603c"
}Follow-up action
After receiving the callback, call Get Order with the returned requestId to retrieve the complete order and card details.
Operational notes
Configure your notification URLs carefully so Bamboo can deliver final order events.
Use public HTTPS endpoints
Production callbacks should target a public HTTPS endpoint that Bamboo can reach.
Separate sandbox and production
Keep notificationUrl and notificationUrlSandbox separate when you want different handling for test traffic.
Validate the secret
Check the callback secretKey on your server before you trust or process the payload.
Disable when needed
Set notificationUrl to an empty value when you need Bamboo to stop sending callbacks.
On this page
Try it out
Open the interactive API panel to test this endpoint with your own credentials.