Skip to main content
This is the accounts-payable workflow end to end: set up the vendor and how they get paid, record the bill, pay it from one of your payment methods on file, and track the money until it arrives. For the objects involved and the payment lifecycle, see How Bill Payments Work.
Before you start: You need a sandbox API key (see the Quickstart) and at least one funding source on file — the bank accounts and cards you’ve connected in the Nickel dashboard. Step 4 shows where to add one. Amounts are in cents throughout.
1

Create the vendor

A vendor is who you pay. Create one with POST /vendor:
Pass "syncToQbo": true to also create the vendor in QuickBooks Online if your account has it connected — see QuickBooks.
2

Add a delivery method

A delivery method is how the vendor receives funds. Set it yourself if you have their details — or better, let the vendor enter their own bank details so you never handle them.
These endpoints return only {"vendorId": "..."} — not the delivery method. Fetch the vendor to get the vendorDeliveryMethods[].id you’ll need when paying:
3

Create the bill

Record what you owe with POST /bill:
Bill dates are epoch milliseconds (1785542400000 is 2026-08-01), unlike invoices which use YYYY-MM-DD strings. Mixing them up creates bills due in 1970.
Note the naming shift: the billNumber you send comes back as reference. A new bill is Open and flips to Paid once a payment covers it; scheduling alone doesn’t change it (see step 5). A non-null scheduledWithdrawalDate is what signals a queued payment.
4

Pick your funding source

A funding source is one of your own payment methods — the bank account or card the bill is paid from. Funding sources are added in the dashboard, not through the API: in the Nickel dashboard, go to Settings → Bill Pay and click Add new, then either connect a bank account (Nickel walks you through linking it with Plaid) or enter a credit card.Once added, list the payment methods your organization can pay from with GET /billPaymentMethods:
The id is the merchantPaymentMethodId for the next step.
5

Pay it

POST /bill/pay is a batch: each item names the bill, the vendor, your funding source, the vendor’s delivery method, and who to notify:
Always send an idempotencyKey. If the request times out and you retry with the same key, Nickel won’t pay the same bills twice.
Two things to handle in the response:
  • Per-bill failures land in billErrors[] ({billId, error}) while valid items still go through — check it on every call. Bills that are already paid, or that already have a pending scheduled payment, are reported here too (they no longer fail the whole batch) and are omitted from billPayments[] so any pre-existing payments on those bills aren’t surfaced as if this batch created them.
  • Batch-level problems — like malformed input — fail the whole request with a top-level {"error": "..."} instead.
Scheduling: add withdrawalDateEpochMillis (when to debit you) or arrivalDateEpochMillis (when it should reach the vendor — Nickel back-computes the withdrawal date from the payment rail’s delivery time; dates too soon for the rail are rejected). A scheduled item creates no bill payment until the withdrawal day — instead the response acknowledges it in scheduled:
While it’s pending, GET /bill/{billId} reports the day in scheduledWithdrawalDate; the bill keeps its status and full amountDueInCents, because nothing has moved yet. No webhook fires at scheduling time. On the withdrawal day the payment executes and rejoins the flow below — a real bill payment appears and bill_payment.succeeded or bill_payment.failed fires. A failed scheduled payment is not retried: the bill stays payable and you submit a new POST /bill/pay. See Scheduled payments for the full contract.
6

Track it

Poll GET /billPayment/{billPaymentId} or subscribe to webhooks: bill_payment.succeeded, bill_payment.failed, and bill_payment.cancelled, plus the check lifecycle (check.sent → check.delivered → check.deposited, with check.returned / check.failed for problems) when paying by mailed check. An ACH bill payment sits in PENDING while the debit and transfer run their course — see the lifecycle.
7

Cancel if you need to

A payment that hasn’t been sent to the payment network yet can be stopped with POST /billPayment/{billPaymentId}/cancel:
A cancelled payment currently reports status: "FAILED" — the same terminal status as a genuine failure. Use the bill_payment.cancelled webhook (or the fact that you called cancel) to tell the two apart.
A scheduled payment has no bill payment to cancel yet — cancel it through its bill instead with POST /bill/{billId}/cancelScheduledPayment:
The response is the refreshed bill — still payable, with scheduledWithdrawalDate back to null. A 404 means there’s no pending scheduled payment to cancel: it never existed, it already executed, or it was already cancelled (cancellation emits no webhook, so check GET /bill/{billId} when in doubt).
Bills and bill payments you create through the API are never written to QuickBooks. Paying a bill that was imported from QuickBooks is — see QuickBooks for the full table.

​
Where to go next

Collect vendor bank details

Let vendors enter their own details on a secure form.

Receive webhooks

Hear about bill_payment and check events as they happen.

How bill payments work

The objects and lifecycle behind this guide.

QuickBooks

What does and doesn’t appear in your books.