Account and reconciliation

Bank slip issuance

Issues a boleto on behalf of the account. It is the reverse of paying a boleto: here the account is the beneficiary and a third party pays.

The bank_slip_issuance feature starts disabled for every tenant, including tenants created after the release. While it is off, POST and GET on /v1/accounts/{accountId}/bank-slips return 403 feature_disabled. CorpX turns it on from the admin panel. Turning it off later does not cancel a slip already issued.

Credential scope: bank_slip.manage. It is money in, not cashout.

First issuance of an account

The holder is not a beneficiary at the bank yet. The first POST registers the beneficiary and returns immediately:

{
  "errorCode": "bank_slip_beneficiary_pending",
  "message": "Cadastro do beneficiário desta conta em análise no banco. Isso acontece só na primeira emissão de cada conta; repita a solicitação em alguns minutos.",
  "beneficiary": { "status": "PENDING", "requestedAt": "2026-09-23T18:00:00Z" }
}

HTTP 202, header Retry-After: 300. Nothing was issued and there is no bankSlipId. Repeat the same body in a few minutes. If registration is still pending, the response is the same, without a new registration.

ineligible or underReview returns 422 bank_slip_beneficiary_ineligible. A synchronous registration failure returns 502 bank_slip_beneficiary_registration_failed and nothing is issued.

Issue

POST /v1/accounts/{accountId}/bank-slips

identifier is the account’s idempotency key (when omitted, the Idempotency-Key header is used). dueDate is YYYY-MM-DD. amount.nominal is greater than zero. payer.personType is person or company.

The 202 body carries bankSlipId, barcode, digitableLine, ourNumber, and registrationCondition: pendingRegistration. Registration at the central base arrives later as bank_slip.registered or bank_slip.registration_failed.

Repeating the same identifier returns 200 with the live slip and does not issue another one.

Consult

Every read is live at the settlement bank. There is no local copy of the slip.

  • GET /v1/accounts/{accountId}/bank-slips — filters barcode, payer, dueDate, status, page, pageSize (up to 200).
  • GET /v1/accounts/{accountId}/bank-slips/{bankSlipId} — bankSlipId is the id returned at issuance.
  • GET /v1/accounts/{accountId}/bank-slips/beneficiary — 404 bank_slip_beneficiary_not_found when the account was never registered.

Write-off

There is no way to write off an open slip. DELETE /v1/accounts/{accountId}/bank-slips/{bankSlipId} returns 501 bank_slip_write_off_unavailable. When the validity must be predictable, send expirationPolicy.paymentLimitDate at issuance.

Events

bank_slip.registered, bank_slip.registration_failed, bank_slip.settled, bank_slip.overdue, bank_slip.written_off, bank_slip.cancelled, bank_slip.expired. Settlement also shows on the statement as BOLETO. bank_slip.failed is in the catalog and is not sent in this version.