Guides

Sandbox and going live

Build and test the whole flow with a test key, then switch to live by changing one string.

What the sandbox is

A test key (wc_test_…) talks to the same API at the same address, but in a separate world: payments are a mock, no real car is blocked and no money is recorded. It is not a copy of production data: it is the real catalogue, with your test bookings kept apart. Test keys work from the moment you sign up.

Searching, quoting, booking, cancelling and every other call behave exactly as live.
A test booking’s checkoutUrl opens a mock payment page. Opening it pays the booking, like a real customer would.
Events and webhooks are raised as in live, marked livemode: false.
Test bookings never block a real car, and real bookings never block your tests.

Simulating a booking

You do not have to wait for a person to collect a car. Three calls play the customer and the airport:

Call	What it simulates	Booking becomes
`POST /sandbox/bookings/{reference}/pay`	The customer pays	confirmed
`…/activate`	The customer collects the car	active
`…/complete`	The car is returned	completed

They must be done in order and only on test bookings of your own business; a live key gets 403. Each raises the matching event, so this is also how you test your webhook handler end to end.

curl -X POST "https://engine-production-0004.up.railway.app/api/v1/sandbox/bookings/WC-7KQ2M9XA/pay" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"

Simulating a purchase

A car purchase has three stages: the buyer pays a deposit, the balance reaches escrow by bank transfer, and the car is handed over.

Call	What it simulates	Order becomes
`POST /sandbox/orders/{reference}/pay-deposit`	The buyer pays the deposit	reserved
`…/pay-balance`	The balance arrives in escrow	paid
`…/complete`	Car and papers handed over	completed

curl -X POST "https://engine-production-0004.up.railway.app/api/v1/sandbox/orders/WS-4HZ8P2LD/pay-deposit" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"

What it does not do

No money moves, so GET /commissions and GET /balance show nothing for sandbox activity. A booking’s own commission field still shows what you would earn.
Real card behaviour (declines, 3-D Secure) is not simulated. Test those once with a real small booking before launch.
The sandbox does not wait: simulators move a booking at once, whatever its dates.

Going live

A checklist

Tick these before you create your first live booking.

Get approved. We review your business after sign-up. GET /me shows capabilities.liveMode: true when you are done.
Create a live key and put it only in your production environment’s secrets. Keep test keys for development and staging.
Set your webhook to a public https address, store the signing secret, verify every signature, and handle repeats by event id.
Handle every outcome: a booking that is expired or cancelled, a 409 when the car was just taken, a 429.
Send an Idempotency-Key on every create, and log the X-Request-Id of every failed call.
Show your customers the terms from GET /terms before they pay, and the total exactly as quoted.
Make one real booking on a cheap car with your own card, cancel it and check the refund and your webhook.
Watch your earnings: after the first completed rental, GET /balance and GET /commissions show your commission, and our team pays it out to your bank account.