---
title: "How to pay invoices, boletos, and Pix codes with stablecoins through an API"
seoTitle: "How to pay invoices and boletos with stablecoins via API"
description: "Register the bill, quote it, pay it from USDC or USDT, and track two webhook streams. A developer guide to stablecoin bill pay, boleto gotchas included."
date: "2026-10-03"
updated: "2026-10-03"
category: "payments"
author: "BlindPay Team"
howto:
  name: "How to pay a bill from stablecoins through an API"
  steps:
    - name: "Verify the customer"
      text: "Onboard the business that owes the bill with KYB, or the individual with KYC, and wait for approval before registering anything."
    - name: "Register the bill"
      text: "Send the boleto barcode, the Pix copy-and-paste code, or the invoice with the vendor's bank details and line items. Save the payable ID it returns."
    - name: "Quote the bill"
      text: "Request a quote for the payable instead of an amount. The provider prices the stablecoin side so the bill is paid in full, and the quote expires in minutes."
    - name: "Authorize and execute the payout"
      text: "Approve the stablecoin pull from your wallet if you fund from an external wallet, then execute the payout against the quote before it expires."
    - name: "Track both webhook streams"
      text: "Listen for payable events for the bill's state and payout events for the payment attempt, and correlate them by ID so one paid bill isn't counted twice."
    - name: "Reconcile and retry"
      text: "Match each completed payable to the invoice in your books. If an attempt fails or is refunded, quote the same payable again instead of registering it twice."
faq:
  - q: "Can you pay an invoice with stablecoins if the vendor doesn't accept crypto?"
    a: "Yes. A stablecoin bill-pay API converts USDC or USDT into the vendor's currency and pays the bill over a normal rail, such as ACH or wire in the US or a boleto or Pix payment in Brazil. The vendor receives an ordinary bank payment and never sees the stablecoin."
  - q: "What is a payable in a payments API?"
    a: "A payable is a bill you register before paying it: an invoice, a boleto, or a Pix code. Unlike a regular payout, where you choose the amount, a payable carries its own amount from the line items or from what the payment rail resolves. You pay it by quoting the payable and executing the payout."
  - q: "Can a boleto amount change after you register it?"
    a: "Yes. A boleto's amount is resolved again when you quote it, and it can move because of fines, interest, or an early-payment discount. Two quotes on different days can return different amounts. Always pay against a fresh quote instead of a cached figure."
  - q: "When do boleto payments clear?"
    a: "Boletos clear on Brazilian banking days between 06:30 and 18:30 BRT, and bills above R$250,000 must be paid by 14:30 BRT to clear the same day. A boleto quoted outside that window is paid the next banking day. Pix payments run 24/7."
  - q: "What happens if a stablecoin bill payment fails?"
    a: "The bill goes back to a payable state and the attempt's failure reason stays on the payout. Don't register the bill again, since the same code would be rejected as a duplicate. Quote the same payable again and pay it. A refunded attempt returns the stablecoins to the funding wallet."
  - q: "Which stablecoins and networks can pay a bill?"
    a: "On BlindPay, payables are paid from USDC or USDT on EVM networks today, from an external wallet or a managed wallet. Code payables, such as boletos and Pix codes, are in Brazilian reais. Invoice payables to a US bank account are in US dollars over ACH or wire."
---

