Payout lifecycle
The states a payout moves through, and which webhook events they emit.
Every payout moves through a small state machine. Each transition emits a webhook event whose payload matches the GET /payout/{id} schema.
States
| Status | Meaning |
|---|---|
created | The payout exists and is pending approval by the sending team. The recipient can already be invited to claim. |
approved | The sending team approved the payout (dashboard, approval session, or preApproved creation). Funds are reserved against the team wallet. |
requested | The recipient claimed the payout and chose a payout method; the transfer has been requested from the payment provider. |
completed | The current delivery attempt completed. |
deleted | The payout was deleted before completion. Terminal. |
expired | The payout expired unclaimed. Terminal. |
The happy path is created → approved → requested → completed.
Notes
- Approval order is not fixed: a recipient can claim before approval — the transfer waits until the payout is both approved and funded.
- A provider rejection after
requesteddoes not complete the payout: it staysrequestedwhile the failure is handled (in the sandbox you can force this with the failure triggers listed in Create a payout). availableOndelays claimability, not creation: the payout exists immediately but can only be claimed from that date.- Deleting (
DELETE /payout/{id}) is only possible before the recipient requests the payout:created,approvedandexpiredpayouts can be deleted,requestedandcompletedpayouts cannot (HTTP 409). - From
requestedon,recipientInvoiceSourcesays who wrote the document behindrecipientInvoice:self-billing(Talentir issued it in the recipient's name),recipient-upload(the recipient uploaded their own invoice while claiming), orpayment-request(the recipient issued it for the payment request that the payout pays).
Retries
When the provider returns a payout, it stays requested until a new attempt delivers it. Talentir Operations reviews each return first; until the review ends, the payout has no retry object. After the review, the payout has a retry object with url, code, and reason. url is the recipient's retry link: show it to the recipient while it is set. It is null while the new attempt runs, or when the sender must pay again. code says why the provider returned the payout: account_closed, account_invalid, name_mismatch, or other. New values can appear. reason is the same as text. After delivery completes, the status becomes completed and retry is omitted.
paidOutAt is omitted until delivery completes. Provider acceptance does not set this field.
The payout keeps its public ID and original requested amount and currency. toMethod, toAsset, and requestedAt describe the current delivery attempt.