Skip to navigation

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. On a company P2P profile contact, this CPF is the holder who signs; it is not taken from the body.

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-Acting-User-AgentstringOptional<=512 characters

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.

X-Acting-Device-IdstringOptional<=128 characters

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.

X-Acting-Session-IdstringOptional<=128 characters

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.

X-Acting-GeostringOptional

Optional latitude,longitude in decimal degrees. Out of range or malformed values are dropped. Risk analysis only. Ignored for delegated credentials.

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

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

X-Request-TimestampstringRequired

Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).

X-Content-SHA256stringRequired

Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.

X-Request-SignaturestringRequired

Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.

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
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.

Allowed values:

Errors

400
Bad Request Error
403
Forbidden Error
502
Bad Gateway Error