To pay a bill from stablecoins through an API, register the bill (an invoice with the vendor's bank details, a boleto barcode, or a Pix code), request a quote for it, then execute a payout from USDC or USDT. The provider converts the stablecoins and pays the bill over the vendor's normal rail. Track the bill and the payment as two separate objects, and retry by re-quoting, never by registering twice.

This guide is for engineering and product teams adding bill pay or accounts payable to a stablecoin product. It covers the general pattern first, then the exact flow, with BlindPay's Payables API as the worked example.

## Why pay bills from stablecoins instead of sending a payout?

A regular stablecoin payout answers "send this much to this account." A bill is different. Its amount, beneficiary, and due date are set by someone else, and for some bill types they change over time. Treating a bill as a plain payout means your code has to parse the bill, compute what's owed, and hope it didn't move.

A bill-pay API flips that. You register the bill, the provider resolves what it can from the payment rail, and the amount comes from the bill, not from you. That matters for three groups:

- **Businesses that hold stablecoin balances** and want to pay suppliers, rent, or taxes without converting manually first.
- **Fintechs and wallets** that want to offer "pay a bill" to customers who keep dollars on-chain.
- **Cross-border teams** paying Brazilian boletos or US vendor invoices from a dollar stablecoin treasury.

There's also a reconciliation reason. The U.S. Faster Payments Council's [July 2026 report](https://fasterpaymentscouncil.org/userfiles/2080/files/CBPWG_DAWG_Stablecoins%20as%20a%20Cross-Border%20Payment%20Method2_07-22-2026%20Final.pdf) points out that stablecoins don't carry trade information on their own, so an overlay is needed to link a payment to its invoice. A payable is that overlay: one object that ties the bill, the line items, and the payment together.

## Which bills can you pay with stablecoins?

| Bill type | What you send | Currency | Paid over | Where the amount comes from |
| --- | --- | --- | --- | --- |
| US vendor invoice | Vendor's bank details, line items, taxes, discount | USD | ACH or wire | Your line items, plus taxes, minus discount |
| Boleto | The 47-digit linha digitável or 44-digit barcode | BRL | Boleto clearing | Resolved from the rail at registration, and again at quote time |
| Utility or tax bill (arrecadação) | The 48-digit code or 44-digit barcode starting with 8 | BRL | Bill clearing | Encoded in the barcode, no interest |
| Pix code with a fixed amount | The Pix copy-and-paste payload | BRL | Pix | Embedded in the code |
| Pix code without an amount | The Pix payload plus line items | BRL | Pix | Your line items |

Pix is the Banco Central do Brasil's [instant payment system](https://www.bcb.gov.br/en/financialstability/pix_en) and runs 24/7. Boletos are Brazil's bank payment slips, used for everything from supplier invoices to school fees, and they clear only on banking days. US invoices travel over ACH, governed by [Nacha](https://www.nacha.org/content/ach-network), or by wire.

## How do you pay a bill from stablecoins, step by step?

1. **Verify the customer.** The business that owes the bill goes through KYB, or the individual through KYC. Nothing is registered until it's approved.
2. **Register the bill.** One call, whatever the type. You get back a payable ID and the resolved details: beneficiary, current amount, due date.
3. **Quote the payable.** Ask for a quote with the payable ID, the network, and the token. Don't send an amount. The quote prices the stablecoin side so the bill is paid in full, with the sender covering fees.
4. **Authorize and execute.** From an external EVM wallet, approve the ERC-20 pull for the quoted amount, then execute the payout. From a managed wallet, skip the approval.
5. **Track two webhook streams.** Payable events describe the bill. Payout events describe the payment attempt, including compliance holds and failure reasons.
6. **Reconcile and retry.** Mark the invoice paid on the payable's completion event. If an attempt fails or is refunded, the bill returns to draft: quote it again.

Here's an illustrative version of steps 2 and 3 on BlindPay's API, registering a boleto and quoting it:

```bash
# 2. Register the boleto
curl --request POST \
  --url https://api.blindpay.com/v1/instances/in_000000000000/payables \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "re_000000000000",
    "currency": "BRL",
    "boleto_barcode": "34191790010104351004791020150008191070026000"
  }'

# 3. Quote it by payable ID, with no amount
curl --request POST \
  --url https://api.blindpay.com/v1/instances/in_000000000000/quotes \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "payable_id": "pb_000000000000",
    "network": "base",
    "token": "USDC"
  }'
```

The full request and response shapes, including invoice registration with line items, are in the [Payables docs](/docs/payables).

## What makes boletos different?

Boletos are the bill type that breaks naive integrations. Four rules to build around:

- **The amount moves.** A boleto's amount is resolved again at quote time. Fines, interest, or a discount for paying early can change it. Quote an overdue boleto on two different days and you can get two amounts. Never pay from a cached figure.
- **The quote can update the bill.** Quoting re-resolves the due date and, if it was empty, the beneficiary. A read right after quoting can show different details than registration did.
- **Boletos clear in a window.** Brazilian banking days only, 06:30 to 18:30 BRT, or 14:30 BRT for bills above R$250,000. A boleto quoted outside that window is paid the next banking day.
- **Late bills get rejected.** If the next available payment day falls after the due date, the quote fails with `payable_boleto_would_be_overdue` instead of paying late.

Pix codes and US invoices don't have these problems. Their amount is fixed at registration, and Pix runs at any hour.

## How do statuses and webhooks work for a paid bill?

A payable has four statuses, and they describe the bill, not the attempt:

| Status | Meaning |
| --- | --- |
| `draft` | Registered and quotable. A failed or refunded attempt returns the bill here |
| `processing` | A payout is executing it, including during a compliance hold |
| `completed` | Paid. Terminal |
| `canceled` | A draft that was deleted. The code can be registered again |

The payment attempt lives on the payout, with its own `payout.new`, `payout.update`, and `payout.complete` events. The bill emits `payable.new`, `payable.update`, and `payable.complete`. One paid bill produces both a `payable.complete` and a `payout.complete`. Correlate them through `payable_id` and `payout_id`, and count the payment once. [Stablecoin API webhooks and reconciliation](/resources/more/stablecoin-api-webhooks-reconciliation) covers signature checks and deduplication.

## What are the common mistakes?

- **Registering the same code twice.** The second call fails with `duplicate_payable`. To retry, quote the existing payable.
- **Sending an amount with the quote.** A payable quote takes its amount from the bill. Don't send `request_amount`.
- **Letting the quote expire.** Quotes last 5 minutes. Execute promptly, or request a new quote for the same payable.
- **Paying from an unsupported network.** Payables are EVM-only today. A Stellar or Solana quote is refused with `payable_network_not_supported`.
- **Forgetting the minimum.** A bill must be worth at least 10.00 USD on the paying side, and a bill near that floor can fail later if the rate moves.
- **Double counting.** Booking both the payable and the payout completion as payments.

## How does BlindPay handle bill pay?

[BlindPay](/global-payments) launched Payables in August 2026. It pays invoices to US bank accounts over ACH or wire, boletos, utility and tax bills, and Pix codes, from USDC or USDT on EVM networks, using the same quote-and-payout flow as any other BlindPay payout. Invoice payables can attach the original PDF, and the dashboard can prefill an invoice by reading it with AI. Every bill passes the same KYC, KYB, and sanctions checks as the rest of the API.

To build accounts payable on top of it, the [invoice payables prompt](/prompts/integrate-invoice-payables) gives a coding agent the full integration spec. The [cut-off times reference](/docs/kb/cut-off-times) lists the boleto windows.

## What to do next

Pick the bill type your users pay most often and run it end to end on a development instance: register it, quote it, pay it, and watch both webhook streams. Then try a failed attempt and confirm your code re-quotes instead of re-registering. For the full context on how stablecoin payments move, see [what blockchain payments are](/resources/more/what-are-blockchain-payments), and for when a bill is better paid over a plain domestic rail, [when not to use blockchain payments](/resources/more/when-not-to-use-blockchain-payments).