Skip to main content
POST
Create a boleto charge
The bank registers the boleto right away: the charge comes back CREATED, with the digitableLine and barcode to show the payer — download its PDF to send it. Rarely, it comes back INITIATED, still without them: read the charge until it is CREATED. There is no notification for a boleto charge: read it to know when it is PAID, which credits confirmedAmount to the wallet. A charge can’t be cancelled: an unpaid boleto stays payable until expiresAt and is then written off by the bank (CANCELED). The boleto is issued for exactly txnAmount: the payer can’t pay a different amount. Amounts are in cents; the percentage rates of txnDiscountAmount, txnFineAmount and txnInterestAmount are fractions (0.02 is 2%). The payer’s name and address are printed on the boleto as the bank keeps them — without accents, the name cut to 50 characters, the street to 40 and the neighborhood to 20 — and the response shows them that way. When the bank refuses the boleto, or doesn’t answer, the error is returned and the charge is kept with status PROCESSING, without a barcode — Portão 3 will never give it one. If the bank refused it (a 4xx), fix the request and create the charge again. If the bank didn’t answer (a 5xx), it may still have registered the boleto, which the payer could then pay from their bank’s app: contact support before creating the charge again, so the payer isn’t charged twice. A refusal under the bank’s business rules comes back with the bank’s status and its reason as code — in lower case, unless this API knows it by name; the reason not_found is always a 500 NOT_FOUND — and an answer this API doesn’t recognize is a 500 BANKING_PROVIDER_INTEGRATION_ERROR. Use default as walletId for the organization’s main wallet. Any member of the organization can create one.

Headers

​
x-environment
enum<string>

Environment of the charge: LIVE (production) or TEST (sandbox). When you omit it, TEST is used; any other value is rejected.

Available options:
LIVE,
TEST

Path Parameters

​
realmId
string<uuid>
required

ID of your realm.

Format: UUID

​
organizationId
string<uuid>
required

ID of the organization.

Format: UUID

​
accountId
string
required

ID of the organization's account (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$
​
walletId
string
required

ID of the wallet that receives the payment (24 hexadecimal characters), or default for the organization's main wallet.

Pattern: ^([0-9a-fA-F]{24}|default)$

Body

application/json
​
txnCurrency
enum<string>
required

Currency of the charge: 986 (Brazilian real) — the only one a boleto takes.

Available options:
986
Example:

"986"

​
txnAmount
integer
required

Amount of the boleto, in cents — at most 24,999,900 (R$ 249,999.00).

Required range: 1 <= x <= 24999900
Example:

150000

​
txnDivergentAmountType
enum<string>
required

Whether the payer may pay a different amount. Send NOT_ALLOW_DIFFERENT_AMOUNT: the boleto is always issued for exactly txnAmount, whatever you send, and the charge comes back with NOT_ALLOW_DIFFERENT_AMOUNT. With BETWEEN_MIN_AND_MAX or ONLY_MIN_AMOUNT you must still send txnMinAmount and txnMaxAmount.

Available options:
ANY_AMOUNT,
BETWEEN_MIN_AND_MAX,
ONLY_MIN_AMOUNT,
NOT_ALLOW_DIFFERENT_AMOUNT
Example:

"NOT_ALLOW_DIFFERENT_AMOUNT"

​
dueDate
string
required

Due date of the boleto (YYYY-MM-DD): today or later.

Minimum string length: 1
Example:

"2026-11-20"

​
expiresAt
string
required

Last day the boleto can be paid (YYYY-MM-DD). It must be after dueDate.

Minimum string length: 1
Example:

"2026-12-20"

​
customer
object
required

The payer: the person or company the boleto is issued to.

​
txnAmountLimitType
enum<string>

Unit of txnMinAmount and txnMaxAmount: FIXED_VALUE (cents) or PERCENT. Not used today, since the payer can't pay a different amount.

Available options:
FIXED_VALUE,
PERCENT
Example:

"FIXED_VALUE"

​
txnMaxAmount
number | null

Highest amount the payer may pay. Required, an integer of at least 1, with BETWEEN_MIN_AND_MAX or ONLY_MIN_AMOUNT; otherwise omit it or send 0. Not used today, since the payer can't pay a different amount.

Example:

0

​
txnMinAmount
number | null

Lowest amount the payer may pay. Required, an integer of at least 1, with BETWEEN_MIN_AND_MAX or ONLY_MIN_AMOUNT; otherwise omit it or send 0. Not used today, since the payer can't pay a different amount.

Example:

0

​
txnDiscountAmount
object[] | null

Discounts for paying early. Omit it for none.

​
txnFineAmount
object | null

A one-off fine for paying late. Omit it for none.

​
txnInterestAmount
object | null

Interest for paying late. Omit it for none.

​
description
string

Description of the charge.

Example:

"Mensalidade de novembro"

Response

Successful response

A boleto charge issued from one of your wallets.

​
_id
string
required

ID of the charge. Use it as {boletoId} in the charge endpoints.

Example:

"6727c3d4b4d3e80012c9b5c2"

​
environment
enum<string>
required

Environment of the charge: LIVE (production) or TEST (sandbox).

Available options:
LIVE,
TEST
Example:

"LIVE"

​
realmId
string<uuid>
required

