Payouts

A payout sends money from an account to a saved contact, which is a bank account or a wallet address. Save the contact with POST /dapi/v1/contacts, then book the payout with POST /dapi/v1/payouts. Who funds a payout depends on the paying account, and the response names it in authorization (Authorization). These routes take X-Hevn-Account to act for a client (Acting as a client).

Save a contact

curl -s -X POST "$HEVN_API/contacts" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ardenne Fabrication SARL",
       "bank":{"method":"sepa","currency":"EUR",
               "fields":{"iban":"DE89370400440532013000"},
               "holder":{"type":"business","businessName":"Ardenne Fabrication SARL"},
               "bankName":"Example Bank"},
       "address":{"country":"FR","city":"Lyon","streetAddress":"12 Rue Garibaldi","zip":"69006"}}'

contact = client.post("/contacts", {
    "name": "Ardenne Fabrication SARL",
    "bank": {
        "method": "sepa",
        "currency": "EUR",
        "fields": {"iban": "DE89370400440532013000"},
        "holder": {"type": "business", "businessName": "Ardenne Fabrication SARL"},
        "bankName": "Example Bank",
    },
    "address": {"country": "FR", "city": "Lyon", "streetAddress": "12 Rue Garibaldi", "zip": "69006"},
})

const contact = await client.post("/contacts", {
  name: "Ardenne Fabrication SARL",
  bank: {
    method: "sepa",
    currency: "EUR",
    fields: { iban: "DE89370400440532013000" },
    holder: { type: "business", businessName: "Ardenne Fabrication SARL" },
    bankName: "Example Bank",
  },
  address: { country: "FR", city: "Lyon", streetAddress: "12 Rue Garibaldi", zip: "69006" },
});

contact, err := client.Post("/contacts", hevn.Body{
	"name": "Ardenne Fabrication SARL",
	"bank": hevn.Body{
		"method":   "sepa",
		"currency": "EUR",
		"fields":   hevn.Body{"iban": "DE89370400440532013000"},
		"holder":   hevn.Body{"type": "business", "businessName": "Ardenne Fabrication SARL"},
		"bankName": "Example Bank",
	},
	"address": hevn.Body{"country": "FR", "city": "Lyon", "streetAddress": "12 Rue Garibaldi", "zip": "69006"},
})

Response 201, Location: /dapi/v1/contacts/ct_3K9…

{ "id": "ct_3K9…", "name": "Ardenne Fabrication SARL", "isExternal": true,
  "bank": { "method": "sepa", "state": "active", … }, … }

The identifiers each method needs in bank.fields are in Rails. Field rules are on Create a contact. To edit, delete or list contacts, see Update a contact, Delete a contact and List saved contacts.

Check capabilities

Both calls are optional. POST /dapi/v1/payouts applies the same checks.

Retrieve contact channels lists the options that can pay the contact, with limits, fees, the payout fields each one requires and blockers (Contact blockers, Fees).
Create an outgoing transfer quote prices a payment method and amount without a contact.

Book the payout

Call POST /dapi/v1/payouts with the contact and one amount.

curl -s -X POST "$HEVN_API/payouts" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Idempotency-Key: order-A-1187" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"ct_3K9…","amount":"500.00","paymentReference":"INV-2026-114"}'

payout = client.post("/payouts", {
    "contactId": contact["id"],
    "amount": "500.00",
    "paymentReference": "INV-2026-114",
}, idempotency_key="order-A-1187")

const payout = await client.post("/payouts", {
  contactId: contact.id,
  amount: "500.00",
  paymentReference: "INV-2026-114",
}, { idempotencyKey: "order-A-1187" });

payout, err := client.Post("/payouts", hevn.Body{
	"contactId":        contact.Str("id"),
	"amount":           "500.00",
	"paymentReference": "INV-2026-114",
}, hevn.IdempotencyKey("order-A-1187"))

Response 201, Location: /dapi/v1/payouts/po_4c8a…

{
  "id": "po_4c8a…",
  "kind": "fiat",
  "status": "awaitingSignature",
  "idempotencyKey": "order-A-1187",
  "quote": { "fromAmount": "500.00", "fromCurrency": "USD", "sourceAccount": "USDC",
             "toAmount": "459.31", "toCurrency": "EUR",
             "rate": "0.9247", "feeAmount": "1.00", "feeCurrency": "USD",
             "expiresAt": "2026-09-17T10:06:11Z" },
  "authorization": "client",
  "contact": { "contactId": "ct_3K9…", "name": "Ardenne Fabrication SARL" }
}

The body fields and the response are on Create an outgoing transfer. To pay from the fiat balance, see Bank-held balance. The example is a payout for a client linked through HEVN Connect. Other paying accounts return another authorization and the fields that go with it.

Retries

Send an Idempotency-Key with each booking. Key format, replay windows and bookings without a key are in Idempotency-Key. A retry with the same key and terms returns the same po_… and quote. Until the payout is funded, a replay returns what the booking returned: an approval with debit or intent, authorization: "client" again (create a new sign session), or the same transfer with wallet. Once the payout is funded, a replay returns it with none of these. The rules for a changed request are on Create an outgoing transfer. A retry under the same key with another sourceAccount returns 409 idempotency_key_reused. Without a key, a request with another sourceAccount books a new payout.

