Adopt the provider title of an installment
Operational action for an installment the emission conference did not adopt: PENDING, without a provider id, and already attempted. That covers an installment whose title the provider proved to exist, one withheld by a lapsed discount before its resend, and one attempted without either, for instance one whose resends the provider keeps refusing.
- The service reads the title at the provider by the
providerIdgiven and compares itsclientRequestId, derived from the installment, its amount and its due date with the installment’s. - All three match: the provider id is recorded on the installment and the acceptance sweep takes it to
CREATED. The answer is200with the boleto, the body ofGET /v1/boletos/{id}. - Any of them differs, the provider has no title with that id, or the installment is not in that state:
422 PBP-0121, and nothing is written. Thedetailsays which. - Repeating the call with the same
providerIdon the installment it already adopted answers200.
Autorizações
JWT bearer token issued by the identity provider.
Cabeçalhos
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.
Parâmetros de caminho
Identifier of the installment's boleto (UUID).
"01928f6e-7a1b-7c3d-9e4f-5a6b7c8d9e0f"
Corpo
The provider's id of the title.
64"8c2f0b5e-1d3a-4c7e-9f6b-2a4d5e6f7a8b"
Resposta
OK
Whether cancelling this boleto would effect a cancellation at the provider. Always present. Derived from the boleto's state, not from any request field: true only for a CREATED boleto that carries a providerId. An already-canceled boleto reads false even though POST /v1/boletos/{id}/cancel answers it 200 as an idempotent replay.
Issuance form of the boleto: SINGLE for a standalone boleto, INSTALLMENT for an installment of a series, BATCH for an item of a batch, which carries batchId and batchPosition.
Midaz ledger the boleto was written with. Always present.
Midaz account the boleto was issued for: the midazAccountId it was created with. The settlement credit of a settled boleto is posted to this account. Always present.
Midaz organization the boleto was written with. Always present, and always the organization of the X-Organization-Id header.
Batch the boleto was created in, as one of its items. Present only on a boleto of kind BATCH, absent on every other kind.
"0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"
Position of the boleto in its batch, zero-based: the position of its item in the batch request. Present only on a boleto of kind BATCH, absent on every other kind.
0 <= x <= 243
Payments a SETTLED hybrid boleto received after it was settled, by the leg that did not settle it, when the provider attaches them to the boleto. A payment by that leg that the provider does not attach to the boleto reaches the collection account without being listed here. They are never credited: the boleto stays settled by the leg in paidVia. At most one is recorded per leg: a later payment by a leg already listed is not added. Only a hybrid boleto carries them, and the member is absent when there is none.
10Final beneficiary (sacador avalista) of the boleto: the holder of the issuing account, read from that account's registration data at issuance. It is a snapshot: a later change to the registration does not change it. Absent on boletos issued before the final beneficiary was derived.
Bank-side identification of the boleto (nosso numero), as assigned by the provider and printed on the instrument. Read from the barcode and returned in the instrument's form, with leading zeros: the width is set by the connected provider (11 digits for the current one). When the payee supplied ourNumber on issuance, this field still reports the instrument and not the value supplied: if the two differ, the value here is the one printed on the boleto, and the divergence is recorded by the service. Optional: absent for boletos issued before this field existed, and absent while the provider has not produced a valid barcode. Absence means not yet known; the periodic reconciliation fills it in once the provider produces the instrument, with no action needed from the client; it is never sent as an empty string.
"00000000029"
Check digit of ourNumber, computed by the bank and never accepted in a request. Optional: absent whenever the provider did not return it, in which case ourNumber is presented alone, with no trailing hyphen. It is absent in particular when the payee supplied ourNumber: the current provider returns the digit only for numbers it assigned itself. When present, the canonical presentation is {ourNumber}-{ourNumberDigit}.
"3"
Leg by which the boleto was paid: BOLETO for a payment of its barcode or digitable line, PIX for a payment of a hybrid boleto's Pix QR code. Present only on a SETTLED boleto, absent on every other status. A traditional boleto is always paid by BOLETO. Set once, when the boleto settles: a later payment by the other leg does not change it and, when the provider attaches it to the boleto, is listed in excessPayments.
BOLETO, PIX Location of the hybrid boleto's dynamic Pix QR code, as issued. For support and diagnostics: to pay, the payer uses qrCode. Only a HYBRID boleto carries it, and it is served together with qrCode, under the same rule: absent while the boleto is PENDING or FAILED, present once it is CREATED and on every later status; absent on every other type.
"pix.example.com/qr/v2/cobv/5d9a8e91c88c43db942d01a0ad92ffc3"
Identifier of the due-date Pix charge attached to a hybrid boleto. Only a HYBRID boleto carries it, and only once its issuance is confirmed; absent on every other type.
"35dabf21d3b941e8a937409b8749f281"
Identifier the payment provider assigned to this boleto. Quote it when you contact the provider about this boleto.
Pix copy-and-paste code of a HYBRID boleto's Pix charge: the payload behind its QR code, which the payer scans or pastes to pay by Pix. Served only after the provider has registered the boleto, so it is never paid into a boleto whose registration fails: absent while the boleto is PENDING or FAILED, and so from the 201 and the 202 of its creation, which answer it PENDING; present on the read once the boleto is CREATED, and on every later status. Absent on a type without a Pix charge.