---
title: "List incoming payouts for an entity (as responder)"
method: GET
path: "/entities/{entityDID}/flow/payouts/incoming"
tags: ["Flow"]
---

# List incoming payouts for an entity (as responder)

`GET /entities/{entityDID}/flow/payouts/incoming`

Retrieves a paginated list of incoming payout transactions where the entity acts as the responder
within Flow workflows. These are payouts initiated by other entities that this entity needs to respond to.
Supports filtering by client references and Flow workflow states.

## Path parameters

- `entityDID` string, did, required — Decentralized Identifier (DID)

## Query parameters

- `refs` union
  - string
  - string[]
- `limit` string
- `offset` string
- `status` union
  - string
  - string[]

## Response `200`

List of incoming payouts retrieved successfully

- object
  - `data` object[]
    - `@id` string — Unique identifier for the transfer
    - `@type` 'Payout' — Type of transaction
    - `ref` string — Client reference (without flow- prefix)
    - `asset` string — Asset identifier for the transaction
    - `amount` string — Transaction amount
    - `status` 'OUTGOING' | 'INCOMING' | 'AWAITING-YOURS' | 'AWAITING-COUNTERPARTY' | 'REJECTED' | 'AUTHORIZED' | 'FLAGGED' | 'SETTLED' | 'FLAGGED-SETTLEMENT' | 'REVERTED' | 'REVERT-AUTHORIZED' | 'REVERT-REJECTED' | 'REVERT-FLAGGED' | 'REVERT-REQUESTED' | 'FROZEN' | 'CLEARED' — The status of a transfer
    - `originator` string — Originator entity information
    - `beneficiary` string — Beneficiary entity information
    - `memo` string — Transaction memo or note
    - `supportedAssets` string[] — List of supported assets for this transaction
    - `flowState` string — Current Flow workflow state
    - `invoice` object — Flow-specific invoice data
    - `paymentLink` string — Payment link for customer interaction
    - `customerDid` string — Customer DID identifier
    - `merchantDid` string — Merchant DID identifier
    - `requiresCustomerApproval` boolean — Whether customer approval is required
    - `createdAt` string, date-time — Transaction creation timestamp
  - `pagination` object
    - `limit` integer — Maximum number of results returned
    - `offset` integer — Number of results skipped
    - `total` integer — Total number of available results

## Other responses

- `400` — Bad Request - The server could not process the request due to a client error.
- `401` — Unauthorized - Authentication information is missing or invalid.
- `403` — Forbidden - The server understood the request but refuses to authorize it.
- `404` — Not Found - The requested resource could not be found.
- `500` — Internal Server Error - An unexpected condition was encountered on the server.

---

[API](https://skmtc.net/notabene/apis/notabene-api.md) · [All operations](https://skmtc.net/notabene/apis/notabene-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notabene/notabene-api/versions/70056745a433/schema)