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
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Headers
CPF of the human performing the operation. Required on cashout routes when the credential enforces a transaction PIN. On a company P2P profile contact, this CPF is the holder who signs; it is not taken from the body.
Transaction PIN of the operator in X-Acting-Document. Required on cashout routes when the credential enforces a PIN (428 pin_required).
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.
Optional user-agent of the end user’s browser or app, for integrator credentials calling on their behalf. Feeds risk analysis only: an invalid or oversized value is dropped and the payment still proceeds. Ignored for delegated credentials.
Optional device fingerprint or identifier from the integrator’s own system. Risk analysis only; never required and never a reason to reject the payment. Ignored for delegated credentials.
Optional session id of the end user in the integrator’s system. Risk analysis only; never required and never a reason to reject the payment. Ignored for delegated credentials.
Optional latitude,longitude in decimal degrees. Out of range or malformed values are dropped. Risk analysis only. Ignored for delegated credentials.
Optional client-generated idempotency token (recommended for safe retries).
Request
Barcode or linha digitável (alias of line)
Amount to pay, greater than zero. Use totalUpdated from the preview.
Linha digitável — canonical field; barcode is the alias
Payer’s CPF/CNPJ
Response headers
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).
Canonical payment id (bol_ + UUID). Same value as boletoId and as transactionId in webhooks.
Deprecated alias of paymentId (same value).
Always PROCESSING at acceptance. Terminal state (COMPLETED/FAILED) is delivered via webhook and the status endpoint.