Issue a single boleto
Issues a boleto through the banking provider. The supported boleto types are TRADITIONAL and HYBRID; a request with type QR_CODE is refused with 422 PBP-0006. A HYBRID boleto can also be paid by Pix: it is issued together with a due-date Pix charge, and once its issuance is confirmed the answer carries that charge’s identifier in pixTxId. The Pix code the payer scans, in qrCode, and its location, in pixLocation, are served only after the provider has registered the boleto, so that code is never paid into a boleto whose registration fails: both are absent while the boleto is PENDING, as this operation answers it, or FAILED, and GET /v1/boletos/ carries them once it is CREATED and on every later status. The charge is registered to the tenant’s Pix receiver, configured at POST /v1/admin/pix-config: when that configuration is incomplete, when the holder of the issuing account cannot be the Pix receiver, or when the configured Pix key is a CPF or a CNPJ other than that holder’s own document, a HYBRID is refused with 422 PBP-0120, whose detail names what to repair, after the final beneficiary is established and before anything is persisted or sent to the provider. A random, e-mail or phone key is not checked against the holder. On a HYBRID, a percentage charge (a fine of type PERCENTAGE, interest of type DAILY_PERCENTAGE or MONTHLY_PERCENTAGE, or a discount of type PERCENTAGE) accepts at most two decimal places, counted as written, so 2.500 carries three: an amount with more is refused with 422 PBP-0006 naming its field (fine.amount, interest.amount or discount.amount), before anything is persisted or sent to the provider. Every boleto is issued with a final beneficiary (sacador avalista): the holder of the issuing account, read from that account’s registration data at issuance and returned in guarantor. This operation does not accept one: a request that sends guarantor is refused with 400 PBP-0001, naming body.guarantor as an unexpected property. The final beneficiary is established after the account checks and before anything is persisted or sent to the provider, and its refusals come in this order: 503 PBP-0118 when the registration data could not be read, or reading it is not configured; then what the registration holds, 400 PBP-0116 when the account has no registered holder, or the holder’s registration is incomplete, and 422 PBP-0117 when the registered holder cannot be used as a final beneficiary; last, 422 PBP-0119 when the payer is the account holder, since a boleto cannot be issued to its own final beneficiary. None of them issues anything, and a retry under the same Idempotency-Key runs the request again. The provider account the boleto is issued on is established after the final beneficiary, on a HYBRID together with its Pix receiver, and before anything is persisted or sent to the provider. When the tenant’s provider configuration cannot establish it, because the provider is not connected for the tenant, it refused the tenant’s credential, or the account to issue on cannot be determined, the request is refused with 422 PBP-0017, the same on every boleto type and with or without a nosso numero; retrying it unchanged does not clear the condition. When the provider refuses that lookup, it is refused with 422 PBP-0014, and when the provider does not answer it, with 503 PBP-0015. None of them issues anything, and a retry under the same Idempotency-Key runs the request again. A nosso numero already held by an active boleto of the same provider account is refused with 422 PBP-0108 before the provider is called. When that holder can be read, the PBP-0108 detail names the boleto that holds the number, and the problem carries its id as ourNumberHolderBoletoId. When it is an earlier emission still without the provider’s answer, the detail says so and does not ask for another number, because that emission can still become a live boleto; when it is a boleto the provider already answered, the detail asks for it to be consulted before another number is informed, because it may be an earlier emission of the same charge whose answer was lost. When a title the local index cannot see holds the number — for example, one issued through another deployment or another tenant sharing the provider account — the provider accepts the emission and refuses it later, and the boleto moves to FAILED, unless the title holding the number belongs to this same emission, in which case the boleto is bound to that title. The boleto stays PENDING instead when the provider’s search cannot tell whose title holds the number — it lists a live title with that number that it attributes to no emission, more than one title of this same emission, or one of this emission without the provider’s identifier or that disagrees with the boleto — or when the search could not be made or read whole; it also stays PENDING, transiently, while the search does not answer or is postponed to a later reconciliation pass. An issuance without a nosso numero whose outcome at the provider is not confirmed yet is answered 202 Accepted: the emission was recorded and sent, but the provider’s answer was lost, could not be read or could not be recorded, and looking the emission up at the provider did not settle it. The 202 carries the recorded boleto, in status PENDING and without providerId, barcode or digitableLine. A background reconciliation completes it: it binds the boleto to its title at the provider when it finds one, and moves it to FAILED when the provider provably holds none. Read its current state with GET /v1/boletos/, using the id in the body. Do not send it again under a new Idempotency-Key, since the provider may have issued it; a resend under the same Idempotency-Key answers this same 202 while the stored answer is kept. Once the read shows the boleto FAILED, it was not issued: send it again under a new Idempotency-Key, since the same Idempotency-Key answers this same 202 until the stored answer expires. Without a nosso numero, 422 PBP-0014 answers only a provider refusal that proves no title was issued, and a retry under the same Idempotency-Key runs the request again. A request under an Idempotency-Key already used for a different boleto, or naming a boleto whose emission reached the provider and failed, is refused with 422 PBP-0013; send it under a new Idempotency-Key.
Autorizações
JWT bearer token issued by the identity provider.
Cabeçalhos
Midaz organization the account and the ledger entry live under. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025.
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.
Corpo
Amount as a decimal string, at most two decimal places.
32"100.00"
Due date, YYYY-MM-DD.
"2030-01-15"
Midaz account the boleto settles into.
Boleto type. The supported values are TRADITIONAL and HYBRID; QR_CODE is refused with 422 PBP-0006. A HYBRID boleto can also be paid by Pix, and needs the tenant's Pix receiver configured at POST /v1/admin/pix-config: without it, or when its Pix key is a CPF or a CNPJ other than the issuing account holder's own document, the request is refused with 422 PBP-0120.
"TRADITIONAL"
Midaz ledger the account lives in and the entry is posted to. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026.
Bank-side identification of the boleto (nosso numero), chosen by the payee. Optional: when absent, the provider assigns the number. A HYBRID boleto takes it as a TRADITIONAL one does, from the same numbering: a number held by an active boleto of either type is in use for both. Surrounding spaces are removed. A hyphen is accepted only when followed by exactly one digit, which is discarded because the check digit is always computed by the bank: 152-3 is sent as 152, while 152- and 152-abc are refused. Any other character that is not a digit is refused. Leading zeros do not make a different number: 152 and 00000000152 are the same number for the current provider, and two active boletos of the same provider account cannot hold it at the same time, whatever their amount or due date. The accepted width is set by the connected provider (11 significant digits for the current one). Format and width refusals answer 400 PBP-0001; a provider that does not accept a number chosen by the payee refuses the field with 422 PBP-0006. A number already held by an active boleto of the same provider account is refused with 422 PBP-0108 before the provider is called. When the holder can be read, the PBP-0108 detail names the boleto that holds the number, and the problem carries its id as ourNumberHolderBoletoId; when it is an earlier emission that has no answer from the provider yet, the detail says so instead of asking for another number; otherwise it asks for that boleto to be consulted before another number is informed, because it may be an earlier emission of the same charge. After a 422 PBP-0014, or a 5xx, answered to an emission with ourNumber, the number can stay held until the periodic reconciliation resolves that emission, which it does not do before a grace period set by the deployment (30 minutes by default); meanwhile that emission can still become a live boleto, and issuing the same charge again with another number can leave two boletos for it.
"00000000152"
Resposta
Created. The banking provider issued the boleto: the body carries its providerId. Compare the 202, where the provider's answer is not confirmed yet.
Midaz ledger the boleto was written with. Always present.
Midaz organization the boleto was written with. Always present.
Final beneficiary (sacador avalista) of the boleto: the holder of the issuing account, read from that account's registration data at issuance. The request never chooses it, and every boleto this operation issues carries it.
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"
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 banking provider assigned to this boleto. Absent from the 202 response, while the provider's answer is not confirmed; read the boleto with GET /v1/boletos/{id} for its current state.
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.