Payout lifecycle

Every payout moves through a small state machine. Each transition emits a webhook event named after it, with the payout as GET /payouts/{id} returns it in data.

created ──approve──▶ approved ──send-claim-link, then the claim──▶ requested ──▶ completed
                        │      ──pay────────────────────────────▶      │
                        │                                              └──▶ failed ──pay──▶ requested
                        └──▶ expired

States

The happy path is created → approved → requested → completed. status is an open enum: treat a value you do not know as a fallback case.

Retrying a failed payout

failed is the status that asks the sender to act. A push payout to a counterparty you entered that the provider returns becomes failed as soon as Talentir Operations has reviewed the return. The payout keeps its approval, so no second approval is needed. Correct the counterparty with PATCH /counterparties/{id} and call POST /payouts/{id}/pay again; the payout returns to requested, and payout.completed or another payout.failed follows.

A claimed payout that the provider returns stays requested, and completedAt stays null. Talentir Operations reviews each return first; until the review ends, retry is null. After the review, Talentir emails the recipient a retry link to enter new payment details. Until a new attempt delivers the payout, retry gives url, code, and reason. url is the retry link: show it in your app while it is set, so the recipient finds it outside the email. It is null while the new attempt runs. code has the same values as failureCode, and reason is the same as text. After delivery, retry is null again.

After the retry completes, the payout becomes completed and emits payout.completed. paymentMethod, requestedAt, and completedAt use the successful delivery. The public payout ID and requested amount stay the same.

Notes

• PATCH /payouts/{id} is allowed only while the status is created. A locked payout refuses PATCH altogether.
• DELETE /payouts/{id} is allowed while the status is created, approved, or expired. A requested, completed, or failed payout cannot be deleted (409 PAYOUT_NOT_DELETABLE). The money of a failed payout waits for pay. A deleted payout is gone from the API: every endpoint answers 404 PAYOUT_NOT_FOUND for it, and lists do not include it. The payout.deleted event carries what DELETE returns: { object, id, deleted: true }.
• availableOn delays the claim and the payment, not creation: the payout exists immediately but cannot be claimed or paid before that UTC day.
• A counterparty change (PATCH /counterparties/{id} on the address, payment method, or tax identity) moves every approved payout to that counterparty back to created, because the sender now pays a different destination. Each such payout emits payout.updated.
• From requested on, paymentMethod names the rail and settlement currency, and recipientInvoiceSource says who wrote the document behind recipientInvoiceUrl: self_billing (Talentir issued it in the recipient's name) or recipient_upload (the recipient uploaded their own invoice while claiming).