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

# Fiat payouts

> Send money from your balance to a bank account.

A fiat payout sends money from your balance to a bank-rail beneficiary. Read
[Payouts](/guides/payouts) first — idempotency, beneficiaries, error codes and how `status` behaves
are shared with the stablecoin rail and are not repeated here.

<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 payout

```bash theme={null}
curl -X POST https://api.stablemint.net/v1/payouts/fiat \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "invoice-4471",
    "beneficiaryId": "3f2a9c14-7b5e-4d21-9c6a-8e0f1d2b3c45",
    "currency": "EUR",
    "amount": 2500.00,
    "reference": "invoice-4471"
  }'
```

<ParamField body="idempotencyKey" type="string" required>
  Your own unique key for this payout. See [Idempotency](/guides/payouts#idempotency).
</ParamField>

<ParamField body="beneficiaryId" type="string" required>
  A bank-rail beneficiary you own.
</ParamField>

<ParamField body="currency" type="string" required>
  There is no FX on this rail — `currency` and `amount` apply to both sides of the transfer. To pay
  out in a currency you do not hold, [convert first](/guides/fx).
</ParamField>

<ParamField body="amount" type="number" required>
  The amount to send.
</ParamField>

<ParamField body="reference" type="string">
  Optional. Echoed back on the response and surfaced on the transaction. Up to 140 characters,
  which is the scheme ceiling for unstructured remittance information.
</ParamField>

## Response

`201 Created` on first submission, `200 OK` on an idempotent replay.

```json theme={null}
{
  "reference": "SM-2026-0000004471",
  "status": "Pending",
  "amount": 2500.00,
  "currency": "EUR",
  "beneficiaryName": "Acme Oy",
  "beneficiaryAccount": "FI21 1234 5600 0007 85",
  "idempotencyKey": "invoice-4471"
}
```

| Field                | Meaning                                                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `reference`          | The business reference for this payout. Use it to track settlement.                                                       |
| `status`             | Where the payout is now. An open set of strings — see [Payouts](/guides/payouts#status-is-the-outcome-not-the-http-code). |
| `beneficiaryName`    | The registered name on the beneficiary you paid.                                                                          |
| `beneficiaryAccount` | The account the money is going to.                                                                                        |
| `idempotencyKey`     | Echoed back, so a replayed response is self-identifying.                                                                  |

<Warning>
  `201` means accepted for processing. A fiat payout settles on banking-rail timescales, not API
  timescales, and can still fail after acceptance — a closed account, a rejected transfer. Subscribe
  to `transaction.status.changed` rather than treating the response as final.
</Warning>

## Replacing the old withdrawal endpoint

<Note>
  This endpoint replaces the partner-managed withdrawal call, which was published on a service host
  rather than on the public API and took the destination bank details inline on every request.

  The shape is different in one way worth planning for: you no longer send `creditorAccount`,
  `creditorName` and the rest of the bank details with the payout. You register the destination once
  as a beneficiary and then send its `beneficiaryId`. Migrating means creating beneficiaries for
  your existing destinations before you switch the call over.
</Note>