> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Create a cautionary block > Places a cautionary block (MED 2.0) on the funds of a Pix that your institution received. Pix Lerian creates a pending ledger transaction that moves the funds from the available balance of the credited account to the blocking account. The amount held is the smaller of the requested amount and the available balance: `effective_amount` is what was held, and it can be lower than `requested_amount`. The blocking account of your institution must be configured. An inbound Pix transfer with this `end_to_end_id` must be completed, with available balance on the credited account, or have its ledger credit parked. For a Pix whose credit is parked, the lock holds at once (`PENDING`) when the ledger already lists that credit. Otherwise the lock is stored as `AWAITING_CREDIT`: nothing is held yet, and the credit of the Pix holds the funds before it completes the transfer. `request_ref` identifies the creation. A replay with the same payload returns the existing lock with `201`; the same `request_ref` with another payload is refused with `409` (`PIX-0012`). Another hold on the same transaction needs another `request_ref`. A retry after a failed create (`502`) reuses the amount that the failed attempt computed, so a hold that the attempt placed becomes this lock. A retry whose earlier hold no longer stands is refused with `422` (`PIX-0013`). Next, return the funds to the payer with [Settle a cautionary block](/es/reference/interfaces/pix-lerian/spi/settle-a-cautionary-block) or [Settle every cautionary block of a Pix](/es/reference/interfaces/pix-lerian/spi/settle-every-cautionary-block-of-a-pix), or give them back to the account holder with [Release a cautionary block](/es/reference/interfaces/pix-lerian/spi/release-a-cautionary-block-to-the-account-holder). ## OpenAPI ````yaml /es/openapi/v3-current/pix-lerian-spi.yaml post /balance-locks openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: Public API for outbound Pix transfers, refunds, and scheduled payments. license: name: Lerian Studio General License title: Pix Lerian — Payments version: 1.2.0 servers: - url: https://api.example.com/spi/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Create, list, and retrieve Pix refunds. name: Refunds - name: Scheduled Payments description: Register, list, retrieve, and cancel scheduled Pix payments. - description: Initiate, process, list, and retrieve outbound Pix transfers. name: Transfers - description: >- Register, list, retrieve, and cancel recurring series of scheduled Pix payments. name: Scheduled Payment Recurrences - description: >- Hold the funds of a received Pix in a cautionary block (MED 2.0), return them to the payer, or give them back to the account holder. name: Balance Locks paths: /balance-locks: post: tags: - Balance Locks summary: Create a cautionary block description: >- Places a cautionary block (MED 2.0) on the funds of a Pix that your institution received. Pix Lerian creates a pending ledger transaction that moves the funds from the available balance of the credited account to the blocking account. The amount held is the smaller of the requested amount and the available balance: `effective_amount` is what was held, and it can be lower than `requested_amount`. The blocking account of your institution must be configured. An inbound Pix transfer with this `end_to_end_id` must be completed, with available balance on the credited account, or have its ledger credit parked. For a Pix whose credit is parked, the lock holds at once (`PENDING`) when the ledger already lists that credit. Otherwise the lock is stored as `AWAITING_CREDIT`: nothing is held yet, and the credit of the Pix holds the funds before it completes the transfer. `request_ref` identifies the creation. A replay with the same payload returns the existing lock with `201`; the same `request_ref` with another payload is refused with `409` (`PIX-0012`). Another hold on the same transaction needs another `request_ref`. A retry after a failed create (`502`) reuses the amount that the failed attempt computed, so a hold that the attempt placed becomes this lock. A retry whose earlier hold no longer stands is refused with `422` (`PIX-0013`). Next, return the funds to the payer with [Settle a cautionary block](/es/reference/interfaces/pix-lerian/spi/settle-a-cautionary-block) or [Settle every cautionary block of a Pix](/es/reference/interfaces/pix-lerian/spi/settle-every-cautionary-block-of-a-pix), or give them back to the account holder with [Release a cautionary block](/es/reference/interfaces/pix-lerian/spi/release-a-cautionary-block-to-the-account-holder). operationId: createBalanceLock parameters: - description: >- REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string requestBody: content: application/json: examples: hold: summary: Hold the funds of a suspicious received Pix value: request_ref: med-2026-000123-hold-1 external_ref: med-2026-000123 origin_system: med-infraction end_to_end_id: E12345678202610271032k7Qm2Xp9Ld4 amount: '150.75' asset: BRL schema: $ref: '#/components/schemas/CreateBalanceLockBody' required: true responses: '201': content: application/json: example: lock_id: 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 midaz_tx_id: 01a17cf3-133d-7a52-8e19-0c4b6d2f7a91 status: PENDING requested_amount: '150.75' effective_amount: '100.26' created_at: '2026-10-27T10:41:07Z' schema: $ref: '#/components/schemas/CreateBalanceLockResponse' description: The hold, created now or replayed by request_ref. '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: >- The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0003 title: Bad Request status: 400 detail: >- Your request contains one or more fields with an invalid data type. code: PIX-0003 schema: $ref: '#/components/schemas/Detail' description: >- Missing or invalid body fields, or a body that is not valid JSON (PIX-0002, PIX-0003, PIX-0010). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0010) answer in the legacy {code,title,message} envelope too. '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: >- The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: '#/components/schemas/Detail' description: request_ref was already used with a different payload (PIX-0012). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: >- The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json. '415': content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: >- The request body must be sent with Content-Type: application/json. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0013 title: Unprocessable Entity status: 422 detail: >- The operation could not be processed due to a business rule violation. code: PIX-0013 schema: $ref: '#/components/schemas/Detail' description: >- No INBOUND transfer matches end_to_end_id that is completed or has its ledger credit parked, the locks waiting for that parked credit already sum to its amount, the credited account has no available balance to hold, the ledger refused the hold for another business reason, or the hold an earlier attempt placed under this request_ref no longer stands (PIX-0013); the ledger account is blocked or has no balance for the asset (PIX-0328, PIX-0329); the participant's blocking account is not configured (PIX-0650); an account has no ledger alias (PIX-0655). '500': content: application/json: example: code: PIX-0000 title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: >- The server could not complete the request. Please try again later. code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Unexpected server error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0652 title: Bad Gateway status: 502 detail: >- The server could not complete the request. Please try again later. code: PIX-0652 schema: $ref: '#/components/schemas/Detail' description: >- The ledger call failed, another write moved the balance while the ledger placed the hold, the create could not tell whether a hold already stands under request_ref, or storing an AWAITING_CREDIT lock failed: retry with the same request_ref (PIX-0652). With a detail naming overrides.allowFeeSkip, the ledger that holds the blocking account does not enable it, so nothing was held: retry with the same request_ref once it is enabled. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: CreateBalanceLockBody: additionalProperties: false properties: amount: description: Requested hold amount examples: - '150.75' type: string asset: description: Asset code (only BRL supported) examples: - BRL type: string end_to_end_id: description: Related Pix transaction end-to-end id examples: - E12345678202610271032k7Qm2Xp9Ld4 type: string external_ref: description: Grouping reference (not unique) examples: - med-2026-000123 type: string origin_system: description: Calling system/flow discriminator examples: - med-infraction type: string request_ref: description: Idempotency key for this creation (unique per tenant) examples: - med-2026-000123-hold-1 type: string required: - request_ref - external_ref - origin_system - end_to_end_id - amount - asset type: object CreateBalanceLockResponse: additionalProperties: false properties: created_at: examples: - '2026-10-27T10:41:07Z' format: date-time type: string effective_amount: examples: - '100.26' type: string lock_id: examples: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 type: string midaz_tx_id: description: The ledger hold; empty while AWAITING_CREDIT examples: - 01a17cf3-133d-7a52-8e19-0c4b6d2f7a91 type: string requested_amount: examples: - '150.75' type: string status: description: >- PENDING, or AWAITING_CREDIT while the Pix's ledger credit is parked and nothing is held yet examples: - PENDING type: string required: - lock_id - midaz_tx_id - status - requested_amount - effective_amount - created_at type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string fields: additionalProperties: type: string description: Per-field detail, keyed by the field or header the refusal names type: object headers: additionalProperties: type: string description: Per-header detail, keyed by the request header the refusal names type: object required: - code - title - message type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.