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:

1. Your app creates the order with POST /v1/orders.
2. You send the buyer to checkout_url. An unpaid order holds its tickets for a short time (10 minutes by default).
3. The buyer pays with an M-Pesa prompt on their phone or with a card.
4. Payd calls Vabu OS back. The order becomes paid, tickets go out, and Vabu OS fires events.order.paid (see events).
5. 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.