ID of the realm.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

​
organizationId
string<uuid>
required

ID of the organization.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

​
accountId
string
required

ID of the account.

Example:

"66f2a1c7b4d3e80012c9a0b4"

​
walletId
string
required

ID of the wallet that receives the payment.

Example:

"66f2a3d1b4d3e80012c9a0d2"

​
status
enum<string>
required

Status of the charge:

  • CREATED — registered at the bank and payable: show digitableLine, barcode or the PDF.
  • PAID — paid and credited to the wallet (see confirmedAmount).
  • CANCELED — written off unpaid by the bank some weeks after expiresAt; it can't be paid.
  • INITIATED, REQUESTED, ENQUEUED — accepted by the bank and being registered; there is no barcode yet, so read the charge again until it is CREATED.
  • PROCESSING — being issued. A charge still PROCESSING after its creation answered an error never gets a barcode from Portão 3. If the bank refused it, create a new one; if the bank didn't answer, it may have registered the boleto anyway — contact support before creating a new one, so the payer isn't charged twice.
  • PROCESSING_PAYMENT — paid and being credited.
  • ERROR — the bank could not issue it.
Available options:
INITIATED,
REQUESTED,
ENQUEUED,
PROCESSING,
CREATED,
PROCESSING_PAYMENT,
PAID,
CANCELED,
ERROR
Example:

"CREATED"

​
txnCurrency
string
required

Currency of the charge: 986 (Brazilian real). A charge whose creation failed before 2026-11 keeps the currency it was sent with.

Example:

"986"

​
txnAmount
number
required

Amount of the boleto, in cents.

Example:

150000

​
txnDivergentAmountType
enum<string>
required

Whether the payer may pay a different amount. Always NOT_ALLOW_DIFFERENT_AMOUNT once the charge is issued: the boleto is issued for exactly txnAmount.

Available options:
ANY_AMOUNT,
BETWEEN_MIN_AND_MAX,
ONLY_MIN_AMOUNT,
NOT_ALLOW_DIFFERENT_AMOUNT
Example:

"NOT_ALLOW_DIFFERENT_AMOUNT"

​
txnMaxAmount
number
required

Highest amount the payer may pay, in cents — txnAmount once the charge is issued.

Example:

150000

​
txnMinAmount
number
required

Lowest amount the payer may pay, in cents — txnAmount once the charge is issued.

Example:

150000

​
txnDiscountAmount
object[] | null
required

Discounts for paying early. Empty when there are none — null on some charges created before 2026-11, whose creation failed.

​
dueDate
string<date-time>
required

Due date of the boleto.

Example:

"2026-11-20T00:00:00.000Z"

​
expiresAt
string<date-time>
required

Last day the boleto can be paid.

Example:

"2026-12-20T00:00:00.000Z"

​
description
string
required

Description of the charge. Empty when none was sent.

Example:

"Mensalidade de novembro"

​
customer
object
required

The payer, as printed on the boleto (as it was sent, on a charge whose creation failed).

​
confirmedAmount
number
required

Amount paid, in cents — with any discount, fine or interest applied. 0 until the charge is paid.

Example:

0

​
createdAt
string<date-time>
required

When the charge was created.

Example:

"2026-11-05T13:10:22.000Z"

​
updatedAt
string<date-time>
required

When the charge last changed.

Example:

"2026-11-05T13:10:24.000Z"

​
barcode
string | null

Barcode of the boleto (44 digits). Absent or null until the charge is CREATED.

Example:

"34191162100001500001090000012345678901234567"

​
digitableLine
string | null

Digitable line of the boleto (linha digitável, 47 digits) — what the payer types into their bank app. Absent or null until the charge is CREATED.

Example:

"34191090080123456789001234567890116210000150000"

​
txnAmountLimitType
enum<string>

Unit of txnMinAmount and txnMaxAmount. Always FIXED_VALUE once the charge is issued.

Available options:
FIXED_VALUE,
PERCENT
Example:

"FIXED_VALUE"

​
txnFineAmount
object | null

The fine for paying late. Absent (or null, on some older charges) when there is none.

​
txnInterestAmount
object | null

The interest for paying late. Absent (or null, on some older charges) when there is none.

​
finalBeneficiary
object

The beneficiary printed on the boleto. Absent until the charge is issued.

​
external
object

Reference of the boleto at the bank. Absent until the charge is issued.

​
confirmedAt
string<date-time>

When the payment was credited. Present only on PAID charges.

Example:

"2026-11-18T14:32:10.000Z"

​
confirmedCurrency
string

Currency of the payment: 986 (Brazilian real). Absent until the charge is issued.

Example:

"986"

​
confirmedBalanceCategory
enum<string>

Balance category of the wallet the payment is credited to. Absent until the charge is issued.

Available options:
FLEX_NATIONAL,
FLEX_INTERNATIONAL,
FOOD,
GAS,
MOBILITY,
TOLL,
FLEX_NATIONAL_WITHOUT_WITHDRAWALS,
ADS,
SAAS,
HOTEL,
AIRLINES,
TRAVEL,
BLOCKED,
CASHBACK
Example:

"FLEX_INTERNATIONAL"

​
__v
number

Internal revision counter of the record.

Example:

0