---
title: "Prepare an escrow action and return the payload to sign"
method: POST
path: "/escrow/{escrowId}/actions"
tags: ["escrow"]
---

# Prepare an escrow action and return the payload to sign

`POST /escrow/{escrowId}/actions`

## Request

- The document declares no server URL.
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/hevn-inc/apis/hevn-api/docs/escrow/:escrowId/actions/post.ts> (a function with typed inputs; its response is checked against the schema)

Prepare an escrow action and return the immutable payload to sign. This request does not broadcast the action.

## Path parameters

- `escrowId` string, required

## 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

- EscrowActionRequest
  - `action` 'authorize' | 'charge' | 'capture' | 'void' | 'refund', required
  - `amount` string, nullable: Token amount affected by this action, when required.
  - `feeBps` integer: Variable fee in basis points for charge or capture actions.

## Response `200`

OK

- EscrowActionResultView
  - `deal` EscrowView, required
    - `id` string, required: Stable public identifier for this escrow.
    - `status` 'draft' | 'authorized' | 'charged' | 'partiallyCaptured' | 'captured' | 'voided' | 'reclaimed' | 'partiallyRefunded' | 'refunded', required
    - `availableActions` EscrowAction[], required: Actions permitted by current state and deadlines.
    - `sender` EscrowPartyView, required
      - `clientId` string, required: Account represented by this escrow party.
    - `receiver` EscrowPartyView, required
      - `clientId` string, required: Account represented by this escrow party.
    - `onchainEscrowUrl` string, required: Block explorer URL for the shared escrow contract.
    - `description` string, nullable: Off-chain escrow description.
    - `completionConditions` string, nullable: Off-chain conditions reviewed before capture.
    - `token` string, required: Digital asset held in escrow.
    - `maxAmount` string, required: Maximum token amount that may be authorized.
    - `authorizedAmount` string, required: Token amount currently authorized for capture.
    - `capturableAmount` string, required: Token amount that may currently be captured.
    - `refundableAmount` string, required: Token amount that may currently be refunded.
    - `windows` EscrowWindowsView, required
      - `approveBy` string, date-time, required: UTC deadline for escrow approval.
      - `holdUntil` string, date-time, required: UTC timestamp until which captured funds remain held.
      - `refundableUntil` string, date-time, required: UTC deadline for a refund.
    - `action` EscrowActionView
      - `action` 'approve' | 'authorize' | 'charge' | 'capture' | 'reject' | 'void' | 'reclaim' | 'refund', required
      - `idempotencyKey` string, required: Key that binds retries to the prepared action.
      - `status` 'awaitingSignature' | 'signing' | 'submitted' | 'confirmed' | 'reverted' | 'failed' | 'superseded' | 'dropped', required
      - `amount` string, nullable: Token amount affected by the action.
      - `feeBps` integer, nullable: Variable fee in basis points, when charged.
      - `transactionHash` string, nullable: On-chain transaction hash, when broadcast.
      - `approval` EscrowApprovalView
        - `id` string, uuid, 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.
    - `consistent` boolean, nullable: Whether persisted state matches the latest chain state.
    - `createdAt` string, date-time, required: UTC timestamp when the escrow was created.
    - `updatedAt` string, date-time, required: UTC timestamp when the escrow was last updated.
  - `action` EscrowActionView, required
    - `action` 'approve' | 'authorize' | 'charge' | 'capture' | 'reject' | 'void' | 'reclaim' | 'refund', required
    - `idempotencyKey` string, required: Key that binds retries to the prepared action.
    - `status` 'awaitingSignature' | 'signing' | 'submitted' | 'confirmed' | 'reverted' | 'failed' | 'superseded' | 'dropped', required
    - `amount` string, nullable: Token amount affected by the action.
    - `feeBps` integer, nullable: Variable fee in basis points, when charged.
    - `transactionHash` string, nullable: On-chain transaction hash, when broadcast.
    - `approval` EscrowApprovalView
      - `id` string, uuid, 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.
  - `events` EscrowEventView[]: Observed on-chain events for this action.
    - `name` string, required: Public name of the observed escrow event.
    - `transactionHash` string, required: On-chain transaction hash associated with this event.
    - `blockNumber` integer, required: Blockchain block number in which this event was observed.
    - `amount` string, nullable: Token amount associated with the event.
  - `pollUrl` string, nullable: Relative API URL to poll while processing continues.

## Other responses

- `201`: Successful Response
- `422`: Request validation failed

## Changes

- **2026-11-12** `299a3aa6f521`: 1 warning, 2 info
  - added the new `verification_not_applicable` enum value to the `error/code` response property for the response status `422`
  - removed the `phone_required` enum value from the `error/code` response property for the response status `422`
  - removed the `rail_requirements_unmet` enum value from the `error/code` response property for the response status `422`
- **2026-10-23** `a02795de2d2b`: 1 breaking, 9 warning, 11 info
  - removed the enum value `reclaim` of the request property `action`
  - deleted the `header` request parameter `x-api-key`
  - added the new `client_already_linked` enum value to the `error/code` response property for the response status `422`
  - added the new `kyb_documents_processing` enum value to the `error/code` response property for the response status `422`
  - …17 more
- **2026-10-20** `19eb00e9f258`: 1 info
  - removed the `phone_in_use` enum value from the `error/code` response property for the response status `422`
- **2026-10-20** `bd6c9d69540e`: 1 warning
  - added the new `phone_in_use` enum value to the `error/code` response property for the response status `422`
- **2026-10-20** `19eb00e9f258`: 1 info
  - removed the `document_fields_missing` enum value from the `error/code` response property for the response status `422`

[Operation history](https://skmtc.dev/hevn-inc/apis/hevn-api/changes/escrow/:escrowId/actions/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)