HEhevn-inc
transfers

Create an outgoing transfer

Changed on

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

Request

Headers

X-Hevn-Accountstring nullable

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

Example:cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41
Idempotency-Keystring 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.

Example:po-inv-2026-114

Request body

contactIdstring required

Saved contact to receive this transfer.

amountstring nullable

Exact amount to debit in the source currency.

amountTostring nullable

Exact amount the contact should receive.

publicKeystring nullable

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

paymentReferencestring nullable

Reference or memo delivered with the transfer.

purposestring nullable

Business purpose or reason for the transfer.

documentIdsstring[]

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

bankIdstring nullable

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

sourceAccount'USDC' | 'EURC' | 'RD' | 'USDC_ARB' | 'FDIC_USD' | 'FDIC_EUR' | 'KYC_CARDS'

Example request

{
  "contactId": "ct_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "documentIds": [
    "doc_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"
  ],
  "bankId": "bnk_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"
}

Response

Successful Response

idstring required

Stable public identifier for this outgoing transfer.

kind'fiat' | 'onchain' required
status'awaitingSignature' | 'submitted' | 'settled' | 'failed' | 'refunded' required
idempotencyKeystring required

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

authorization'debit' | 'intent' | 'client'

Example response

{
  "quote": {
    "fromAmount": "500.00",
    "toAmount": "500.00",
    "rate": "500.00",
    "feeAmount": "500.00"
  },
  "debit": {
    "amount": "500.00"
  },
  "contact": {
    "contactId": "ct_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"
  }
}

Changes

  • 299a3aa6f521Revision changes
    • warning

      added the new FDIC_EUR enum value to the /// response property for the response status

    • warning

      added the new verification_not_applicable enum value to the / response property for the response status

    • info

      added the new FDIC_EUR enum value to the request property

    • info

      removed the phone_required enum value from the / response property for the response status

    • info

      removed the rail_requirements_unmet enum value from the / response property for the response status

  • a02795de2d2bRevision changes
    • warning

      deleted the header request parameter x-api-key

    • warning

      added the new KYC_CARDS enum value to the /// response property for the response status

    • warning

      added the new RD enum value to the /// response property for the response status

    • warning

      added the new USDC_ARB enum value to the /// response property for the response status

    • warning

      added the new client enum value to the response property for the response status

    • warning

      added the new client_already_linked enum value to the / response property for the response status

    • warning

      added the new kyb_documents_processing enum value to the / response property for the response status

    • warning

      added the new link_code_expired enum value to the / response property for the response status

    • warning

      added the new link_code_invalid enum value to the / response property for the response status

    • warning

      added the new payout_not_awaiting_signature enum value to the / response property for the response status

    • warning

      added the new redirect_uri_not_allowed enum value to the / response property for the response status

    • warning

      added the new sandbox_amount_limit_exceeded enum value to the / response property for the response status

    • warning

      added the new sandbox_faucet_balance_too_high enum value to the / response property for the response status

    • info

      the request property became optional

    • info

      added the new KYC_CARDS enum value to the request property

    • info

      added the new RD enum value to the request property

    • info

      added the new USDC_ARB enum value to the request property

    • info

      request property list-of-types was widened by adding types null to media type application/json

    • info

      the request property's minLength was decreased from 1 to 0

    • info

      removed the client_policy_not_enabled enum value from the / response property for the response status

    • info

      removed the client_request_conflict enum value from the / response property for the response status

    • info

      removed the email_in_use enum value from the / response property for the response status

    • info

      removed the integrator_inactive enum value from the / response property for the response status

    • info

      removed the name_in_use enum value from the / response property for the response status