> ## 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. # Cancel a boleto batch > Cancels the cancelable items of one boleto batch of the X-Organization-Id organization and answers one result per item, in ascending position. Only an item in CREATED status that is registered at the payment provider is canceled, through the same cancellation as POST /v1/boletos/{id}/cancel and with the request's reason; every other item is answered NOT_CANCELABLE with PBP-0103 and is not touched, its status saying why. An item whose cancellation is attempted and refused, or fails, is answered CANCEL_FAILED with the code and message of that refusal, and the other items are still canceled. Canceling only part of a batch is not an error: a batch that is found is answered 200, and each item's status is the one its boleto has after the attempt. A retry carrying the same Idempotency-Key returns the stored answer of the first call, without executing anything, while the service keeps the idempotency record of that call; once the record has expired, the same key is answered from the items' current state, so an item the first call canceled comes back NOT_CANCELABLE with status CANCELED. To cancel one boleto of a batch on its own, use POST /v1/boletos/{id}/cancel. A request refused before any item is touched keeps its own status and code, in this order: 401 or 403 for authentication and authorization; 400 PBP-0012 for a missing or malformed Idempotency-Key; 400 PBP-0001 when batch_id is not a UUID or the body fails schema validation, including reason absent or not a string; 400 PBP-0025 when X-Organization-Id is missing or not a canonical UUID; 400 PBP-0001 when reason is blank once trimmed, longer than 500 characters or carries markup, with the same messages as POST /v1/boletos/{id}/cancel; and 404 PBP-0005 when the batch does not exist or belongs to another organization, with the same body for both. ## OpenAPI ````yaml /es/openapi/v3-current/payments.yaml post /v1/boletos/batches/{batch_id}/cancel openapi: 3.1.0 info: description: >- API for the Lerian Payments interface via BTG. It covers boleto issuance, cancellation, and queries; bill payments (bankslip, utilities, and DARF) and queries; aggregated boleto and payment dashboards; provider connection and outbound webhook configuration; and the provider webhook receiver for settlement events. ERROR BODIES. A failed request arrives as an RFC 9457 problem document on application/problem+json. Branch on the code member. A license refusal carries an LCS code, listed in the License Manager error list. title: Payments — via BTG API version: 1.0.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: [] tags: - description: >- Tenant-level setup: connecting the banking provider and configuring where status notifications are delivered. name: Admin - description: Issuing, querying and cancelling boletos, and retrieving the rendered PDF. name: Boletos - description: >- Aggregated counts, amounts and breakdowns over a period, for boletos and for payments. name: Dashboards - description: >- Paying bankslips, utility bills and DARF tax slips, and querying those payments. name: Payments - description: >- The webhook the payment provider posts settlement events to. Authenticated with a credential agreed with the provider, not with the platform identity used by the rest of this API. name: Settlement paths: /v1/boletos/batches/{batch_id}/cancel: post: tags: - Boletos summary: Cancel a boleto batch description: >- Cancels the cancelable items of one boleto batch of the X-Organization-Id organization and answers one result per item, in ascending position. Only an item in CREATED status that is registered at the payment provider is canceled, through the same cancellation as POST /v1/boletos/{id}/cancel and with the request's reason; every other item is answered NOT_CANCELABLE with PBP-0103 and is not touched, its status saying why. An item whose cancellation is attempted and refused, or fails, is answered CANCEL_FAILED with the code and message of that refusal, and the other items are still canceled. Canceling only part of a batch is not an error: a batch that is found is answered 200, and each item's status is the one its boleto has after the attempt. A retry carrying the same Idempotency-Key returns the stored answer of the first call, without executing anything, while the service keeps the idempotency record of that call; once the record has expired, the same key is answered from the items' current state, so an item the first call canceled comes back NOT_CANCELABLE with status CANCELED. To cancel one boleto of a batch on its own, use POST /v1/boletos/{id}/cancel. A request refused before any item is touched keeps its own status and code, in this order: 401 or 403 for authentication and authorization; 400 PBP-0012 for a missing or malformed Idempotency-Key; 400 PBP-0001 when batch_id is not a UUID or the body fails schema validation, including reason absent or not a string; 400 PBP-0025 when X-Organization-Id is missing or not a canonical UUID; 400 PBP-0001 when reason is blank once trimmed, longer than 500 characters or carries markup, with the same messages as POST /v1/boletos/{id}/cancel; and 404 PBP-0005 when the batch does not exist or belongs to another organization, with the same body for both. operationId: cancelBoletoBatch parameters: - description: >- Organization the batch belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A batch of another organization is answered 404, exactly as one that does not exist. in: header name: X-Organization-Id schema: description: >- Organization the batch belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A batch of another organization is answered 404, exactly as one that does not exist. type: string - description: >- Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012. in: header name: Idempotency-Key required: true schema: description: >- Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012. type: string - description: >- Batch identifier (UUID), the batchId the creation answered. A value that is not a UUID is refused with 400 PBP-0001. in: path name: batch_id required: true schema: description: >- Batch identifier (UUID), the batchId the creation answered. A value that is not a UUID is refused with 400 PBP-0001. examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CancelBoletoBatchRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CancelBoletoBatchResponse' description: >- One result per item of the batch, in ascending position: whether this request canceled the item (CANCELED), could not cancel it (NOT_CANCELABLE) or attempted it and was refused (CANCEL_FAILED), and the status of its boleto after the attempt. Canceling only part of a batch is not an error. '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Bad Request '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again. '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Not Found '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect. '413': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Request Entity Too Large '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] components: schemas: CancelBoletoBatchRequest: additionalProperties: false properties: reason: description: >- Reason for the cancellation, recorded on every item canceled as its cancellationReason. Required: absent, blank once trimmed or longer than 500 characters is refused with 400 PBP-0001, with the same messages as POST /v1/boletos/{id}/cancel. examples: - Cobrança emitida em duplicidade type: string required: - reason type: object CancelBoletoBatchResponse: additionalProperties: false properties: batchId: description: Batch identifier. examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid type: string items: description: One result per item of the batch, in ascending position. items: $ref: '#/components/schemas/CancelBoletoBatchItemResult' type: - array - 'null' required: - batchId - items 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 CancelBoletoBatchItemResult: additionalProperties: false properties: boletoId: description: Identifier of the item's boleto. format: uuid type: string errorCode: description: >- Product code of the outcome. Present with NOT_CANCELABLE (PBP-0103) and with CANCEL_FAILED. examples: - PBP-0103 pattern: ^PBP-[0-9]{4}$ type: string errorMessage: description: Readable reason, present with errorCode. Translate it by errorCode. examples: - boleto is SETTLED and cannot be canceled type: string position: description: Position of the item in the request, from 0. examples: - 0 format: int64 maximum: 24 minimum: 0 type: integer result: description: >- Outcome of the request for the item. CANCELED: this request canceled it. NOT_CANCELABLE: the item could not be canceled, and status says why (SETTLED paid, CANCELED already canceled, INACTIVATED written off, FAILED failed, PENDING not cancelable yet); errorCode is PBP-0103, and it is not an error. CANCEL_FAILED: the cancellation was attempted and refused, with the code and message the single boleto cancellation gives; asking again retries only these and the items that became cancelable. enum: - CANCELED - NOT_CANCELABLE - CANCEL_FAILED examples: - CANCELED type: string status: description: Status of the item's boleto after the attempt. enum: - PENDING - CREATED - SETTLED - CANCELED - INACTIVATED - FAILED examples: - CANCELED type: string required: - position - boletoId - result - status 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.