> ## Documentation Index
> Fetch the complete documentation index at: https://developer.madhousewallet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipients and account requirements

> Collect the right bank details for each currency and manage payout recipients.

A recipient is the bank account that receives a fiat payout. Because each currency and country requires different details, you first ask the API which fields to collect, then create the recipient.

## Discover required fields

Call [`GET /api/payouts/account-requirements`](/api-reference/recipients/get-account-requirements) with a target `currency` before creating a recipient. The response lists each account type (for example `iban`, `sort_code`, `aba`) and the fields it needs, including validation rules and allowed values.

### Dynamic requirements

Some fields have `refreshRequirementsOnChange: true`. When a user changes one of these, POST the current form state back to [`POST /api/payouts/account-requirements`](/api-reference/recipients/refresh-account-requirements) to get an updated field list.

<Steps>
  <Step title="Get initial fields">
    `GET` with the `currency` and render the returned fields.
  </Step>

  <Step title="React to a change">
    When a `refreshRequirementsOnChange` field changes (for example `legalType` from `PRIVATE` to `BUSINESS`), `POST` the current `type` and `details`.
  </Step>

  <Step title="Re-render and repeat">
    Render the updated fields, then continue until the form is complete.
  </Step>
</Steps>

## Create a recipient

Call [`POST /api/payouts/recipients`](/api-reference/recipients/create-a-recipient) with the `currency`, `type`, `accountHolderName`, and the `details` you collected.

```bash theme={null}
curl -X POST "$MW/api/payouts/recipients" \
  -H "Authorization: Bearer mw_live_<keyId>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "type": "iban",
    "accountHolderName": "Jane Doe",
    "details": { "legalType": "PRIVATE", "iban": "DE89370400440532013000" },
    "wallet": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"
  }'
```

<Note>
  When an account type requires an address, `details.address.country` must be an ISO 3166-1 alpha-2 code (two letters, for example `US`, `GB`, `DE`). Country names and three-letter codes are rejected with `400`.
</Note>

## Email recipients

For EUR payouts you can create an email-based recipient instead of collecting bank details. Pass `type: "wise_email_recipient"` with `currency: "EUR"` and `details: { "email": "recipient@example.com" }`. No requirements lookup is needed, and email recipients carry no transfer fee.

## The `wallet` field

The `wallet` field is conditionally required: it is only needed if your account requires KYC verification. When required, it must be a KYC-verified EVM or SVM address — verify at [kyc.madhousewallet.com](https://kyc.madhousewallet.com). If KYC is not enabled for your account, you may omit it. See [Compliance](/concepts/compliance).

## Update and delete

* [`PATCH /api/payouts/recipients/{id}`](/api-reference/recipients/update-a-recipient) updates `accountHolderName` and/or `details`. An update may issue a new recipient `id` — always use the `id` from the response for later calls.
* [`DELETE /api/payouts/recipients/{id}`](/api-reference/recipients/delete-a-recipient) deactivates a recipient. The `wallet` is passed as a query parameter here, since DELETE carries no body. Any in-progress transfers for the recipient are marked `failed` before deletion; the response's `transfers_failed` count shows how many were cancelled.

<Tip>
  By default a recipient is deleted automatically after a transfer reaches a terminal state. Set `keep_recipient: true` on a transfer to keep reusable recipients you manage yourself.
</Tip>