Reuse the key when you retry. A new key books a second payout.

Authorization

authorization on the response names who funds the payout. Read it before status: each value returns awaitingSignature after booking. The values are defined in Authorization values.

Paying account	`sourceAccount`	`authorization`	Next
Your main wallet	An account key such as `USDC` or `EURC`	`debit`	Sign and confirm (Pay from your own account).
One of your sub accounts	Its `acc_…` id	`debit`	Sign and confirm. `debit.sourceAddress` is the sub account (Sub accounts).
Your balance at the partner bank	`FDIC_USD`	`intent`	Sign and confirm (Bank-held balance).
The wallet of a client linked through HEVN Connect	An account key	`client`	The holder approves in the sign-in window (HEVN Connect).
A client’s external account on Base	Its `acc_…` id	`wallet`	The customer’s wallet sends `transfer` (External wallets).

publicKey is required when your developer key signs. Without it the call returns 422 validation_failed with details.field = "publicKey". It is not used with client or wallet. A payout from the main wallet of a client that is not linked through HEVN Connect returns 403 account_not_controlled. A client created with POST /dapi/v1/clients pays from an external account. With authorization: "client", the holder approves the payout in a sign session of the sign-in window (Approve the payout).

Track it to completion

Read GET /dapi/v1/payouts/{payoutId}. A pollUrl points to this route (polling).

Response 200

{ "id": "po_4c8a…", "kind": "fiat", "status": "settled",
  "quote": { … }, "contact": { … },
  "transactionHash": "0x4f1c…", "transactionId": "txn_9e4…",
  "createdAt": "2026-09-17T10:04:11Z", "settledAt": "2026-09-17T10:04:39Z" }

`status`	Meaning	Next
`awaitingSignature`	Booked and quoted. No money has moved.	Follow `authorization`: sign and confirm, open a `sign` session, or have the wallet send `transfer`.
`submitted`	The funding operation was sent, or the partner bank holds the payout (`attention`).	Poll.
`settled`	The debit landed and the partner bank accepted the payout. Delivery timing is set by the partner bank.	Read the ledger row.
`failed`	The payout did not complete. `failure.code` names the cause, listed on Retrieve an outgoing transfer.	Book again with the same `Idempotency-Key`. After `409 payment_slot_consumed`, use a new key (Retrying a confirm).
`refunded`	The partner bank returned the money to the paying account.	Reconcile.

The fields of the read, attention and transactionId among them, are on Retrieve an outgoing transfer.

Pay from your own account

Book without X-Hevn-Account, or with your cl_… in it, and add publicKey. To pay from a sub account, also send its acc_… id as sourceAccount.

curl -s -X POST "$HEVN_API/payouts" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "Idempotency-Key: treasury-2026-09-17" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"ct_3K9…","amount":"500.00",
       "publicKey":"'"$HEVN_PUBLIC_KEY"'","paymentReference":"INV-2026-114"}'

payout = hevn.post("/payouts", {
    "contactId": contact["id"],
    "amount": "500.00",
    "publicKey": key.public_key,
    "paymentReference": "INV-2026-114",
}, idempotency_key="treasury-2026-09-17")

const payout = await hevn.post("/payouts", {
  contactId: contact.id,
  amount: "500.00",
  publicKey: key.publicKey,
  paymentReference: "INV-2026-114",
}, { idempotencyKey: "treasury-2026-09-17" });

payout, err := api.Post("/payouts", hevn.Body{
	"contactId":        contact.Str("id"),
	"amount":           "500.00",
	"publicKey":        key.PublicKey,
	"paymentReference": "INV-2026-114",
}, hevn.IdempotencyKey("treasury-2026-09-17"))

Response 201, Location: /dapi/v1/payouts/po_7e1b…

{
  "id": "po_7e1b…",
  "kind": "fiat",
  "status": "awaitingSignature",
  "quote": { … },
  "authorization": "debit",
  "approval": { "id": "…", "payload": "eyJ…", "expiresAt": "2026-09-17T10:06:10Z" },
  "debit": { "address": "0x8f3b…", "sourceAddress": "0x2f1c…",
             "amount": "500.00", "amountAtomic": "500000000",
             "token": "USDC", "chainId": 8453, "operation": { … } }
}

Check debit and its operation (Debit contents), sign approval.payload and post the signature to POST /dapi/v1/payouts/{payoutId}/confirm (Signing, Authorize an outgoing transfer). Confirm outcomes are in Retrying a confirm.

Pay a wallet

A wallet contact uses the same payout body, authorization and read. The payout has kind: "onchain".

Save an address as a contact

curl -s -X POST "$HEVN_API/contacts" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ardenne treasury","crypto":{"chain":"base","token":"USDC","address":"0x7c1d…"}}'

contact = client.post("/contacts", {
    "name": "Ardenne treasury",
    "crypto": {"chain": "base", "token": "USDC", "address": "0x7c1d…"},
})

const contact = await client.post("/contacts", {
  name: "Ardenne treasury",
  crypto: { chain: "base", token: "USDC", address: "0x7c1d…" },
});

