Balance holds
A hold locks part of the account’s available balance at the banking provider. The money stays in the account but leaves available on GET /balance until the hold is released to another CorpX account or cancelled.
Writes are M2M only, with the holds.write scope. Creating and releasing go through the cashout locks and the transaction PIN, like any outflow. Reads accept read, holds.read or holds.write.
Lifecycle
Partial release does not exist: cancel and create another hold. A hold created by a P2P order (reason: p2p_order) is released or cancelled only by the order and answers 409 hold_managed_by_order on the routes above.
What is locked right now
GET .../holds?status=held lists only the holds that still lock balance at the banking provider: the active ones, plus releasing or cancelling ones whose lock has not been undone yet. Their sum is the heldAmount on GET /balance, so the list explains the locked balance line by line.
Hold origin
A hold created by a P2P order carries source, in the list and in the single read:
deadlineAtis the deadline currently running on the order (nullin dispute or a final status).- On order holds, the destination accounts (seller and intermediation) do not appear, and
lastErrorcomes out as a public code. - A hold created through the API, with no order, has no
source. If reading the order fails, the field is simply omitted.
Asynchronous answers
202on creation: the provider did not confirm the lock. The hold staysunknown_lockuntil reconciled. Do not resend with another key before checking the balance.202on release or cancel: the operation is still running. Read the hold or wait for the webhook.
Webhooks
Error codes are in the Balance holds section of Error Handling.