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 '{
  "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"
  },
  "identifier": "order-12345",
  "issueDate": "2026-09-23",
  "expirationPolicy": {
    "allowPaymentAfterDueDate": true,
    "paymentLimitDate": "2026-10-30",
    "blockPaymentAfterLimit": true,
    "decursoGraceDays": 1
  }
}'

{
  "chargeId": "8c1f6a2e-4d3b-4b9a-9f0e-1a2b3c4d5e6f",
  "identifier": "order-12345",
  "barcode": "23793381286000782713695000063305975520000015075",
  "digitableLine": "23793381286000782713695000063305975520000015075",
  "ourNumber": "string",
  "status": "OPEN",
  "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).

When the beneficiary is already eligible, 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. Repeating the same identifier returns 200 with the live boleto.

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). When the beneficiary is already eligible, 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`. Repeating the same `identifier` returns **200** with the live boleto. 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.

dueDatedateRequired

Due date, YYYY-MM-DD. Required.

amountobjectRequired

Face amount of the boleto.

payerobjectRequired

Who must pay the boleto.

identifierstringOptional

Idempotency key for this account. Falls back to the Idempotency-Key header. Unique per account.

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.

chargeIdstringOptional

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

identifierstringOptional

Your idempotency key.

barcodestringOptional

Barcode.

digitableLinestringOptional

Linha digitável.

ourNumberstringOptional

Our number at the settlement bank.

statusenumOptional

Canonical status.

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

Errors

400

Bad Request Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error

502

Bad Gateway Error