Skip to main content
POST
Send a boleto payment for approval
The payment must be REQUESTED, with its amount and balance category set (at creation or with PUT .../boleto/{boletoId}), and every required transaction custom field filled in. Its details can’t change while it waits: to change them, cancel it and create another payment. Send it for approval only when the policies answer NONE: with APPROVE, confirm it instead; with DENY, it is refused. See Business policies and approvals for the whole flow. 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}$

Response

Successful response

A boleto payment just sent for approval, with the approval request opened for it.

​
_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:

"PENDING_APPROVAL"

​
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:

0

​
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"

​
policyRequest
object
required

The approval request opened for the payment.

​
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