# 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](https://docs.vabu.live/events/index.md)).
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](https://docs.vabu.live/whats-coming.md).

## 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](https://docs.vabu.live/api.md).

## 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](https://docs.vabu.live/concepts/keys-and-scopes.md#which-credentials-each-endpoint-takes).

## Related

- [Events and ticketing](https://docs.vabu.live/products/events.md) for the orders that start most payments.
- [Commerce](https://docs.vabu.live/products/commerce.md) for merch orders.
- [Integration modes](https://docs.vabu.live/concepts/integration-modes.md) for how your own payments fit in.
- [What's coming](https://docs.vabu.live/whats-coming.md) for reporting your own payments and test-mode payments.