---
title: "List payins for an entity with optional ref-based filtering"
method: GET
path: "/entities/{entityDID}/flow/payins"
tags: ["Flow"]
---

# List payins for an entity with optional ref-based filtering

`GET /entities/{entityDID}/flow/payins`

Retrieves a paginated list of payin transactions for an entity within Flow workflows.
Supports filtering by client references and Flow workflow states. Client references
are automatically converted to database references by adding the 'flow-' prefix.

## Path parameters

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

## Query parameters

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

## Response `200`

List of payins retrieved successfully

- object
  - `data` object[]
    - `@id` string — Unique identifier for the transfer
    - `@type` 'Payin' — 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)