Developers

Sandbox

Test keys let you build and rehearse the full booking flow against the real catalogue without charging anyone or touching real capacity.

Updated 2026-10-20

What do test keys do?

A test key (pk_test_...) runs exactly the same code as a live key. Catalogue and availability are real. Only writes are different: a booking made with a test key is quarantined.

A sandbox booking...	Detail
Has its own reference	Numbered `TST-<n>`, with `sandbox: true` in the response.
Is never charged	No money moves.
Holds no capacity	Capacity checks still answer (quotes and bookings can still be UNAVAILABLE), but nothing is taken from real inventory.
Earns nothing	No commission and no statement line.
Ignores the credit limit	Test keys are never refused by the credit limit, so `CREDIT_LIMIT` cannot be rehearsed on a test key.
Is invisible to staff	It does not appear in the operator’s own tools.
Emails only you	Sent to your notification address only, with a `[SANDBOX]` subject prefix. Never to the customer or drivers; no SMS.
Has no waiver link	Waiver `url` values are `null`.
Disappears after 7 days	Sandbox bookings are deleted 7 days after they are created.

Reads and cancels work on sandbox bookings. A test key only ever sees sandbox bookings and a live key only live ones; idempotency keys are scoped per mode, so the same key in test and live never collides.

How do I test failures on purpose?

Add a tag to the local part of the customer email, such as ann+soldout@example.com. Tags are deterministic and can be combined.

Tag	Result
`+soldout`	`409 UNAVAILABLE` (reason `sold_out`)
`+duplicate`	`409 DUPLICATE`
`+declined`	The sandbox pay page always declines.
`+slow`	The booking call waits 3 seconds before answering.

jsonCombined tags

"customer": {
  "name": "Ann Lee",
  "email": "ann+soldout+slow@example.com"
}

Important

Tags only work on test keys. On a live key a +tag is just part of the customer's email address.

How do I try the pay-link flow?

If your account settles by pay link, a test-key booking comes back awaiting_payment with a payLinkUrl to a sandbox pay page. Open it and choose Simulate successful payment or Simulate declined card to see how the booking changes: a paid sandbox booking becomes confirmed (paymentStatus: captured); a decline shows paymentStatus: failed. No real payment form is involved and no card is ever entered.

A decline can be retried.
Paid, cancelled and expired are final.
holdExpiresAt shows when the hold would lapse (holdMinutes from GET /me).

jsonSandbox booking awaiting payment

{
  "ok": true,
  "data": {
    "bookingRef": "TST-12",
    "idempotencyKey": "order-48214",
    "sandbox": true,
    "status": "awaiting_payment",
    "paymentStatus": "pending",
    "settlementMode": "pay_link",
    "date": "2026-11-14",
    "time": "10:00",
    "payLinkUrl": "https://booking.example.com/pay/sandbox/<token>",
    "holdExpiresAt": "2026-10-20T18:12:10.000Z",
    "waivers": [
      { "driverIndex": 0, "driver": "Ann Lee", "status": "pending", "url": null }
    ],
    "replayed": false,
    "...": "remaining fields as in a live booking"
  },
  "requestId": "req_7d0c25"
}

Note

The sandbox pay page stands in for our secure hosted payment page, which live keys use. A live pay-link booking is also awaiting_payment with a payLinkUrl and a holdExpiresAt, but the seats really are held until then and the customer pays on the real page. See pay-link bookings. Webhooks are on the way Coming soon; for now, poll GET /bookings/{ref}.

How do I go live?

Run your whole flow with a test key: catalogue, availability, quote, book, read, cancel, and each failure tag.
Confirm your settlement, communication and pricing modes in GET /me are what you expect.
Pass the sandbox certification checklist with your test key.
Ask the operator to switch on live access for your account. Until they do, pk_live_ keys answer SANDBOX_ONLY.
Store the live key on your server only, and swap it in. GET /me now reports mode: "live"; bookings get DR... references, hold real capacity and appear on your monthly statement.
Your first live booking is real. Start with a cancelable test of your own.

Next: Errors →