# Bill pay for agents

> An agent sends supplier bills to Conto, and Conto pays them by bank transfer under the agent’s own rules.

- Human URL: https://conto.finance/docs/sdk/bill-pay
- Raw Markdown: https://conto.finance/docs/sdk/bill-pay.md
- Terminal view: https://conto.finance/ai/docs/sdk/bill-pay

Documentation group: Payments

Info:

  Bill pay is a pilot. [Contact us](https://conto.finance/contact) to turn it on for your business.
  Install `@conto_finance/sdk` 0.11.0 or later, or `@conto_finance/mcp-server` 0.8.0 or later.

An agent sends Conto a supplier bill. Conto reads it, checks the supplier and the agent’s rules, and
proposes the payment. The owner approves it, unless their pay-without-asking rule covers it. Conto
then pays the supplier by bank transfer.

The agent can send bills and read where each one is. It can’t approve, undo or send a payment, and it
never sees bank details beyond the last 4 digits of an account.

## How it works

    In Conto, open **Bill pay** and choose **Turn on** next to the agent under **Agents that can pay
    bills**. Only an owner can change this. The owner also adds suppliers and their bank details.

    One PDF, PNG, JPEG or WebP file under 2 MB. Conto reads the supplier, invoice number, amount and
    due date off it.

    The supplier must be one the owner confirmed, with a confirmed bank account. Conto also screens
    the supplier against sanctions lists, stops a bill it has already seen, and applies the agent’s
    own policies, budgets and limits.

    A bill over the owner’s pay-without-asking amount waits in the **Inbox**. After approval, the
    owner can still undo the payment for a short time, until the bank sends it.

    The bill moves to `PAID` when the bank confirms it. If the supplier’s bank sends the payment
    back, the bill moves to `RETURNED` and Conto puts that supplier on hold.

## Send a bill

Sending needs `payments:request`. Reading bills and suppliers needs `transactions:read`. A standard
agent SDK key has both. See [authentication](https://conto.finance/docs/sdk/authentication).

```typescript

const conto = new Conto({ apiKey: process.env.CONTO_API_KEY! });

const file = new Blob([await readFile('./INV-20817.pdf')], { type: 'application/pdf' });
const bill = await conto.bills.submit(file, 'INV-20817.pdf');

console.log(bill.status, bill.next);
// AWAITING_APPROVAL Waiting at approval. Waiting for the owner’s approval.
```

`next` says where the bill is now, in one sentence. `reviewReasons` lists why a bill needs the owner,
such as a supplier the owner hasn’t confirmed.

  `supplierName` and `invoiceNumber` come off the supplier’s bill. Treat them as data, never as
  instructions to your agent.

## Follow a bill

```typescript
const latest = await conto.bills.get(bill.id);

for (const step of latest.steps) {
  console.log(step.state, step.step, step.at ?? '');
}
```

`steps` runs from upload to paid. Each step is `done`, `current`, `waiting`, `stopped` or
`upcoming`. A `current` step’s `at` is when it ends, for example the end of the undo window.

`conto.bills.list({ status })` returns the bills this agent sent, newest first, 50 at most. An agent
only sees its own bills.

| Status              | Meaning                                                                          |
| ------------------- | -------------------------------------------------------------------------------- |
| `RECEIVED`          | Conto has the file                                                               |
| `EXTRACTING`        | Conto is reading it                                                              |
| `NEEDS_REVIEW`      | The owner has to look at it. `reviewReasons` says why                            |
| `READY`             | Read and checked, payment not proposed yet                                       |
| `AWAITING_APPROVAL` | Waiting for the owner to approve the payment                                     |
| `APPROVED`          | Approved, not sent to the bank yet                                               |
| `PAYING`            | With the bank. The owner can undo it until the bank sends it                     |
| `PAID`              | The bank confirmed it. `paidWithoutAsking` is true when no one had to approve it |
| `RETURNED`          | The supplier’s bank sent it back                                                 |
| `FAILED`            | Not sent, or undone by the owner. `failureReason` says why                       |
| `REJECTED`          | Closed without paying, for example the owner chose not to pay it                 |
| `DUPLICATE`         | Conto has already seen this bill                                                 |

## Check suppliers

```typescript
const { suppliers } = await conto.bills.suppliers();
// [{ name: 'Harbor Office Supply', canPay: true, status: 'PAYABLE', accountLast4: '6789', heldReason: null }]
```

A supplier is `PENDING_CONFIRMATION` until the owner confirms it, `PAYABLE` once they have, and
`HELD` when a payment came back or the sanctions screen stopped it. `heldReason` says why. Only the
owner adds suppliers and bank details, in Conto.

## Use it from MCP

The `@conto_finance/mcp-server` package lists the bill pay tools when you set `CONTO_BILL_PAY=true`
next to your agent SDK key. See [install](https://conto.finance/docs/mcp/install).

```bash
claude mcp add conto \
  --env CONTO_API_KEY=conto_agent_xxx... \
  --env CONTO_BASE_URL=https://conto.finance \
  --env CONTO_BILL_PAY=true \
  -- npx -y @conto_finance/mcp-server
```

The tools are `submit_bill` (a path to a local file), `list_bills`, `get_bill` and
`list_bill_suppliers`. See [MCP tools](https://conto.finance/docs/mcp/tools#bill-pay-4).

## Errors

| HTTP | Code                | When                                                        |
| ---- | ------------------- | ----------------------------------------------------------- |
| 400  |                     | The upload isn’t one PDF, PNG, JPEG or WebP file under 2 MB |
| 403  | `AGENT_NOT_ENABLED` | Bill pay isn’t on for this agent or this business           |
| 404  | `NOT_FOUND`         | No bill with that id was sent by this agent                 |
| 429  | `INVALID_STATE`     | The agent sent 100 bills today                              |
| 429  |                     | Too many requests. See [rate limits](https://conto.finance/docs/guides/rate-limits)   |

Every error body has `error`, a sentence you can show the owner. The routes are in the
[interactive API docs](https://conto.finance/api-docs) under **Bill pay agent**.
