API BaaSBoleto

Pay a boleto

Initiates payment of a boleto, utility bill, or tax. `amount` is required and must be the amount the settlement bank expects **today** — the `totalUpdated` from `POST /boleto/preview`, not the face value in the barcode. Sending the face value for an overdue slip fails with `boleto_amount_mismatch` (422), and the error message carries the amount the settlement bank expects. Because interest accrues daily, run the preview on the same day you pay. Returns a canonical `paymentId` (`bol_` + UUID). **This is the single id to keep**: it is echoed by the status endpoint and arrives as `transactionId` (and `paymentId`) in the `boleto.paid` / `boleto.failed` webhooks. The legacy `boletoId` field carries the same value. Requires feature flag `boleto_payment` to be enabled for the tenant.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Acting-DocumentstringOptional
CPF of the human performing the operation. Required on cashout routes when the credential enforces a transaction PIN.
X-Transaction-PinstringOptional

Transaction PIN of the operator in X-Acting-Document. Required on cashout routes when the credential enforces a PIN (428 pin_required).

X-Acting-IpstringOptional

Real IP of the end user, for integrator credentials calling on their behalf. This is the IP evaluated against cashoutSourceIps — without it the check would see your server’s IP. Ignored for delegated credentials, where the connection IP is already the right one.

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringOptional

Optional client-generated idempotency token (recommended for safe retries).

Request

This endpoint expects an object.
barcodestringRequired

Barcode or linha digitável (alias of line)

amountdoubleRequired

Amount to pay, greater than zero. Use totalUpdated from the preview.

linestringOptional

Linha digitável — canonical field; barcode is the alias

taxIdstringOptional

Payer’s CPF/CNPJ

scheduleddateOptional
Schedule date, when supported by the settlement bank
descriptionstringOptional
Optional payment description

Response headers

LocationstringOptional
Relative path to poll the payment status.

Response

Payment accepted (asynchronous). The endpoint returns immediately — it does **not** block waiting for settlement. Poll the status endpoint with `paymentId` (see the `Location` header), or wait for the `boleto.paid` / `boleto.failed` webhook. Idempotency: send an `Idempotency-Key` header. Retries with the same key return the same `paymentId` and reuse the same run (no duplicate debit).
paymentIdstringOptional

Canonical payment id (bol_ + UUID). Same value as boletoId and as transactionId in webhooks.

boletoIdstringOptional

Deprecated alias of paymentId (same value).

workflowIdstringOptional
runIdstringOptional
Temporal run id of the payment workflow.
idempotencyKeystringOptional
amountdoubleOptional
statusenumOptional

Always PROCESSING at acceptance. Terminal state (COMPLETED/FAILED) is delivered via webhook and the status endpoint.

Errors

400
Bad Request Error
403
Forbidden Error
502
Bad Gateway Error