Skip to main content

Counterparty payout lifecycle webhooks

· 2 min read

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:

TopicFires when
CounterpartyPayoutCreatedThe payout was created and submitted for processing
CounterpartyPayoutSentThe payout was sent to the bank — funds have left, but are not yet reconciled
CounterpartyPayoutCompletedThe payout reconciled to a posted bank transaction. Terminal success
CounterpartyPayoutReturnedThe 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.