Skip to navigation

Hold part of the balance

Locks amount of the account’s available balance at the banking provider. The hold stays active until it is released to another CorpX account (POST .../release) or cancelled (POST .../cancel), or until expiresAt.

M2M only (scope holds.write); cashout locks and the transaction PIN apply. Idempotency-Key is required: an exact retry returns the same hold with 200. 202 means the provider did not confirm the lock; CorpX reconciles it and the key is not sent again.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringRequired>=8 characters

Client-generated idempotency token.

X-Acting-DocumentstringOptional

CPF of the human performing the operation. Required on cashout routes when the credential enforces a transaction PIN. On a company P2P profile contact, this CPF is the holder who signs; it is not taken from the body.

X-Transaction-PinstringOptional

Transaction PIN of the operator in X-Acting-Document. Required on cashout routes when the credential enforces a PIN (428 pin_required).

X-Request-TimestampstringRequired

Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).

X-Content-SHA256stringRequired

Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.

X-Request-SignaturestringRequired

Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.

Request

This endpoint expects an object.
amountstringRequired
Decimal BRL amount with up to 2 places.
reasonstringRequired<=64 characters

Machine-readable purpose of the hold.

referencestringRequired<=140 characters

Your reference (order, contract).

expiresAtdatetimeOptional

Optional; the hold is cancelled at this time.

Response

Idempotent retry; returns the existing hold

holdIdstringOptional
Hold identifier.
accountIdstringOptional
Account the balance belongs to.
statusenumOptional
Lifecycle.
amountstringOptional
Held BRL amount.
feestringOptional
Fee withheld on release.
reasonstringOptional
Purpose of the hold.
referencestringOptional
Your reference.
expiresAtdatetime or nullOptional
Automatic cancellation time.
releaseobjectOptional
Destination of the release.
transferIdstringOptional
Internal transfer of the release.
feeTransferIdstringOptional
Internal transfer of the fee.
lastErrorstringOptional
Last provider error.
releasedAtdatetime or nullOptional
Release time.
cancelledAtdatetime or nullOptional
Cancellation time.
createdAtdatetime or nullOptional
Creation time.
updatedAtdatetime or nullOptional
Last change.
sourceobjectOptional

What created the hold. Present only on holds of P2P orders (reason: p2p_order); absent on holds created through the API or when the order could not be read. On these holds the destination accounts (release.toAccountId, release.fee.toAccountId) are omitted and lastError is a public code.

Errors

400
Bad Request Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error