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//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//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//cancel; and 404 PBP-0005 when the batch does not exist or belongs to another organization, with the same body for both.
Authorizations
JWT bearer token issued by the identity provider.
Headers
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.
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.
Path Parameters
Batch identifier (UUID), the batchId the creation answered. A value that is not a UUID is refused with 400 PBP-0001.
"0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"
Body
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.
"Cobrança emitida em duplicidade"
Response
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.