Developers
Build payouts into your own systems
A REST API over JSON for recipients, payouts, batches, events and webhook endpoints. The API runs on the same code as the web app, with the same rules, limits and approvals.
Keys and scopes
An owner or admin creates API keys in the web app, under Organisation, API keys. A key belongs to one organisation, is shown once, stored hashed and can be revoked at any time. Each key carries only the scopes it needs.
| Scope | Allows |
|---|---|
payouts:read | Read payouts, batches and events |
payouts:write | Create payouts and batches, which moves money |
recipients:read | Read saved recipients |
recipients:write | Create recipients |
webhooks:manage | Read webhook endpoints |
Idempotency keys
Every request that creates or moves money needs an Idempotency-Key header, unique per request you mean to
make. Send the same request again with the same key, after a timeout for example, and you get the first response back
with Idempotent-Replayed: true. The payout is never made twice. Keys are kept for 24 hours.
POST /v1/payouts
Authorization: Bearer vsk_<prefix>_<secret>
Idempotency-Key: 6f1c2a8e-3b7d-4e0a-9c51-2d8f4b6a7e10
Content-Type: application/jsonSigned webhooks
Add up to ten endpoints in the web app. Vusha sends payout.submitted, payout.review,
payout.completed, payout.failed, batch.finished and
deposit.credited events to them.
- Each delivery has a
Vusha-Signatureheader with a timestamp and an HMAC-SHA256 of the timestamp and the raw body. - When you rotate the secret, the old one keeps signing alongside the new one for 24 hours.
- Answer with any 2xx within 10 seconds. Anything else is retried, 10 attempts over about 24 hours.
- An endpoint that fails every attempt for 3 days is turned off and the organisation's owners are emailed.
# Header on every delivery
Vusha-Signature: t=1792900000, v1=5b2c...e91f
# To check it
signed = t + "." + raw_body
expected = hex(HMAC_SHA256(endpoint_secret, signed))
accept if expected equals any v1 value
and t is within 5 minutes of your clockwhsec_.Events feed
GET /v1/events lists your organisation's events, oldest first, whether or not an endpoint received them.
Each item is exactly the body a delivery sends. After downtime, pass the id of the last event you processed as
since and carry on from there.
GET /v1/events?since=<last event id>
Authorization: Bearer vsk_<prefix>_<secret>payouts:read scope. Re-read from a little before your last event and skip ids you already have.What the API covers
Recipients, payouts, batches, events and webhook endpoints, under /v1 on the Vusha host. Times are ISO 8601 in UTC.
Organisation
The organisation the key belongs to.
Recipients
Full numbers are accepted but never returned. Responses show a masked destination.
Payouts
Created and confirmed in one call. Above your approval threshold, a payout waits for approvers in the web app.
Batches
Checked in the background and confirmed by approvers in the web app.
Start paying from one balance
Tell us who you pay, in which countries and roughly how often. We reply from [email protected].