Skip to main content
POST
Confirm a boleto payment
The organization’s business policies are evaluated again first. You can confirm when they approve the payment (APPROVE, also when no policy matches); when they require approval (NONE), send the payment for approval instead — it is confirmed automatically once approved, and can’t be confirmed by hand meanwhile. Organization admins — API clients included — can confirm whatever the policies decide, and get the verdict back in policy, but not a payment already waiting for approval. When the matching policy approves the payment (APPROVE) and tops up the wallet before paying, the top-up runs first — except when a payment for a later day is confirmed directly: it isn’t topped up. An organization admin confirming a payment the policies send for approval (NONE) skips the top-up too. See Business policies and approvals for the whole flow. The answer depends on the day to pay:
  • 200 — paid now: the payment, now PAID, and the policies’ verdict in policy.
  • 201 — a later day (scheduledAt): the schedule created for it. The payment becomes SCHEDULED; on that day a new payment is created from the same barcode and paid, for the same amount. Cancel the payment to cancel the schedule. That day’s payment is charged to the general-purpose balance category (FLEX_INTERNATIONAL) whatever category was set, and carries none of the payment’s custom fields — so it fails when the organization has a required transaction custom field. The amount must be one the boleto accepts (between txnMinAmount and txnMaxAmount, when it states them): otherwise the confirmation answers 400 with code INVALID_AMOUNT and origin SCHEDULING, nothing is scheduled, and the payment keeps its status — a REQUESTED one can take another amount with PUT .../boleto/{boletoId}; one confirmed after its approval stays PENDING_APPROVAL until its deadline (cancel it and create another).
When the bank refuses the payment — for example, for insufficient funds or a limit — it becomes FAILED, with the reason in failReason, and the error is returned. A FAILED payment can’t be retried: create another one. Some of the bank’s reasons come in lowercase (maximum_value_exceeded_by_period), with the message Unknown error: branch on code. You need permission to pay from the wallet: on the organization’s main wallet, be an organization admin; on another wallet, be an organization admin or have it shared with you as OWNER or USER — and boleto payments must be enabled in its settings.

Headers

​
x-environment
enum<string>

Environment of the payment: 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 pays (24 hexadecimal characters), or default for the organization's main wallet.

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

