---
title: "Create a new payout within Flow workflows (entity-level)"
method: POST
path: "/entities/{entityDID}/flow/payouts"
tags: ["Flow"]
---

# Create a new payout within Flow workflows (entity-level)

`POST /entities/{entityDID}/flow/payouts`

Creates a new payout transaction within a Flow workflow context.
This endpoint initiates a payout workflow where the merchant can receive funds
by selecting a wallet and specifying where they want the funds sent.

## Path parameters

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

## Request body

- object
  - `ref` string, required — Client-provided reference (e.g., payout reference)
  - `currency` string, required — Currency code for the transaction
  - `amount` string, required — Transaction amount
  - `supportedAssets` string[] — Optional list of supported assets for this transaction (CAIP-19)
  - `merchant` object, required — Merchant party information
    - `@id` string — Merchant identifier (mailto:, tel:, or did:web/did:ethr/did:pkh/did:key/did:jwk/did:keri)
    - `name` string — Merchant name
    - `email` string, email — Merchant email address
  - `customer` object, required — Customer party information
    - `@id` string — Customer identifier (mailto:, tel:, or did:web/did:ethr/did:pkh/did:key/did:jwk/did:keri)
    - `name` string — Customer name
    - `email` string, email — Customer email address
  - `memo` string — Optional transaction memo
  - `invoice` object — Invoice details for the transaction
    - `id` string — Invoice number
    - `dueDate` string, date — Invoice due date
    - `lineItems` object[]
      - `description` string — Item description
      - `quantity` number — Item quantity
      - `unitPrice` number — Unit price
      - `lineTotal` number — Total price for this line item
    - `paymentTerms` string — Payment terms

## Response `201`

Payout created successfully

- object
  - `transfer` object
    - `@id` string — Unique identifier for the transfer
    - `@type` 'Payout' — Type of transaction
    - `ref` string — Client reference
    - `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
    - `flowState` string — Current Flow workflow state
    - `paymentLink` string — Payment link for customer interaction
    - `customerDid` string — Customer DID identifier
    - `merchantDid` string — Merchant DID identifier
    - `createdAt` string, date-time — Transaction creation timestamp

## Other responses

- `400` — Invalid request data or validation error
- `401` — Unauthorized - Authentication information is missing or invalid.
- `403` — Forbidden - The server understood the request but refuses to authorize it.
- `404` — Customer not found
- `409` — Payout with this reference already exists
- `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)