Payout API: Create, Fund, and Track Payouts From Your Backend
Four endpoints, an SDK, and a webhook for every status change. The life of a payout from your backend's point of view, and the rules that keep a payout from happening twice.
Four endpoints
| Call | Use it when |
|---|---|
| Create a payout | A recipient asks to withdraw |
| Get a payout | You want funding progress and status for one payout |
| List payouts | You want a filtered page, by email, reference, or status |
| Cancel a payout | You no longer want to fund one that has received nothing |
Every call returns the same payout shape, and so does every webhook, so one parser covers all of it. The full reference is in the Payouts API docs.
Creating a payout
A create call carries what you already know about the withdrawal:
- The recipient’s email, which is how they sign in.
- The payout amount, a whole multiple of your payout step and up to 1,000 USDC.
- The token and chain you will fund it with, and a refund address.
- Your own reference, such as the withdrawal ID, and an optional return URL.
The response gives you the payout ID, a deposit address made for this payout, the exact amount to send, when the quote expires, your fee, and the checkout link. How payout funding works explains the amount line by line.
The Idempotency-Key header is required. Use one key per withdrawal and reuse it on every retry: a timeout or a double submit then returns the same payout instead of a second one.
Handing off the link
Give the recipient the checkout link however suits your product: redirect them, open it in a new tab, or embed it as an iframe in your cashier. You can hand it off before the funds land; the page waits for them. Once the payout is funded, the recipient also gets an email with a link that resumes where they left off. What they see from there is covered in what a wallet-free payout looks like.
Statuses and webhooks
Each payout webhook carries the full payout, including your reference, and a stable event ID to deduplicate on.
| Event | When it fires |
|---|---|
| PAYOUT_ORDER_CREATED | The payout is created |
| PAYOUT_ORDER_PARTIALLY_FUNDED | Some funds arrived, not yet enough; fires again as more arrives |
| PAYOUT_ORDER_FUNDED | The payout is funded and belongs to the recipient |
| PAYOUT_ORDER_MATCHED | A peer starts paying the recipient |
| PAYOUT_ORDER_PARTIALLY_PAID | A buyer paid part of the payout; fires once per payment |
| PAYOUT_ORDER_SETTLED | The payout ended: the recipient was paid in their app or in crypto, or kept the rest of a partly paid one |
| PAYOUT_ORDER_CANCELLED | You cancelled before funding, or the recipient cancelled |
| PAYOUT_ORDER_EXPIRED | The funding deadline passed with nothing received |
Listing and reconciling
The list call filters by the recipient’s exact email, your reference, and status, a page at a time, so a support agent can pull one recipient’s payouts and finance can reconcile a payout run against your own ledger. The merchant dashboard shows the same list with a timeline and webhook log per payout, a CSV export, and Top up and Cancel where they apply.
For where this fits a business, see online casino payouts and creator payouts.
FAQ
Is there an SDK for payouts?
Yes. The Peer Pay SDK has createPayout, getPayout, listPayouts, and cancelPayout, plus typed payout webhook payloads. Call them from your backend only, since every call carries your merchant API key.
How do I stop a retry from paying a recipient twice?
Send an Idempotency-Key header with every create call, one key per withdrawal, reused on retries. The same key with the same body returns the same payout; the same key with a different body is refused.
Can I embed the payout in my own app?
Yes. The checkout link works as a redirect, in a new tab, or inside an iframe in your cashier. Embedded, it posts a success or failure message to your page once.
How do I find every payout for one recipient?
List payouts filtered by the recipient's exact email, your merchant reference, or status, a page at a time. The dashboard has the same filters and a CSV export.
Can I test payouts before going live?
The Peer Pay CLI runs a local simulator of the payout API, including funding, listing, and settlement, so you can exercise your integration and webhooks without moving real funds.