# recipients

Recipients (beneficiaries): requirements per currency/country, CRUD, Confirmation/Verification of Payee, approval (customer tier or operator queue, D-14).

## GET /recipients

operationId: `listRecipients`
Summary: List recipients
API key scopes: `recipients:read`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `cursor` (query), `limit` (query), `sort` (query), `filter` (query), `q` (query), `withTotal` (query)
Responses: 200 `RecipientPage`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `recipients:read`.

**Metadata filter:** `filter[metadata.<key>]=<value>` (exact match; at most 5; AND).

**Batch look-up (P12-T07):** `filter[id]=<id>,<id>,…` (at most 100) returns those rows only, e.g. to resolve names shown next to ids; combine with `limit` ≥ the number of ids.

## POST /recipients

operationId: `createRecipient`
Summary: Add recipient
API key scopes: `recipients:write`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header, required)
Request body: `RecipientCreate`
Responses: 201 `Recipient`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Validates against requirements (IBAN mod-97, BIC, national formats), de-duplicates (`409 duplicate-recipient`), runs CoP/VoP where available and applies the approval mode (D-14): customer approval tier or operator queue. API keys: no step-up; recipients created by API keys always require approval by a human per the customer policy.

**Step-up:** requires a verified step-up challenge for action `recipient.create` within the last 5 minutes (session/bearer only). Otherwise `403` with problem type `step-up-required`; the step-up check runs before body validation.

**Idempotency:** `Idempotency-Key` is required. Replays within 24 h return the original response with `Idempotency-Replayed: true`.

**API key scope:** `recipients:write`.

## GET /recipients/{recipientId}

operationId: `getRecipient`
Summary: Get recipient (full details)
API key scopes: `recipients:read`
Parameters: `recipientId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `If-None-Match` (header)
Responses: 200 `Recipient`, 304, 401 `Problem`, 403 `Problem`, 404 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `recipients:read`.

## PATCH /recipients/{recipientId}

operationId: `updateRecipient`
Summary: Edit recipient
API key scopes: `recipients:write`
Parameters: `recipientId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `If-Match` (header, required)
Request body: `RecipientUpdate`
Responses: 200 `Recipient`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 412 `Problem`, 422 `Problem`, 428 `Problem`, 429 `Problem`, default `Problem`

**Step-up:** requires a verified step-up challenge for action `recipient.update` within the last 5 minutes (session/bearer only). Otherwise `403` with problem type `step-up-required`; the step-up check runs before body validation.

**Concurrency:** `If-Match` with the current `ETag` is required (`428` if absent, `412` if stale).

**API key scope:** `recipients:write`.

## DELETE /recipients/{recipientId}

operationId: `deleteRecipient`
Summary: Delete recipient (soft)
API key scopes: `recipients:write`
Parameters: `recipientId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `If-Match` (header, required)
Responses: 204, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 412 `Problem`, 428 `Problem`, 429 `Problem`, default `Problem`

`409` if scheduled payments or pending payments reference it.

**Concurrency:** `If-Match` with the current `ETag` is required (`428` if absent, `412` if stale).

**API key scope:** `recipients:write`.

## POST /recipients/{recipientId}/verify

operationId: `verifyRecipient`
Summary: Run Confirmation / Verification of Payee
API key scopes: `recipients:write`
Parameters: `recipientId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header)
Responses: 200 `RecipientVerification`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 429 `Problem`, default `Problem`

`422 verification-unavailable` if no routed provider supports CoP/VoP for this currency/country.

**API key scope:** `recipients:write`.

## GET /recipients/requirements

operationId: `getRecipientRequirements`
Summary: Field requirements per currency and country
API key scopes: `recipients:read`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `currency` (query, required), `country` (query, required), `type` (query)
Responses: 200 `RecipientRequirements`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 429 `Problem`, default `Problem`

**API key scope:** `recipients:read`.