Tollbooth API
A small REST API over HTTPS with JSON bodies. Base URL: https://tollbooth.axxes.club/api/v1
Authentication
Create an API key in Dashboard → Developers. Keys belong to one workspace, start with tb_live_ and are shown once. Send them as a bearer token, from your server only.
Authorization: Bearer tb_live_…
Create a checkout
POST /checkout-sessions creates a payment and a hosted Stripe Checkout page. Redirect your customer to checkout_url; they return to your success_url when they've paid. Your workspace must have finished payout setup.
amount integerrequired
Amount in minor units (cents). Minimum 50.
currency string
usd (default), eur, gbp, cad, aud or mxn.
description stringrequired
Shown to the customer at checkout, e.g. “VIP ticket — Friday”.
success_url https URLrequired
Where the customer lands after paying.
cancel_url https URLrequired
Where the customer lands if they back out.
customer_email string
Prefills checkout and appears on the payment.
reference string
Your own order or invoice id, for reconciliation.
metadata object
Up to 20 string key/value pairs, echoed back on the payment.
curl https://tollbooth.axxes.club/api/v1/checkout-sessions \
-H "Authorization: Bearer $TOLLBOOTH_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_1234" \
-d '{"amount": 2500, "currency": "usd", "description": "VIP ticket",
"reference": "order_1234",
"success_url": "https://your.app/thanks", "cancel_url": "https://your.app/cart"}'201 Created
{
"object": "payment",
"id": "9b2c…",
"status": "pending",
"amount": 2500,
"currency": "usd",
"amount_refunded": 0,
"application_fee": 25,
"description": "VIP ticket",
"customer_email": null,
"reference": "order_1234",
"metadata": {},
"checkout_url": "https://checkout.stripe.com/c/pay/…",
"created": 1790000000
}Payments
GET /payments/:id returns one payment. GET /payments lists them newest first; page with limit (1–100) and starting_after (a payment id).
{ "object": "list", "data": [ { "object": "payment", … } ], "has_more": false }Refunds
POST /refunds with payment_id refunds the rest of a payment, or pass amount for a partial refund. Tollbooth's fee on the refunded amount is returned too.
curl https://tollbooth.axxes.club/api/v1/refunds \
-H "Authorization: Bearer $TOLLBOOTH_KEY" \
-H "Content-Type: application/json" \
-d '{"payment_id": "9b2c…", "amount": 1000}'Payment statuses
pending
Checkout created; the customer hasn't paid yet.
succeeded
Paid. Money is on its way to your payout account.
partially_refunded
Some of the amount was refunded.
refunded
Fully refunded.
expired
The checkout page expired unpaid (after 24 hours).
failed
The payment couldn't be completed.
Errors
Errors use standard HTTP status codes and a consistent body.
409 Conflict
{ "error": { "type": "account_not_ready", "message": "This workspace hasn't finished payout setup in Tollbooth yet" } }400 invalid_request_error
Something in the request is missing or malformed.
401 authentication_error
Missing, invalid or revoked API key.
404 resource_missing
No such payment in this workspace.
409 account_not_ready
Finish payout setup before taking payments.
502 api_error
Stripe returned an error; the message says why.
Idempotency
Send an Idempotency-Key header (your order id works well) on create and refund requests. If a network error makes you retry, Stripe won't create a second checkout or refund.