ID of the boleto payment — its _id (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$

Body

application/json
​
processingType
enum<string>

Leave it out (INSTANT). DELAYED is reserved for the scheduled payments Portão 3 makes on their day.

Available options:
INSTANT,
DELAYED
Example:

"INSTANT"

​
retryCount
integer

Leave it out (0). Reserved for the scheduled payments Portão 3 makes on their day.

Example:

0

Response

Successful response

A boleto payment just made.

​
_id
string
required

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

Example:

"6726b1c2b4d3e80012c9a4a1"

​
environment
enum<string>
required

Environment of the payment: 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 organization's account.

Example:

"66f2a1c7b4d3e80012c9a0b4"

​
walletId
string
required

ID of the wallet that pays.

Example:

"66f2a3d1b4d3e80012c9a0d2"

​
barcode
string
required

The boleto's barcode (or digitable line), as the bank returned it.

Example:

"34194162600001500001790010104351004791020150"

​
status
enum<string>
required

Status of the payment:

  • REQUESTED — created; its details can still be changed, and it can be sent for approval, confirmed or cancelled.
  • PENDING_APPROVAL — waiting for the approvers the business policy names. It is paid once approved.
  • EXPIRED — the approval deadline (approvalExpiresAt) passed while it was still waiting — also when it was approved but the policy's top-up of the wallet failed; the approval request (policyRequestId) tells which.
  • SCHEDULED — confirmed for a later day. On scheduledAt, a new payment is created and paid; this one stays SCHEDULED.
  • PAID — the bank accepted the payment; the money left the wallet.
  • FAILED — the payment was refused, for the reason in failReason.
  • CANCELLED — cancelled before it was paid.
  • REFUNDED — paid, then reversed by the bank; the amount was returned.
Available options:
REQUESTED,
PENDING_APPROVAL,
CANCELLED,
PAID,
FAILED,
REFUNDED,
SCHEDULED,
EXPIRED
Example:

"PAID"

​
payee
string | null
required

Name of the beneficiary — who receives the money (beneficiário). Empty or null when the bank didn't say.

Example:

"Gráfica Aurora Ltda"

​
payeeDocument
string | null
required

CPF or CNPJ of the beneficiary, digits only. Empty or null when the bank didn't say.

Example:

"12345678000195"

​
payer
string | null
required

Name of who the boleto was issued to (pagador). Empty or null when the bank didn't say.

Example:

"Acme Comércio Ltda"

​
payerDocument
string | null
required

CPF or CNPJ of who the boleto was issued to, digits only. Empty or null when the bank didn't say.

Example:

"98765432000110"

​
txnCurrency
string
required

Currency of the amounts, as an ISO 4217 numeric code: 986 (Brazilian real).

Example:

"986"

​
txnOriginalAmount
number
required

Face value of the boleto, in cents.

Example:

150000

​
txnDiscountAmount
number
required

Discount the boleto granted on the day the payment was created, in cents (not refreshed later).

Example:

0

​
txnFineAmount
number
required

Late fine the boleto charged on the day the payment was created, in cents (not refreshed later).

Example:

0

​
txnInterestAmount
number
required

Interest the boleto charged on the day the payment was created, in cents (not refreshed later).

Example:

0

​
txnUpdatedAmount
number
required

Amount the boleto asked for when the payment was created, in cents — the face value with that day's discount, fine and interest applied. It isn't refreshed later: what will be paid is pendingConfirmation.amount, and what was paid, confirmedAmount.

Example:

150000

​
txnMinAmount
number
required

Smallest amount the boleto accepts, in cents. 0 when it states none.

Example:

0

​
txnMaxAmount
number
required

Largest amount the boleto accepts, in cents. 0 when it states none.

Example:

0

​
processingType
enum<string>
required

How the payment was made: INSTANT (when it was confirmed) or DELAYED (by a schedule, on its day).

Available options:
INSTANT,
DELAYED
Example:

"INSTANT"

​
confirmedAmount
number
required

Amount paid, in cents. 0 until the payment is made.

Example:

150000

​
createdAt
string<date-time>
required

When the payment was created.

Example:

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

​
updatedAt
string<date-time>
required

When the payment last changed.

Example:

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

​
policy
Policy evaluation · object | null
required

The business policy evaluated on this confirmation, and what it decided. null when the payment was confirmed after its approval, and when an organization admin confirmed it while the policies couldn't be evaluated.

​
type
enum<string> | null

Kind of boleto: GENERIC (a bank boleto) or UTILITY_BILL (a utility or tax bill — energy, water, phone, taxes). A bank boleto can only be scheduled for its due date (or the next business day), or for any business day when it has no due date. null or absent when the bank didn't say.

Available options:
GENERIC,
UTILITY_BILL,
null
Example:

"GENERIC"

​
issuer
string | null

Bank that issued the boleto. null or absent when the bank didn't say.

Example:

"Itaú Unibanco S.A."

​
dueDate
string<date-time> | null

Due date of the boleto (vencimento). null or absent when it has none — usual for utility and tax bills.

Example:

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

​
expiresAt
string<date-time> | null

Last day the boleto can be paid (data limite de pagamento). null or absent when the bank didn't say.

Example:

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

​
settlesAt
string<date-time> | null

Settlement date the bank reported for the boleto when it was looked up. null or absent when the bank didn't say.

Example:

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

​
receipt
object

Authentication data the bank returned when the boleto was looked up.

​
external
object

References of the payment at the bank.

​
pendingConfirmation
object

What will be paid. Absent until an amount is known — when the boleto states none and none was sent, set it with PUT .../boleto/{boletoId} — and on payments created before it existed.

​
customFields
object

Values of the organization's transaction custom fields, keyed by each field's slug. Absent when the payment has none.

Example: {"cost-center":"CC-1020"}

Example:
​
requester
object

Who created the payment. Absent on payments created before it was recorded.

​
scheduledAt
string<date-time>

Day the payment is scheduled for. Absent when it is paid as soon as it is confirmed.

Example:

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

​
scheduledTimeZone
string

Time zone scheduledAt was read in — always America/Sao_Paulo. Present only with scheduledAt.

Example:

"America/Sao_Paulo"

​
scheduleId
string<uuid>

ID of the schedule created when a payment for a later day was confirmed. Cancel the payment to cancel it.

Example:

"8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"

​
policyRequestId
string

ID of the approval request opened when the payment was sent for approval, or of the automatic approval that funded it. Absent otherwise.

Example:

"4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a"

​
approvalExpiresAt
string<date-time>

Deadline for the approval: 21:00 (São Paulo time) of the day the payment is for, and at least one hour after it was sent for approval. Present once it was sent for approval.

Example:

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

​
autoResolutionRequestedAt
string<date-time>

When a confirmation first asked for the automatic approval of the matching business policy. Once set, every later confirmation of this payment follows that approval. Absent when no confirmation needed it.

Example:

"2026-11-02T13:12:05.000Z"

​
autoResolutionInFlightUntil
string<date-time>

While set and in the future, a confirmation is carrying out the matching policy's automatic approval, and cancelling the payment is refused until then.

Example:

"2026-11-02T13:13:35.000Z"

​
confirmedAt
string<date-time> | null

When the payment was made. null or absent until then.

Example:

"2026-11-02T13:12:07.000Z"

​
confirmedBalanceCategory
enum<string>

Balance category of the wallet the payment was charged to.

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

"FLEX_INTERNATIONAL"

​
failReason
string

Why the payment failed, as an error code — for example LIMIT_EXCEEDED, INSUFFICIENT_FUNDS or REJECTED_BY_FRAUD. Only on FAILED payments.

Example:

"INSUFFICIENT_FUNDS"

​
canceledAt
string<date-time> | null

When the payment was cancelled. null or absent unless it was.

Example:

"2026-11-02T15:40:00.000Z"

​
refundedAt
string<date-time>

When the bank reversed the payment.

Example:

"2026-11-05T10:30:00.000Z"

​
__v
number

Internal revision counter of the record.

Example:

0