Skip to main content
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 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 to get an updated field list.
1

Get initial fields

GET with the currency and render the returned fields.
2

React to a change

When a refreshRequirementsOnChange field changes (for example legalType from PRIVATE to BUSINESS), POST the current type and details.
3

Re-render and repeat

Render the updated fields, then continue until the form is complete.

​
Create a recipient

Call POST /api/payouts/recipients with the currency, type, accountHolderName, and the details you collected. 
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"
  }'
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.

​
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. If KYC is not enabled for your account, you may omit it. See Compliance.

​
Update and delete

  • PATCH /api/payouts/recipients/{id} 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} 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.
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.