---
title: "Submit the signature for a prepared escrow action"
method: POST
path: "/escrow/{escrowId}/actions/{idempotencyKey}/confirm"
tags: ["escrow"]
---

# Submit the signature for a prepared escrow action

`POST /escrow/{escrowId}/actions/{idempotencyKey}/confirm`

## Request

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

Submit the signature for the previously prepared escrow action. The path idempotency key must match the prepared action and makes safe retries return the first result.

## Path parameters

- `escrowId` string, required
- `idempotencyKey` string, required

## Headers

- `X-Hevn-Account` string, nullable: The client account to act for, as a `cl_…` id. Omit it to act as yourself.

## Request body

- EscrowConfirmRequest
  - `signature` string, required: Base64 DER ECDSA P-256/SHA-256 signature over the decoded approval payload.
  - `publicKey` string, nullable: Registered P-256 public key; omit when the signature uniquely identifies the key.

## Response `200`

Successful Response

- 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

- `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`: 9 warning, 8 info
  - 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`
  - added the new `link_code_expired` enum value to the `error/code` response property for the response status `422`
  - …13 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/:idempotencyKey/confirm/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)