Claw funds from a reserve into an operator account
Books a balanced transaction debiting the reserve and crediting
operator_account_id. Used when the held-back funds are
forfeited to the operator (e.g. a chargeback lost by the
merchant, an expired escrow window). The reason_code is
persisted in transaction metadata for audit.
Authorizations
Same flow; ledger:write is required for any mutation.
Headers
Required on writes. Stable identifier you choose. The same key
always returns the same transaction, forever. Can also be supplied as
idempotency_key in the request body. Header wins.
Allowed character set: A-Z, a-z, 0-9, _, :, ., -.
Max 255 bytes. Replays of an accepted key return the original
response with header Idempotent-Replayed: true so callers can
tell a replay from a freshly-committed result.
1 - 255^[A-Za-z0-9_:.\-]+$"pi_acme_1234_capture"
Path Parameters
Body
Operator account where clawed funds land (revenue, write-off, etc.).
Amount in minor units to claw back, as a decimal string (recommended) or an integer on write.
^\d+$Free-text audit reason; persisted in transaction metadata.
"chargeback_lost"
Response
Claw booked
Discriminator naming the shape of this resource (e.g. account, transaction).
reserve_op_result "account"
"reserve:merchant_payable:acme:usdc"
Reserve posted balance after this op, in minor units, as a decimal string. Parse with a big-integer or decimal type, never a JS number.
^-?\d+$"500000"
Alias of balance; preserved for symmetry with the decision-doc contract. Decimal string of minor units.
^-?\d+$"500000"