How Bill Payments Work

Bill payments are the accounts-payable side of Nickel: you record what you owe a vendor as a bill, then pay it from one of your payment methods on file. Nickel moves the money to the vendor by ACH, mailed check, or international wire (SWIFT), and notifies you (and optionally the vendor) as the payment progresses. International wire payments incur a $20 fee, collected as a separate ACH debit from your funding source.

​

Objects

​

Paying a bill end to end

The flow is: create the vendor → add a delivery method (or let the vendor add their own) → record the bill → pay it from a funding source with POST /bill/pay → track it via GET /billPayment/{billPaymentId} and the bill_payment.* / check.* webhooks. Pay a Vendor Bill walks through every step with real requests and responses.

​

Scheduled payments

Paying a bill with a future withdrawal date does not create a bill payment yet — it queues a scheduled payment that executes on the withdrawal day. The POST /bill/pay response acknowledges it in a scheduled array ({ billId, withdrawalDate }) rather than billPayments, and withdrawalDate is the calendar day (US Eastern) the debit occurs — the exact time of day is not part of the contract. A bill can have at most one pending scheduled payment. While one is pending:

• GET /bill/{billId} reports the day it will execute in scheduledWithdrawalDate. Note that the bill also reports status: Paid even though no money has moved yet — treat a non-null scheduledWithdrawalDate as “scheduled, not settled”.
• Paying the bill again fails into billErrors[] with an “already been paid or has a pending scheduled payment” error. If you are retrying a POST /bill/pay request that may have partially succeeded, treat that error as confirmation the schedule exists and verify with GET /bill/{billId}.
• No webhook fires at scheduling time — the response acknowledgment and GET /bill/{billId} are the signals that a payment is queued.

On the withdrawal day the payment executes and rejoins the normal flow: a real bill payment is created and bill_payment.succeeded or bill_payment.failed fires. A payment that fails on its withdrawal day (for example, insufficient funds) is not retried: the bill returns to Open, scheduledWithdrawalDate returns to null, and the failed payment remains visible via GET /billPayment/{billPaymentId}. Submit a new POST /bill/pay request to try again. To cancel a scheduled payment before it executes, call POST /bill/{billId}/cancelScheduledPayment. The response is the refreshed bill — status back to Open and scheduledWithdrawalDate null. A 404 means the bill has no pending scheduled payment: it never had one, it already executed, or it was already cancelled. Cancellation emits no webhook, and a scheduled payment can also be cancelled from the Nickel dashboard — so an integration that must know a bill’s current state should check GET /bill/{billId} rather than assume the schedule it created is still pending.

​

Bill payment lifecycle

A bill payment starts as CREATED, moves to PENDING once the debit from your payment method has been initiated, and ends in SUCCEEDED when the vendor receives the funds or FAILED if the movement fails (for example, an ACH return). Check payments report their delivery progress through the check.* webhook events between debit and deposit.

​

Stopping a check payment

POST /billPayment/{billPaymentId}/cancel only works before a check is cut. To pull back a check that has already been issued, call POST /billPayment/{billPaymentId}/stopPayment. Nickel cancels the check if it hasn’t been mailed yet, or places a stop payment with the bank if it has. Either way you’re refunded automatically: the bill payment moves to REFUNDED, the bill returns to unpaid, and any connected QuickBooks bill payment is voided. Timing is the constraint. A stop payment works right up until the vendor deposits the check — once it’s deposited the money is gone and the request returns 400. Because a check can be deposited at any time, don’t treat a still-outstanding check as recoverable: stop it as soon as you know it’s wrong. If your account has QuickBooks connected, see QuickBooks for which of these objects appear in your books — in short, API-created bills and their payments never do.