Counterparty payout lifecycle webhooks

Counterparty payout lifecycle webhooks

Payouts now report their progress over webhooks, so you no longer have to poll the payouts API to find out whether funds were delivered. Four new topics:

Topic	Fires when
CounterpartyPayoutCreated	The payout was created and submitted for processing
CounterpartyPayoutSent	The payout was sent to the bank — funds have left, but are not yet reconciled
CounterpartyPayoutCompleted	The payout reconciled to a posted bank transaction. Terminal success
CounterpartyPayoutReturned	The payout ended without delivering funds

Every payload mirrors the payout resource — payoutId (the same id the payouts API returns), counterpartyId, amount in cents, currency, status, description, and effectiveDate.

Treat Sent as provisional

A payout can sit in Sent for a few days depending on the rail, and can still be returned after that. Wait for CounterpartyPayoutCompleted before treating the money as delivered.

Returned covers every failure

CounterpartyPayoutReturned fires for all terminal failures — returned, reversed, cancelled, denied, and failed — so read status rather than inferring the cause from the topic name. Bank returns additionally carry returnCode (for example R01) and returnReason; the other failures leave both null. In all cases the payout amount is available on the counterparty balance again.

Notes

• A duplicate create — the same idempotency key replayed — returns the existing payout and does not fire a second CounterpartyPayoutCreated.
• Payouts already in flight when these topics shipped will not emit Sent, Completed, or Returned. Reconcile those from the payouts API.
• If you subscribe with the "*" wildcard, you are already receiving all four topics — make sure your handler tolerates them.