Skip to navigation

Issue a boleto (Boleto Charge)

Issues a boleto for this account. Scope boleto_charge.manage. The feature boleto_charge starts disabled for every tenant, including tenants created after this release. While it is off every boleto charge route returns 403 feature_disabled. With the feature on, issuance still requires boletoCharge.enabled=true on the tenant policy (every account of the tenant) or on this account’s policy; otherwise the route returns 403 boleto_charge_account_disabled. enabled=false on the account policy opts that account out of a tenant-wide enable.

Beneficiary. If the holder is not yet a beneficiary (or the relationship is closed), this call registers the holder from the account’s own data and returns 202 with errorCode: boleto_charge_beneficiary_pending and Retry-After: 300. Nothing was issued. Repeat the same body in a few minutes. You can also register first with POST .../boleto/charge/beneficiary (no body).

identifier is required in the JSON body and is the only idempotency key for this operation. Idempotency-Key is not accepted as a fallback. Repeating the same boleto returns 200 without consuming quota again.

The beneficiary is validated before quota is reserved. A new issuance must fit both monthly BRT quotas: the tenant policy boletoCharge.maxIssuesPerMonth (default 100) and the account policy (default 5 for PF, 10 for PJ). Once admitted, the slot is consumed even if the settlement bank later fails; it is never refunded.

When the beneficiary is already eligible and quota is available, the response is 202 with the boleto (chargeId, barcode, digitableLine). Registration at the central base is still asynchronous: subscribe to boleto.charge.registered and boleto.charge.registration_failed.

There is no write-off of an open boleto. Bound validity with expirationPolicy.paymentLimitDate.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.

Request

This endpoint expects an object.
identifierstringRequired>=1 character

Caller-owned idempotency key, unique per account.

dueDatedateRequired

Due date, YYYY-MM-DD.

amountobjectRequired
Face amount of the boleto.
payerobjectRequired
Who must pay the boleto.
issueDatedateOptional

Issue date, YYYY-MM-DD. dueDate cannot be before it.

interestobjectOptional
Interest or fine. startDate, when set, must be after dueDate.
fineobjectOptional
Interest or fine. startDate, when set, must be after dueDate.
discountobjectOptional

Early-payment discount. Each groups[].limitDate must be before dueDate.

abatementobjectOptional
Fixed abatement. Together with discounts it must not reach amount.nominal.
allowPartialPaymentbooleanOptional
Accept a payment below the amount.
allowDivergentPaymentbooleanOptional
Accept an amount other than the face value, within min and max.
divergentPaymentModeenumOptional
How a divergent payment is bounded.
Allowed values:
minPaymentAmountdoubleOptional
Minimum accepted payment when divergent payment is on. Not greater than maxPaymentAmount.
maxPaymentAmountdoubleOptional
Maximum accepted payment when divergent payment is on.
expirationPolicyobjectOptional

How long the boleto can be paid. There is no write-off of an open boleto; paymentLimitDate is how you bound validity.

Response

This identifier was already issued. Body is the live boleto.
chargeIdstring

Settlement-bank id of this boleto. Use it on the item route and in webhooks.

identifierstring
Your idempotency key.
statusenum
Canonical status.
updatedAtdatetime
Last successful synchronization with the settlement bank, in UTC.
barcodestringOptional
Barcode.
digitableLinestringOptional

Linha digitável.

ourNumberstringOptional
Our number at the settlement bank.
registrationConditionenumOptional
Registration at the central base. PENDING right after issuance.
Allowed values:
dueDatedateOptional
Due date.
amountobjectOptional
statusReasonstringOptional
Present when the settlement bank sent a reason.
paymentLimitDatedateOptional
Last day payment is accepted.
paymentobjectOptional
Present after settlement.
payerobjectOptional
requestobjectOptional
Original normalized issuance request, available on item detail.

Errors

400
Bad Request Error
403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
502
Bad Gateway Error