Issue a boleto (Boleto Charge)

curl -X POST https://tenant.api.corpx.com/v1/accounts/accountId/boleto/charge \
     -H "X-Tenant-Id: X-Tenant-Id" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "identifier": "order-12345",
  "dueDate": "2026-10-23",
  "amount": {
    "nominal": 150.75,
    "currency": "BRL"
  },
  "payer": {
    "name": "Maria da Silva",
    "personType": "person",
    "taxNumber": "52998224725",
    "email": "maria.silva@example.com",
    "addressStreet": "Avenida Paulista",
    "addressNumber": "1000",
    "addressDistrict": "Bela Vista",
    "addressCity": "Sao Paulo",
    "addressState": "SP",
    "addressZipCode": "01310100"
  },
  "issueDate": "2026-09-23",
  "expirationPolicy": {
    "allowPaymentAfterDueDate": true,
    "paymentLimitDate": "2026-10-30",
    "blockPaymentAfterLimit": true,
    "decursoGraceDays": 1
  }
}'

{
  "chargeId": "8c1f6a2e-4d3b-4b9a-9f0e-1a2b3c4d5e6f",
  "identifier": "order-12345",
  "status": "OPEN",
  "updatedAt": "2026-09-24T14:08:12Z",
  "barcode": "23793381286000782713695000063305975520000015075",
  "digitableLine": "23793381286000782713695000063305975520000015075",
  "ourNumber": "string",
  "registrationCondition": "REGISTERED",
  "dueDate": "2026-02-20",
  "amount": {
    "nominal": 150.75,
    "updatedAmount": 150.75,
    "currency": "BRL"
  },
  "statusReason": "Pagamento pedido #12345",
  "paymentLimitDate": "2026-02-20",
  "payment": {
    "amount": 150.75,
    "settledAt": "2026-02-20T08:33:39Z"
  },
  "payer": {
    "name": "MARIA DA SILVA",
    "taxNumber": "12345678000190",
    "personType": "person"
  }
}

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.

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.

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`. **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.

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 for audit and the backoffice dialog.

Errors

400

Bad Request Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

502

Bad Gateway Error