Beneficiaries

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.

Every example on this page is a signed request. $SIGNATURE is computed per request over a canonical string — see Authentication. Bearer tokens are not accepted.

Create a beneficiary

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

string

required

The registered name on the destination account. This is the name checked against the account on the fiat rails.

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.

boolean

required

Whether the account belongs to you. Send false when paying a third party.

string

required

Sepa, Swift or Wallet. The rail fixes what the beneficiary can receive and cannot be changed afterwards.

object

required

The identifiers for that rail. Which subfields are required depends on rail — see below.

`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

string

Your own label for this destination. Handy when one counterparty has several accounts.

string

ISO 3166-1 alpha-2, exactly two characters.

string

The id of a completed payee-verification check, where your flow runs one first.

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.

Response

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

{
  "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"
}

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.

List beneficiaries

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.

A query string is part of the signature. Sort and percent-encode it exactly as the canonical string requires, or the request fails with 401 signature_invalid — the filters themselves are fine.

Read one

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.

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"
  }'

string

required

The beneficiary to rename.

string

required

The new alias.

string

An optional display name.

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.

Delete

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.
`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.

Fiat payouts

Pay a Sepa or Swift beneficiary.

Stablecoin payouts

Pay a Wallet beneficiary.

Get started

Authentication

Core resources

Accept payments

Send money

Webhooks

Feed

Cross-chain bridge

Create a beneficiary

Required fields

`railDetails` per rail

Optional fields

Response

List beneficiaries

Read one

Update

Delete

Errors

Next

Fiat payouts

Stablecoin payouts

​Create a beneficiary

​Required fields

​railDetails per rail

​Optional fields

​Response

​List beneficiaries

​Read one

​Update

​Delete

​Errors

​Next

Fiat payouts

Stablecoin payouts

Create a beneficiary

Required fields

`railDetails` per rail

Optional fields

Response

List beneficiaries

Read one

Update

Delete

Errors

Next