---
title: "Create a new payin for a customer within Flow workflows"
method: POST
path: "/entities/{entityDID}/flow/customers/{customerDID}/payins"
tags: ["Flow"]
---

# Create a new payin for a customer within Flow workflows

`POST /entities/{entityDID}/flow/customers/{customerDID}/payins`

## Request

- Base URL: `https://api.eu1.notabene.id`
- URL: `https://api.eu1.notabene.id/entities/{entityDID}/flow/customers/{customerDID}/payins`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/notabene/apis/notabene-api/docs/entities/:entityDID/flow/customers/:customerDID/payins/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new payin transaction for a customer within a Flow workflow context.
This endpoint initiates a payment workflow where the customer (merchant) can
receive payments. The payin includes invoice data, supported assets, and
generates a payment link for customer interaction.

## Path parameters

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

## Request body

- object
  - `ref` string, required: Client-provided reference (e.g., invoice number)
  - `currency` string, required: Currency code for the transaction (e.g., USD, EUR)
  - `amount` string, required: Transaction amount
  - `supportedAssets` string[]: List of supported assets for this transaction (CAIP-19 format, or fiat codes)
  - `fallbackSettlementAddresses` string[], required: List of fallback settlement addresses (CAIP-10 or payto://) for the merchant
  - `customer` object, required: Customer party information (the payer/originator)
    - `@id` string, required: 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 (optional, complex invoices require customer approval)
    - `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`

Payin created successfully

- object
  - `transfer` object
    - `@id` string: Unique identifier for the transfer
    - `@type` 'Payin': Type of transaction
    - `ref` string: Client reference
    - `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
    - `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`: Payin with this reference already exists
- `500`: Internal Server Error - An unexpected condition was encountered on the server.

---

[API](https://skmtc.dev/notabene/apis/notabene-api.md) - [All operations](https://skmtc.dev/notabene/apis/notabene-api/llms.txt) - [OpenAPI document](https://skmtc.dev/notabene/apis/notabene-api/revisions/70056745a433?raw)