Transfers

A transfer binds one unexpired quote option to a saved fiat account or crypto wallet. Heron tracks the overall transfer and each provider leg through normalized status and progress fields.

Create a transfer

POST /v1/transfers
Idempotency-Key: <stable-key-for-this-logical-transfer>

The required body fields are quoteOptionId and destination:

{
  "quoteOptionId": "00000000-0000-4000-8000-000000000010",
  "destination": {
    "type": "FIAT_ACCOUNT",
    "fiatAccountId": "00000000-0000-4000-8000-000000000020"
  },
  "entityId": "00000000-0000-4000-8000-000000000001",
  "clientReference": "invoice-1042"
}

For a crypto destination, use:

{
  "type": "CRYPTO_WALLET",
  "cryptoWalletId": "00000000-0000-4000-8000-000000000030"
}

clientReference is optional customer context. It does not replace Idempotency-Key.

Idempotency

Generate one idempotency key for each logical transfer. If the create request times out or the connection drops, retry the same request with the same key. A matching replay returns the existing transfer instead of creating another one.

Do not reuse a key for a different quote option, destination, or business instruction. Heron rejects conflicting replays.

Destination binding

The destination must match the selected quote option. Heron stores the confirmed destination version and a snapshot of the instructions with the transfer, so later edits to the saved account or wallet do not redirect an existing payment.

If the saved destination changed after it was quoted, request a new quote before creating the transfer.

Transfer lifecycle

Use the exact status value returned by the API:

Phase	Statuses	Meaning
Setup	PENDING_SETUP	Heron is preparing the execution path.
Funding	READY_TO_FUND, AWAITING_FUNDS	Funding instructions are available or Heron is waiting for funds.
Execution	IN_PROGRESS, IN_REVIEW	The payment is moving or requires review.
Final	COMPLETED, FAILED, RETURNED, REFUNDED, CANCELED	The transfer reached a terminal outcome.

Use the top-level status for the transfer lifecycle and top-level blockingParty to identify whether the next action is with the CUSTOMER, HERON_OPS, PROVIDER, or no party (NONE).

There is no top-level progressStage on a transfer. Current granular progress is reported on each item in legs[*].progressStage. For multi-leg transfers, present the legs in position order and show each leg's stage rather than combining the values into an undocumented transfer-level stage. Entries in timeline[*].progressStage describe historical transitions, not the current aggregate state. If your UI needs one overall indicator, use the transfer's top-level status and blockingParty. Do not derive it from the number of legs or an arbitrary maximum stage.

Fund the transfer

The transfer detail can expose awaitingFundsInstructions. For workflows that need a dedicated funding session, call:

POST /v1/transfers/{transferId}/funding-session

Use the exact amount, destination coordinates, and reference returned for that transfer. When proof of payment is requested, upload a PDF, JPEG, or PNG of up to 10 MB as multipart/form-data. The binary must use the form field name file:

curl --request POST "$HERON_API_URL/v1/transfers/${TRANSFER_ID}/funding-proof" \
  --header "X-API-Key: ${HERON_API_KEY}" \
  --form "file=@./proof-of-payment.pdf"

Use the same HERON_API_URL environment that created the transfer. Let your HTTP client set the multipart Content-Type header so it includes the required boundary; do not send the file as JSON. A successful upload returns 200 with the accepted funding-proof record. Proof submission does not mean the transfer is complete. Continue tracking its status.

Track updates

Use GET /v1/transfers/{transferId} for an on-demand read and customer webhooks for asynchronous updates. Subscribe to both:

• transfer.status_changed for the normalized transfer state
• transfer.leg_status_changed for execution-path detail

Webhook events can be duplicated or arrive out of order. Deduplicate by event id and retrieve the current transfer before applying irreversible side effects.

Reconciliation

Store the Heron transfer id, your clientReference, amounts, currency or asset, current status, and relevant payment references. Use Exports & Reporting for bulk reconciliation and status-history output.