Create an outgoing transfer

Validate the contact, fix the transfer terms, reserve an idempotent outgoing transfer and return the approval payload to sign. Supplying amount fixes the debit side; amountTo fixes the contact side.

POST /payouts

Create an outgoing transfer

cURL

curl --request POST \
  --url https://api.example.com/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contactId": "ct_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"
}
'

201

{
  "id": "<string>",
  "kind": "fiat",
  "status": "awaitingSignature",
  "idempotencyKey": "<string>",
  "quote": {
    "fromAmount": "500.00",
    "fromCurrency": "<string>",
    "toAmount": "500.00",
    "toCurrency": "<string>",
    "sourceAccount": "USDC",
    "rate": "500.00",
    "feeAmount": "500.00",
    "feeCurrency": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z",
    "fromChainId": "<string>",
    "toChainId": "<string>"
  },
  "authorization": "debit",
  "approval": {
    "id": "<string>",
    "payload": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z"
  },
  "debit": {
    "address": "<string>",
    "amount": "500.00",
    "amountAtomic": "<string>",
    "token": "<string>",
    "chainId": 123
  },
  "intent": {
    "digest": "<string>",
    "settles": "<string>"
  },
  "contact": {
    "contactId": "ct_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
    "name": "<string>",
    "address": "<string>",
    "chainId": "<string>",
    "token": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Hevn-Account · string | null

The client account to act for, as a cl_… id. Omit it to act as yourself.

Example:

"cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

Idempotency-Key · string | null

Your own key for this write, ^[A-Za-z0-9._:-]{1,128}$. A retry with the same key replays the first answer; the same key with a different request is refused.

Example:

"po-inv-2026-114"

Body

application/json

contactId · string · required

Saved contact to receive this transfer.

Pattern: ^(?:ct_)?[A-Za-z0-9._:\-]{1,216}$

Example:

"ct_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

amount · string | null

Exact amount to debit in the source currency.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Example:

"500.00"

amountTo · string | null

Exact amount the contact should receive.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Example:

"500.00"

publicKey · string | null

Base64 DER SubjectPublicKeyInfo for the registered P-256 developer key. Required unless the account holder signs their own transfers.

Required string length: 1 - 512

paymentReference · string | null

Reference or memo delivered with the transfer.

Maximum string length: 140

purpose · string | null

Business purpose or reason for the transfer.

Maximum string length: 64

documentIds · string[]

Supporting document identifiers returned by POST /dapi/v1/documents.

Maximum array length: 10

Pattern: ^(?:doc_)?[A-Za-z0-9._:\-]{1,216}$

bankId · string | null

Optional receiving-account identifier used to select a specific funding route.

Pattern: ^(?:bnk_)?[A-Za-z0-9._:\-]{1,216}$

Example:

"bnk_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

sourceAccount · enum<string> · default: USDC

Account this payout is paid from. USDC and EURC debit the client's wallet; FDIC_USD spends the custodial USD balance and is authorized by an intent signature instead of a debit.

Available options: USDC, EURC, RD, USDC_ARB, FDIC_USD, KYC_CARDS

Response

201

application/json

Successful Response

id · string · required

Stable public identifier for this outgoing transfer.

kind · enum<string> · required

Whether the contact is account-based or on-chain.

Available options: fiat, onchain

status · enum<string> · required

Current public lifecycle status of the transfer.

Available options: awaitingSignature, submitted, settled, failed, refunded

idempotencyKey · string · required

Caller-supplied key that makes an identical retry return this result.

quote · PayoutQuoteView · object | null

Price, fee and conversion terms fixed for this transfer.

Show child attributes

authorization · enum<string> · default: debit

Whether the approval authorizes a balance debit or a signature over the transfer's terms, or whether the account holder signs it themselves in the HEVN sign-in window.

Available options: debit, intent, client

approval · ApprovalView · object | null

Authorization to sign before execution.

Show child attributes

debit · DebitView · object | null

Exact on-chain debit used to fund this transfer.

Show child attributes

intent · IntentView · object | null

Terms authorized by the signature, when this transfer is not funded by a debit.

Show child attributes

contact · PayoutContactView · object | null

Contact snapshot fixed at creation.

Show child attributes