---
url: /docs/payables.md
---
# Payables

A payable pays an existing Brazilian bill from stablecoins. Your user pastes a boleto's linha digitável or a PIX copia e cola code, you quote it, and we pay it.

A payable is its own transaction, prefixed `pb_`. It is not a payout: there is no bank account to register first, because a bill already says who gets paid.

## The two instruments

| | Boleto | PIX code |
| --- | --- | --- |
| What you send | Linha digitável, exactly 47 digits | EMV copia e cola payload |
| Settlement | Banking days only | Any time, usually seconds |
| Cancelable | Yes, until it reaches the rail | No |

Utility bills and tax slips (arrecadação, 48 digits starting with 8) are a different rail and are not supported yet. They are rejected at quote time with `PAYABLES_INSTRUMENT_NOT_SUPPORTED`.

## Timing: boletos follow the Brazilian banking calendar

**This is the part that surprises integrators.** PIX runs 24/7, so a PIX payable usually completes in under a minute. Boletos only clear on Brazilian banking days. A boleto submitted on a Saturday is refused by the rail, not queued by it.

So when a boleto cannot go out today, we do not send it and hope. The quote comes back with a `scheduled_date`, and the payable stays in `processing` until that day. Over a weekend that is a legitimate two-day wait, and it is not a stuck payment.

Two rules produce a `scheduled_date`:

* the request lands on a non-banking day, or
* the boleto is above R$250,000 and was submitted after 14:30 BRT.

`scheduled_date` is on the quote, so you can show your user the real date *before* they commit, on the payable itself, and in every webhook.

A boleto whose due date falls before the day it could execute is refused at quote time (`PAYABLES_BOLETO_WOULD_BE_OVERDUE`) rather than paid late. No stablecoins are collected for a payment that would arrive vencido.

Brazilian bank holidays are not predicted. A boleto refused by the rail is retried on the next banking day, so an unexpected holiday costs a day rather than the payment. If the retry would land after the due date, the payable fails and the stablecoins are returned instead.

## Lifecycle

```
processing → completed
           → failed → refunded
           → canceled
```

`on_hold` is a compliance review, which can clear back to `processing` or fail.

Stablecoins are collected before the bill is paid. If the payment then fails, the collection is reversed automatically and the payable ends `refunded`.

## Webhooks

| Event | When |
| --- | --- |
| `payable.processing` | The payable was created and funding started |
| `payable.scheduled` | It will execute on a later banking day, with `scheduled_reason` |
| `payable.on_hold` | Held for compliance review |
| `payable.completed` | Settled on the rail |
| `payable.failed` | Did not go through, with `failure_reason` |
| `payable.refunded` | Failed, and the stablecoins were returned |

`payable.scheduled` carries `scheduled_reason`: `non_banking_day`, `large_amount_cutoff`, or `rail_rejection_retry`. It fires when the payable is deferred at creation and again if the date moves, so a cached `scheduled_date` is never silently wrong.

`failure_reason` is one of a stable set of codes: `funding_allowance_insufficient`, `funding_balance_insufficient`, `funding_failed`, `boleto_amount_changed`, `boleto_no_longer_payable`, `rejected_by_rail`, `canceled_by_client`, `compliance_rejected`, `compliance_review_timeout`, `unknown`. Branch on these rather than on the message.

## Canceling

`DELETE /instances/{instance_id}/payables/{id}` cancels a boleto that has not reached the rail, which includes the whole time it is waiting for its scheduled date. Any stablecoins already collected are returned.

PIX codes cannot be canceled: they settle too fast for there to be a safe window.