Test booking webhooks and simulate payments in a sandbox

Payments and webhooks are often the hardest parts of a booking integration to test. A deposit needs a card, a reminder needs a day to pass, and a cancellation needs a client who changes their mind. In a Bookatu sandbox you can make each happen when you choose, with no real money.

The test checkout

Where a live business sends a client to pay, a sandbox sends them to a test checkout with three buttons and nothing to type.

• Pay (test) completes the payment, and a booking held for its deposit is confirmed.
• Decline (test) shows a declined card and leaves the checkout open, as a real one does.
• Abandon lets the checkout expire, and a booking held for its deposit is let go.

Every kind of checkout works this way, from deposits to gift cards and invoices, and refunds are simulated too. Memberships can't be bought in test mode yet. Where a booking needs a card saved, the card step has buttons as well: Save test card, and Save a card that will decline.

Make things happen with the simulator

POST /api/v1/{slug}/sandbox/simulate/{event} makes an event happen now to one of the sandbox's own bookings, through the same code as the real thing. It takes a test key with bookings:write.

• deposit.paid pays the booking's open test checkout.
• payment.failed declines the test card, and nothing else changes.
• checkout.expired abandons the checkout.
• booking.client_cancelled is the client's own cancellation, under the business's rules.
• booking.no_show marks a no-show. A fee the policy sets waits for the owner, as at a live business.
• reminders.due sends the booking's reminders as if their time had come.

1curl -X POST https://bookatu.com/api/v1/sbx-ab12cd34/sandbox/simulate/deposit.paid \2  -H "Authorization: Bearer bk_test_YOUR_KEY" \3  -H "Content-Type: application/json" \4  -d '{ "appointmentId": "apt_..." }'

The answer gives the booking as it is now, the ids of the outbox messages the event kept and the webhook events it sent.

Webhooks from a sandbox

Besides its maker's expiry warning, webhooks are the one thing a sandbox sends out. Add an endpoint on the sandbox's Developer API page, at a public https address, and its events reach you signed, as a live business's do. Every payload has a top-level livemode field, false for a sandbox, and the X-Bookatu-Livemode header says the same. So one receiver can take both and never mistake a test booking for a real one.

A sandbox's webhooks keep to smaller limits: up to 5 endpoints, 300 deliveries an hour, 3 retries, and Send test 10 times a minute.

A booking lifecycle in five steps

1. 01
   Add an endpoint

   On the Developer API page, add your receiver and keep its signing secret.

2. 02
   Book the deposit service

   On the sandbox's booking page, book Full colour. Your endpoint gets booking.created, and you reach the test checkout.

3. 03
   Decline, then pay

   Press Decline (test), then Pay (test). The booking is confirmed, and its confirmation is in the outbox.

4. 04
   Bring the reminder forward

   Simulate reminders.due, then read the reminder in the outbox.

5. 05
   Cancel as the client

   Simulate booking.client_cancelled. Your endpoint gets booking.cancelled, and the answer says whether the deposit was kept.

Questions owners ask

Can a test payment ever charge a real card?

No. A sandbox has no real payment account, and its checkout and card step have buttons only. No card number is ever asked for.

Will my live webhook endpoints get test events?

Only if someone adds them to a sandbox. A sandbox's events go to the endpoints registered on that sandbox, each marked livemode: false.

Does the simulator work on my real business?

No. At a live business it answers 404 NOT_A_SANDBOX, and in a sandbox it acts only on that sandbox's own bookings.

Where to start

Add one endpoint, book the deposit service and press Decline (test) before Pay (test). Our developer guide Testing with a sandbox lists every event and refusal. For deposits at a live business, read our post How deposits stop no-shows (and what an empty chair really costs).