This is a dev/local preview of the public API 0.88.0 contract, available only to enabled partners. Funding, commission credits and withdrawals are not yet available. Sandbox and production remain disabled until launch.
Check the balance
Use your tenant-bound API key to read your partner’s balance:GET /v1/balance returns:
The dev stub’s initial balance is configured by the operator. A partner without an initial credit has no funds to spend. Reading a balance does not reserve it for a booking; another payment can spend it before you submit.
Pay for a booking
Prepare a trip with its selected items and travelers, then callPOST /v1/checkout with its trip_id. See Trips and checkout.
Use the returned quote_id. Submit a balance payment only when checkout’s accepted_payment_types includes type: "balance". Discovery lists it only when the feature is enabled, your partner is entitled and the quote currency matches the balance currency. Read discovery on each checkout; do not cache it.
Send the typed payment to the public API with an Idempotency-Key:
payment object needs only type: "balance"; no card or shared payment token is required. A posted debit produces payment_status: "authorized", then fulfillment proceeds as for other payments. Authorization alone does not mean the booking is confirmed.
The answer is the same payment outcome as for every typed payment: read it and follow its recovery.action as described in Payment outcomes and retries, including how to retry with the same Idempotency-Key after a timeout. Read GET /v1/trip/{trip_id} for the booking status. A competing submission after an attempt has already been debited returns 409.
Insufficient balance
INSUFFICIENT_BALANCE (HTTP 403) means the available balance cannot cover the quote. The payment is refused before acceptance, with recovery.action: "stop".
Fund the balance or pay another way using an available checkout payment method. Do not retry with a new key to bypass this refusal. Funding is not yet available in this slice; on dev, the operator configures the stub’s initial credit. Replaying the same key returns the original result.
See Payment outcome codes for the other codes a balance payment can return.
Cancellations and refunds
When a balance-paid booking is cancelled and refunded, the refund credits the balance back. It does not issue a Stripe card refund. Follow the booking’s cancellation and refund status, then checkGET /v1/balance to see the restored funds. A cancellation request alone is not proof that the refund has completed.