Pay a vendor invoice

An agent can pay a vendor invoice by ACH from one of your accounts. Invoices under your approval threshold will go through without an admin, and invoices at or above it will wait for one. In addition, an idempotency key keeps a retry from paying the same invoice twice.

Example use case

Cora's Coffee has received invoice INV-4471 for $420.00 from Acme Supplies, one of its vendors. Cora's Coffee asks its agent to pay the invoice by ACH from the operating account, using the vendor and the invoice number as the idempotency key (two vendors can use the same invoice number). If the payment is under the approval threshold in the agent's policy, it will go through on its own. If it's at or above it, the agent sends an admin the approval link and waits.

The steps below follow that agent from start to finish:

Find the bank rail → Choose the account → Send → Read the result → Confirm

Requirements

Before you start, you'll need:

• A linked agent: The agent runs each step below with the CLI.
• A verified organization: ACH payments are only available to verified organizations.
• A policy that allows the send: The agent's policy must allow sends from the paying account to the vendor.

Prompt

You can hand the task to your agent with a prompt like this one:

Pay Acme Supplies invoice INV-4471 for $420.00 by ACH from our operating account. Use idempotency key acme-inv-4471. If it needs approval, send me the approval link and wait.

Steps

1. Find the vendor's bank rail

First, the agent looks for the vendor among your counterparties:

catena counterparties list

The agent finds Acme Supplies, picks a rail with type: "bank", and takes its cpr_... ID. If Acme isn't a counterparty yet, the agent can create it from details you give it, or ask Acme for them:

catena counterparties create --name "Acme Supplies" --email billing@acme.example
catena counterparties request-details cp_... --bank

We email Acme a secure form (the request expires after 7 days), and the agent waits until a bank rail appears. The agent must not make up bank details.

2. Choose the source account

Next, the agent chooses the account to pay from and check its balance:

catena accounts list
catena accounts balance acct_...

The agent checks that .balances.available covers the $420.00 invoice.

3. Send the payment

Now the agent can send the payment, passing the invoice number as both the description and the idempotency key:

catena send --account acct_... --rail cpr_... \
  --amount 420.00 --method ach \
  --description "INV-4471" --idempotency-key acme-inv-4471

If the agent runs the same command again with the same key, we will return the same intent (with replayed: true) and will not pay a second time. See Retry safely for more on how retries work.

4. Read the result

Below are the statuses the send may return, and what happens next for each:

5. Confirm the payment

Finally, the agent confirms the payment:

catena intents get int_...

The vendor is paid once the intent's status is completed. .data holds the linked transaction when one is available, and can be null until then. Note that an approved payment still has to be submitted and settle. See Approval and execution for details.

Variations

You can adapt this recipe in a few ways: