---
title: "CounterpartyPayoutReturned"
method: POST
path: "counterpartyPayoutReturned"
tags: ["Webhook Topics"]
---

# CounterpartyPayoutReturned

`POST counterpartyPayoutReturned` (webhook)

Fired when a payout ends without delivering funds. This covers every terminal failure — returned, reversed, cancelled, denied, and failed — so read **status** to see which occurred rather than relying on the topic name.

**returnCode** and **returnReason** are populated when the receiving bank returned the payment (for example `R01`, insufficient funds) and are null for the other failures. See [ACH Return Codes](/docs/webhooks/ach-return-codes) for every code. The payout amount is available on the counterparty balance again.

The included payload mirrors the payout resource — **payoutId**, **counterpartyId**, **amount** (in cents), **currency**, **status**, **description**, and **effectiveDate** — so you can act on the event without re-reading the payouts API.

## Payload

- object
  - `id` string, uuid, required: Unique identifier for the object.
  - `type` 'WebhookEvent', required
  - `attributes` object, required
    - `id` string, uuid, required: The webhook event ID
    - `topic` string, required: The webhook topic/event type
    - `clientId` string, uuid, required: The client ID associated with this webhook event
    - `userId` string, uuid: The user ID associated with this webhook event (if applicable)
    - `walletId` string, uuid: The wallet ID associated with this webhook event (if applicable)
    - `updatedAt` string, date-time, required
    - `createdAt` string, date-time, required
  - `relationships` object, required
    - `event` object
      - `data` object, required: The related event resource (PaymentIntent, Payment, Refund, Capture, or ApplicationEvent)
        - `id` string, uuid, required
        - `type` string, required
  - `included` WebhookCounterpartyPayoutReturned[], required
    - `id` string, uuid, required
    - `type` 'CounterpartyPayoutReturned', required
    - `attributes` object, required
      - `payoutId` string, required: The payout id, identical to the one the payouts API returns
      - `counterpartyId` string, uuid, required: The counterparty being paid out
      - `merchantId` string, uuid, required: The merchant that owns the counterparty
      - `amount` integer, required: The payout amount, represented in the smallest currency unit (e.g., cents for USD).
      - `currency` string, required: ISO 4217 currency code of the payout
      - `status` 'Approved' | 'Cancelled' | 'Completed' | 'Denied' | 'Failed' | 'NeedsApproval' | 'Pending' | 'Processing' | 'Returned' | 'Reversed' | 'Sent', required: The payout status at the time the event fired. This is the same status the payouts API reports, so a webhook and a subsequent read always agree.
      - `description` string, nullable, required: Description recorded on the payout
      - `effectiveDate` string, required: The date the payout is scheduled to settle, as `YYYY-MM-DD`
      - `createdAt` string, required: ISO 8601 timestamp
      - `updatedAt` string, required: ISO 8601 timestamp
      - `returnCode` string, nullable, required: Bank return code when the payout was returned by the receiving bank (for example `R01`). Null for the other terminal failures, which carry no bank return. See [ACH Return Codes](/docs/webhooks/ach-return-codes).
      - `returnReason` string, nullable, required: Human-readable reason for the return, when the bank supplied one
      - `reference` string, nullable
      - `email` string, email, nullable
      - `fullName` string, nullable
      - `phoneNumber` string, nullable
      - `error` string, nullable
      - `walletId` string, uuid, nullable
      - `billingAddress` object, nullable

## Acknowledgement `200`

Return a 200 status to indicate that the data was received successfully

---

[API](https://skmtc.dev/byaccrue/apis/accrue-merchant-api.md) - [All operations](https://skmtc.dev/byaccrue/apis/accrue-merchant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/byaccrue/apis/accrue-merchant-api/revisions/3e2d97ef2e6e?raw)