Move an emulated outgoing transfer to its next reported status

POST /sandbox/payouts/{payoutId}/status

Move an emulated outgoing transfer to its next reported status

cURL

curl --request POST \
  --url https://api.hevn.finance/dapi/v1/sandbox/payouts/{payoutId}/status \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

200

{
  "payoutId": "po_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "status": "awaitingSignature",
  "amount": "500.00",
  "currency": "<string>",
  "idempotencyKey": "<string>",
  "transactionId": "txn_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "txHash": "<string>",
  "refundTxHash": "<string>"
}

Authorizations

Authorization · string · header · required

Platform access token from POST /auth/token, carrying the platform audience and the developer_key_id of the registration that minted it. It acts as your own account; name a client you created with X-Hevn-Account: cl_…. Every request re-checks that the registration is still active and that the caller's source IP is inside its allowlist. A token is valid only against the server that issued it, so sandbox tokens are refused in production and production tokens in the sandbox.

Headers

x-api-key · string | null

X-Hevn-Account · string | null

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

Example:

"cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

Idempotency-Key · string | null

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"

Path Parameters

payoutId · string · required

Body

application/json

status · enum<string> · required

Next externally reportable lifecycle status for the emulated transfer.

Available options: awaitingSignature, submitted, settled, failed, refunded

Response

200

application/json

Successful Response

payoutId · string · required

Outgoing-transfer identifier updated by the emulator.

Pattern: ^(?:po_)?[A-Za-z0-9._:\-]{1,216}$

Example:

"po_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

status · enum<string> · required

Current public lifecycle status of the outgoing transfer.

Available options: awaitingSignature, submitted, settled, failed, refunded

amount · string · required

Transfer amount.

Example:

"500.00"

currency · string · required

Transfer currency or digital asset.

idempotencyKey · string · required

Caller-supplied key that binds retries to this update.

transactionId · string | null

Ledger transaction identifier, when created.

Pattern: ^(?:txn_)?[A-Za-z0-9._:\-]{1,216}$

Example:

"txn_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

txHash · string | null

Settlement transaction hash, when applicable.

refundTxHash · string | null

Refund transaction hash, when applicable.