contact, err := client.Post("/contacts", hevn.Body{
	"name":   "Ardenne treasury",
	"crypto": hevn.Body{"chain": "base", "token": "USDC", "address": "0x7c1d…"},
})

chain takes a chain code.

Contact	Payout	`quote`	`debit.address` with `debit`
USDC or EURC on Base	Direct, no conversion	`fromAmount` equals `toAmount`. `fromChainId` and `toChainId` are `base`. `expiresAt` is 15 minutes after booking. No `rate` or `feeAmount`.	`contact.address`
Another chain or token	Routed across chains	`fromChainId`, `toChainId`, `feeAmount` in `USD`, `expiresAt`. No `rate`.	A one-time address for the route

On a direct payout and on a payout to a HEVN account, amountTo equals amount. An amount with more decimals than the token returns 422 validation_failed.

A routed payout is priced

Routed payout, response 201

{ "id": "po_6d21…", "kind": "onchain", …,
  "quote": { "fromAmount": "1.50", "toAmount": "1.4923", …,
             "feeAmount": "0.0077", "feeCurrency": "USD",
             "expiresAt": "2026-09-17T10:06:11Z",
             "fromChainId": "base", "toChainId": "arb" },
  "contact": { "contactId": "ct_9a…", "name": "Ardenne treasury",
               "address": "0x7c1d…", "chainId": "arb", "token": "USDC" } }

Wallet payout refusal	Cause
`409 payout_not_fundable`	The account has no routing. Use a USDC or EURC contact on Base.
`400`	The address is the paying account’s wallet.
`409 insufficient_funds`	The balance does not cover the amount. Fund the paying account. With `debit`, confirm again.

The ledger row of a settled wallet payout has isIncome: false and type: "crypto", or internal when the address belongs to another HEVN account (Walk the ledger).

Bank-held balance

Send "sourceAccount": "FDIC_USD" to pay from the balance the partner bank holds for the account. The wallet is not debited, and you sign the payout terms.

curl -s -X POST "$HEVN_API/payouts" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "Idempotency-Key: payout-A-1188" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"ct_3K9…","amount":"500.00","sourceAccount":"FDIC_USD","publicKey":"'$HEVN_PUBLIC_KEY'"}'

payout = hevn.post("/payouts", {
    "contactId": "ct_3K9…",
    "amount": "500.00",
    "sourceAccount": "FDIC_USD",
    "publicKey": key.public_key,
}, idempotency_key="payout-A-1188")

const payout = await hevn.post("/payouts", {
  contactId: "ct_3K9…",
  amount: "500.00",
  sourceAccount: "FDIC_USD",
  publicKey: key.publicKey,
}, { idempotencyKey: "payout-A-1188" });

payout, err := api.Post("/payouts", hevn.Body{
	"contactId":     "ct_3K9…",
	"amount":        "500.00",
	"sourceAccount": "FDIC_USD",
	"publicKey":     key.PublicKey,
}, hevn.IdempotencyKey("payout-A-1188"))

Response 201

{ "id": "po_4c8a13d7f2", …,
  "authorization": "intent",
  "quote": { "fromCurrency": "USD", "sourceAccount": "FDIC_USD", … },
  "approval": { … },
  "intent": { "digest": "0x9c1f…", "settles": "message_signature" } }

Check quote and intent, then sign, confirm and poll as for any payout from your account. A client whose holder signs cannot pay from FDIC_USD: the call returns 409 payout_not_fundable with details.reason = "holder_signature_unsupported". The refusals are under sourceAccount on Create an outgoing transfer. To move the balance to your wallet, use Swaps.

When a payout is refused

POST /dapi/v1/payouts returns these codes. A 400 or 422 comes before booking, so the same key works for the corrected request.

`code`	Status	Cause and fix
`invalid_request`	400	The terms are not accepted, for example an amount below the minimum, a direction that cannot be priced, or account details the method does not accept. The reason is in `message`.
`payout_not_fundable`	409	With `details.reason = "holder_signature_unsupported"`, pay from `USDC` or `EURC`. Otherwise book again with a new key on a rail that can be funded.
`provider_unavailable`	503	The partner bank is unavailable. Retry with the same key.
`account_not_controlled`	403	The paying wallet belongs to a client and its holder does not sign through HEVN Connect. See Authorization.
`source_account_unsupported`	409	The `acc_…` account cannot pay this payout. An external account pays USDC from Base. A sub account pays its token on a route that is one transfer to a funding address.
`transfer_policy_denied`	403	The account’s transfer policy refuses this payout. It applies to each paying account, `acc_…` ids included.

The other codes, among them 404 contact_not_found, 409 contact_not_payable and 422 contact_payment_details_invalid, are in Errors. To move a booked payout in the sandbox, see Move a payout.

Start here

Core concepts

Clients

Move money

Ship it

Reference

Changelog

Save a contact

Check capabilities

Book the payout

Retries

Authorization

Track it to completion

Pay from your own account

Pay a wallet

Save an address as a contact

A routed payout is priced

Bank-held balance

When a payout is refused

Next: Swaps