Appearance
Payments
You do not call a payments API directly today. An order or booking starts the payment for you: Vabu OS asks Payd to open a checkout for M-Pesa or card, and the response carries a checkout_url. The buyer pays there, Payd confirms by callback, and the order completes. This page covers the calls around that flow: starting a checkout, paying a balance, refunds, and the money views your organizers use.
How the pieces fit
| Resource | What it is |
|---|---|
| Checkout | A Payd payment page for one order. Its checkout_url comes back when you create the order. |
| Order | What the buyer is paying for. It stays pending until Payd confirms the money. |
| Payment | One attempt to pay for an order, with a provider and a status. Organizers can list them. |
| Deposit and balance | A ticket can allow pay later. The buyer pays a deposit first and the balance later, in one or more parts. |
| Refund | A request to return money for a paid booking. |
| Settlement | Money moved to the organizer for an event. |
| Payout request | An organizer's request for an early payout on one event. |
| Credits | A prepaid KES balance an organizer spends on message blasts. It is topped up through a Payd checkout. |
The flow for an event order:
- Your app creates the order with
POST /v1/orders. - You send the buyer to
checkout_url. An unpaid order holds its tickets for a short time (10 minutes by default). - The buyer pays with an M-Pesa prompt on their phone or with a card.
- Payd calls Vabu OS back. The order becomes
paid, tickets go out, and Vabu OS firesevents.order.paid(see events). - Your app reads the order with
GET /v1/orders/{id}to show the result. Do not treat the redirect back from Payd as proof of payment.
Payd calls routes that only it uses. Your app never calls them.
What is not available yet
There is no endpoint to report a payment you collected yourself, so a client that runs its own payment stack cannot complete an order that way. There is also no payment simulator in test mode, and test keys cannot start a checkout. Both are on what's coming.
Amounts and phones
Currency defaults to KES. Event and stream orders return amounts in KES, such as 2400.00. Payout requests, settlement totals and merch use integer cents in fields named ..._cents. Credits use amount_kes. Phone numbers go in E.164 format, such as +254712345678.
What you can call today
Start a payment (no sign-in)
| Method | Path | What it does |
|---|---|---|
| POST | /v1/orders | Create an event order. Returns the order and a checkout_url. A free order skips payment. |
| POST | /v1/events/{event}/book | Book one ticket type. Returns the booking and a payment URL. |
| POST | /v1/orders/{code}/pay-balance | Start a checkout for the balance of an order paid by deposit. Send an optional amount in KES, at least 1.00. |
| GET | /v1/orders/{id} | Read an order. A part-paid order shows paid and balance. |
| POST | /v1/plus/orders | Start a checkout to buy a video. Returns a checkout_url. |
| POST | /v1/plus/subscriptions/checkout | Start a checkout for a monthly subscription. |
A deposit order becomes paid, and its tickets go out, only when the balance reaches 0. Each part payment sends the buyer a receipt with the balance still due.
Refunds
| Method | Path | What it does |
|---|---|---|
| POST | /v1/creator/refund/{code} | Ask for a refund on a paid booking, with an optional reason. |
The buyer can ask for everything they paid. Organizer staff can send a smaller amount. A refund must be asked for more than 24 hours before the event starts. The call records a pending refund and cancels the booking. A second request on the same booking is refused.
Organizer: payments, settlements and payouts
| Method | Path | What it does |
|---|---|---|
| GET | /v1/organizer/payments | List payments for your event bookings. Filter by status or provider. |
| GET | /v1/organizer/payments/{payment} | Get one payment with its booking. |
| GET | /v1/organizer/settlements | List settlements with totals settled and unsettled. |
| GET | /v1/organizer/settlements/by-event | Get one row per event: processed, fees, settled and unsettled. |
| GET | /v1/organizer/settlements/{settlement} | Get one settlement. |
| GET | /v1/organizer/events/{eventId}/money-movements | List every money movement for an event, newest first. |
| PUT | /v1/organizer/settings/payout | Set where payouts go: M-Pesa or a bank account. |
| POST | /v1/organizer/payout-requests | Ask for an early payout on an event, with event_id, amount_cents and a reason. |
| GET | /v1/organizer/payout-requests | List payout requests with a count for each status. |
A payout request moves from requested to tenant_approved to processing, then ends as completed, failed or rejected.
Organizer: credits
| Method | Path | What it does |
|---|---|---|
| GET | /v1/organizer/credits/balance | Get the credit balance in KES. |
| POST | /v1/organizer/credits/estimate | Estimate what a message blast will cost. |
| POST | /v1/organizer/credits/top-up | Start a Payd checkout to add credits, from KES 10 to KES 100,000. Send amount_kes and a redirect_url. |
| GET | /v1/organizer/credits/transactions | List top-ups and spending. |
The full parameters for each call are in the API reference.
Calling these endpoints
The start-a-payment routes take only X-Tenant-Code, with no sign-in. The refund route and every /v1/organizer/* route take a signed-in user token (Authorization: Bearer ..., a Vabu ID or Payd ID token) plus X-Tenant-Code, in live mode. Organizer routes also accept an optional X-Organization-Id header. Payments and settlements need the Owner or Admin role. Money movements need an event manager with the finance role, or the Owner. Payout requests and payout settings need the Owner role. Test keys and publishable keys are refused on these routes today. See which credentials each endpoint takes.
Related
- Events and ticketing for the orders that start most payments.
- Commerce for merch orders.
- Integration modes for how your own payments fit in.
- What's coming for reporting your own payments and test-mode payments.