---
title: "Create an outgoing transfer"
method: POST
path: "/payouts"
tags: ["transfers"]
---

# Create an outgoing transfer

`POST /payouts`

## Request

- The document declares no server URL.
- Auth: HTTP bearer

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.

## Headers

- `X-Hevn-Account` string, nullable: The client account to act for, as a `cl_…` id. Omit it to act as yourself.
- `Idempotency-Key` string, nullable: 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.

## Request body

- PayoutCreateRequest
  - `contactId` string, required: Saved contact to receive this transfer.
  - `amount` string, nullable: Exact amount to debit in the source currency.
  - `amountTo` string, nullable: Exact amount the contact should receive.
  - `publicKey` string, nullable: Base64 DER SubjectPublicKeyInfo for the registered P-256 developer key. Required unless the account holder signs their own transfers.
  - `paymentReference` string, nullable: Reference or memo delivered with the transfer.
  - `purpose` string, nullable: Business purpose or reason for the transfer.
  - `documentIds` string[]: Supporting document identifiers returned by POST /dapi/v1/documents.
  - `bankId` string, nullable: Optional receiving-account identifier used to select a specific funding route.
  - `sourceAccount` 'USDC' | 'EURC' | 'RD' | 'USDC_ARB' | 'FDIC_USD' | 'FDIC_EUR' | 'KYC_CARDS'

## Response `201`

Successful Response

- PayoutResponse
  - `id` string, required: Stable public identifier for this outgoing transfer.
  - `kind` 'fiat' | 'onchain', required
  - `status` 'awaitingSignature' | 'submitted' | 'settled' | 'failed' | 'refunded', required
  - `idempotencyKey` string, required: Caller-supplied key that makes an identical retry return this result.
  - `quote` PayoutQuoteView
    - `fromAmount` string, required: Amount debited in the source currency.
    - `fromCurrency` string, required: Currency debited by the quote.
    - `sourceAccount` 'USDC' | 'EURC' | 'RD' | 'USDC_ARB' | 'FDIC_USD' | 'FDIC_EUR' | 'KYC_CARDS'
    - `toAmount` string, required: Amount delivered in the destination currency.
    - `toCurrency` string, required: Currency delivered by the quote.
    - `rate` string, nullable: Conversion rate from source to destination amount.
    - `feeAmount` string, nullable: Fee charged in feeCurrency.
    - `feeCurrency` string, nullable: Currency in which the fee is charged.
    - `expiresAt` string, date-time, nullable: UTC timestamp after which the quote is no longer valid.
    - `fromChainId` string, nullable: Network from which the transfer is funded.
    - `toChainId` string, nullable: Network on which the contact receives the transfer.
  - `authorization` 'debit' | 'intent' | 'client'
  - `approval` ApprovalView
    - `id` string, required: Single-use approval identifier.
    - `payload` string, required: Base64 canonical authorization payload to sign with the developer key.
    - `expiresAt` string, date-time, required: UTC timestamp after which this approval is refused.
  - `debit` DebitView
    - `address` string, required: On-chain address receiving the funding debit.
    - `amount` string, required: Human-readable token amount debited.
    - `amountAtomic` string, required: Integer token amount in the asset's smallest unit.
    - `token` string, required: Digital asset debited to fund the transfer.
    - `chainId` integer, required: Numeric network identifier on which the debit executes.
  - `intent` IntentView
    - `digest` string, required: EIP-712 digest of the terms authorized by this approval.
    - `settles` string, required: How the backend settles once the intent is authorized.
  - `contact` PayoutContactView
    - `contactId` string, nullable: Saved contact associated with the transfer.
    - `name` string, nullable: Human-readable contact name.
    - `address` string, nullable: On-chain destination address, when applicable.
    - `chainId` string, nullable: Network on which the contact receives funds.
    - `token` string, nullable: Digital asset the contact receives, when applicable.

## Other responses

- `422`: Request validation failed

## Changes

- **2026-11-12** `299a3aa6f521`: 2 warning, 3 info
  - added the new `FDIC_EUR` enum value to the `quote/anyOf[subschema #1: PayoutQuoteView]/sourceAccount/anyOf[subschema #1: AccountKey]/` response property for the response status `201`
  - added the new `verification_not_applicable` enum value to the `error/code` response property for the response status `422`
  - added the new `FDIC_EUR` enum value to the request property `sourceAccount`
  - removed the `phone_required` enum value from the `error/code` response property for the response status `422`
  - …1 more
- **2026-10-23** `a02795de2d2b`: 13 warning, 11 info
  - deleted the `header` request parameter `x-api-key`
  - added the new `KYC_CARDS` enum value to the `quote/anyOf[subschema #1: PayoutQuoteView]/sourceAccount/anyOf[subschema #1: AccountKey]/` response property for the response status `201`
  - added the new `RD` enum value to the `quote/anyOf[subschema #1: PayoutQuoteView]/sourceAccount/anyOf[subschema #1: AccountKey]/` response property for the response status `201`
  - added the new `USDC_ARB` enum value to the `quote/anyOf[subschema #1: PayoutQuoteView]/sourceAccount/anyOf[subschema #1: AccountKey]/` response property for the response status `201`
  - …20 more
- **2026-10-20** `a1784641d134`: 1 info
  - added the optional property `quote/anyOf[subschema #1: PayoutQuoteView]/sourceAccount` to the response with the `201` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/hevn-inc/apis/hevn-api/changes/payouts/post.md)

---

[API](https://skmtc.dev/hevn-inc/apis/hevn-api.md) - [All operations](https://skmtc.dev/hevn-inc/apis/hevn-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hevn-inc/apis/hevn-api/revisions/299a3aa6f521?raw)