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

# Beneficiaries

> Register a destination once, then pay it by id.

A beneficiary is a saved destination — a bank account or a wallet address — that you pay by id.
You cannot send money to a raw account number or wallet address, so registering one is the first
step of every [payout](/guides/payouts).

<Note>
  Every example on this page is a signed request. `$SIGNATURE` is computed per request over a
  canonical string — see [Authentication](/guides/authentication). Bearer tokens are not accepted.
</Note>

## Create a beneficiary

```bash theme={null}
curl -X POST https://api.stablemint.net/v1/beneficiaries \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryName": "Acme Oy",
    "type": "Business",
    "isAccountOwner": false,
    "rail": "Sepa",
    "railDetails": { "iban": "FI2112345600000785" },
    "countryCode": "FI",
    "alias": "acme-treasury"
  }'
```

### Required fields

<ParamField body="beneficiaryName" type="string" required>
  The registered name on the destination account. This is the name checked against the account on
  the fiat rails.
</ParamField>

<ParamField body="type" type="string" required>
  `Business` or `Personal`. The API reference marks this optional because older clients omit it —
  **partners must send it**, and a request without it is rejected.
</ParamField>

<ParamField body="isAccountOwner" type="boolean" required>
  Whether the account belongs to you. Send `false` when paying a third party.
</ParamField>

<ParamField body="rail" type="string" required>
  `Sepa`, `Swift` or `Wallet`. The rail fixes what the beneficiary can receive and cannot be
  changed afterwards.
</ParamField>

<ParamField body="railDetails" type="object" required>
  The identifiers for that rail. Which subfields are required depends on `rail` — see below.
</ParamField>

### `railDetails` per rail

| `rail`   | Required             | Also accepted | Notes                                                                                                                  |
| -------- | -------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `Sepa`   | `iban`               | `bic`         | The IBAN is validated and normalised before it is stored.                                                              |
| `Swift`  | `iban` **and** `bic` | —             | Both are required; an absent or malformed BIC is rejected.                                                             |
| `Wallet` | `walletAddress`      | —             | Must be a valid EVM address. It is stored checksummed, so the casing you get back may differ from the casing you sent. |

### Optional fields

<ParamField body="alias" type="string">
  Your own label for this destination. Handy when one counterparty has several accounts.
</ParamField>

<ParamField body="countryCode" type="string">
  ISO 3166-1 alpha-2, exactly two characters.
</ParamField>

<ParamField body="accountVerificationId" type="string">
  The id of a completed payee-verification check, where your flow runs one first.
</ParamField>

<Note>
  The API reference also lists `accountType` and `account` as an alternative to `rail` and
  `railDetails`. That pair is a legacy shape kept working for older clients — use `rail` and
  `railDetails` for anything new.
</Note>

### Response

`201 Created`. The response carries the `id` you pay against, and `accountMasked` alongside the
full `account`.

```json theme={null}
{
  "id": "3f2a9c14-7b5e-4d21-9c6a-8e0f1d2b3c45",
  "beneficiaryName": "Acme Oy",
  "type": "Business",
  "isAccountOwner": false,
  "rail": "Sepa",
  "railDetails": { "iban": "FI2112345600000785", "bic": null },
  "accountMasked": "FI21********0785",
  "alias": "acme-treasury",
  "countryCode": "FI",
  "createdAt": "2026-09-15T09:12:44Z"
}
```

<Warning>
  **The rail decides which payout endpoint accepts it.** A `Sepa` or `Swift` beneficiary is paid
  with `POST /v1/payouts/fiat`; a `Wallet` beneficiary with `POST /v1/payouts/token`. Sending one
  to the wrong endpoint fails with `400`, not `404` — see [Payouts](/guides/payouts).
</Warning>

## List beneficiaries

```bash theme={null}
curl "https://api.stablemint.net/v1/beneficiaries?rail=Wallet&page=1&pageSize=50" \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE"
```

Filter with `rail`, `accountType`, `beneficiaryName`, `alias`, `name`, `isAccountOwner`, `id` and
`createdAt`; page with `page` and `pageSize`; order with `sortBy` and `sortDirection`.

<Warning>
  **A query string is part of the signature.** Sort and percent-encode it exactly as
  [the canonical string](/guides/authentication#the-canonical-string) requires, or the request
  fails with `401` `signature_invalid` — the filters themselves are fine.
</Warning>

## Read one

```bash theme={null}
curl https://api.stablemint.net/v1/beneficiaries/3f2a9c14-7b5e-4d21-9c6a-8e0f1d2b3c45 \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE"
```

A beneficiary belonging to another partner returns `404`, not `403`.

## Update

Only the label is editable. **The id goes in the body, not the path.**

```bash theme={null}
curl -X PUT https://api.stablemint.net/v1/beneficiaries \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "3f2a9c14-7b5e-4d21-9c6a-8e0f1d2b3c45",
    "alias": "acme-treasury-eur",
    "name": "Acme Oy"
  }'
```

<ParamField body="id" type="string" required>
  The beneficiary to rename.
</ParamField>

<ParamField body="alias" type="string" required>
  The new alias.
</ParamField>

<ParamField body="name" type="string">
  An optional display name.
</ParamField>

<Note>
  **Account details are immutable.** There is no way to repoint a beneficiary at a different IBAN
  or wallet address — create a new one and delete the old. That is deliberate: a destination that
  can be edited is a destination that can be edited by mistake.
</Note>

## Delete

```bash theme={null}
curl -X DELETE https://api.stablemint.net/v1/beneficiaries/3f2a9c14-7b5e-4d21-9c6a-8e0f1d2b3c45 \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE"
```

`204 No Content`. Past payouts to the beneficiary are unaffected — deleting it removes the
destination, not the history.

## Errors

| Status | Meaning                                                                                                                                  |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Failed validation — a bad IBAN or BIC, an invalid wallet address, a missing `type`, or neither `rail`+`railDetails` nor the legacy pair. |
| `401`  | Signature, timestamp or nonce failed. See [Authentication](/guides/authentication).                                                      |
| `403`  | Valid signature, but the service account lacks the beneficiary permission.                                                               |
| `404`  | No such beneficiary, or it is not yours.                                                                                                 |
| `409`  | A beneficiary with those account details already exists.                                                                                 |

## Next

<CardGroup cols={2}>
  <Card title="Fiat payouts" icon="building-columns" href="/guides/payouts-fiat">
    Pay a `Sepa` or `Swift` beneficiary.
  </Card>

  <Card title="Stablecoin payouts" icon="coins" href="/guides/payouts-stablecoin">
    Pay a `Wallet` beneficiary.
  </Card>
</CardGroup>