Payouts

A payout moves money from your Olympus Pay balance to your settlement destination.

curl https://merchant.olympuspay.co/api/v1/payouts \
  -X POST \
  -H "Authorization: Bearer $OLYMPUS_API_KEY" \
  -H "Idempotency-Key: payout-2026-09-26-001" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1500.00, "currency": "BWP", "destinationType": "provider_bank" }'

amount is in major units, between 0.01 and 100,000,000.

Destinations#

`destinationType`	Where the money goes
`olympus_account`	Your own Olympus Pay account in that currency
`provider_bank`	Your saved settlement bank account

API payouts go only to your saved account#

For your protection, a payout made with an API key can only go to the settlement account an owner or admin saved in the dashboard. You do not need to send bank details. If you send bankDetails, they must match the saved account, or the request fails with 403. To pay a different account, change the saved account in the dashboard, which requires a signed-in owner or admin.

Requirements#

A live key with scope payouts:create. Sandbox keys get 400.
A verified business and a saved settlement account (for provider_bank).
Enough available balance. Money already set aside for other payouts in progress is not available.

Idempotency#

Always send an Idempotency-Key header (8 to 64 characters). If your request times out and you send it again with the same key, you get the original payout back with "idempotentReplay": true instead of a second payout. See Idempotency.

Approval for large payouts#

A payout at or above a per-currency threshold returns 202 with requiresApproval: true, an approvalId and a payoutId. The funds are set aside straight away. A second person in your business approves it in the dashboard, or rejects it and the funds are released.

Statuses and events#

Status	Meaning
`pending`	Created and funds set aside, not yet sent (or waiting for approval)
`processing`	Sent, awaiting confirmation
`completed`	Landed
`failed`	Failed, funds returned to your balance
`cancelled`	Cancelled with `POST /payouts/{id}/cancel` while `pending`

You receive payout.completed or payout.failed. List payouts with GET /payouts (scope payouts:read).