In the API, an invoice is a payment link (
/paymentLink). This page says “invoice” in prose and keeps the API’s names in paths and fields.Objects
To pay a bill from Nickel Banking, pass the account’s
NickelBalance payment method from GET /billPaymentMethods to POST /bill/pay. How Bill Payments Work covers the rest.
Who can read it
An API key acts as the team member who created it, with that member’s role. A key created with a role of its own has only what both roles allow. Nickel Banking has its own permissions: seeing balances, seeing cards and seeing deposits are granted separately, so a key can read one list and not another. When a list would come back empty because the key can’t see it, Nickel answers403 instead. An empty list therefore always means there is nothing to show.
Opening more accounts
Your organization opens its first Nickel Banking account in the Nickel dashboard. That’s where the business accepts the bank’s terms, and the acceptance covers every account after it. (A business that uses Nickel through a platform partner accepts the terms on a page Nickel hosts instead, and the platform opens its first account with this same request.) Once the first is open, open more withPOST /nickelBanking/accounts, for example one for payroll and one for taxes:
GET /nickelBanking/accounts lists it. accountNumberLastFour can be null for a moment while the bank finishes opening it.
Always send an idempotencyKey. If the request times out and you retry with the same key, Nickel answers the account the first request opened instead of opening a second one. The key needs two permissions: “Can apply for a Nickel Banking account for the Organization” and “Can see Nickel Banking balance”. An organization can have up to 10 accounts.
Balances
balanceCents is the account’s settled balance. It is Nickel’s record of the account’s ledger, updated as transactions post, not a live read from the bank. It is negative when the account is overdrawn.
Card purchases the bank has approved but not yet posted are held against the account in pendingCardHoldsCents. balanceCents doesn’t include them, so what the account can spend right now is balanceCents minus pendingCardHoldsCents.
Before paying a bill, check the account’s spendableCents on GET /billPaymentMethods instead: it also subtracts money already committed to other payments, and a bill payment larger than it fails.
Check deposits
You deposit a check by sending photos of its front and back toPOST /nickelBanking/checkDeposits, or from the Nickel dashboard. The photos identify the check: sending the same two again returns the deposit they already made instead of depositing the check twice. Deposit a Check walks through it.
A deposit is PROCESSING while the bank reviews the check. It becomes DEPOSITED once the money is yours, or REJECTED if the bank refuses it. A deposited check can still come back: if the bank reverses it, the deposit becomes RETURNED and the money leaves the account again. returnReason and rejectionReason carry the bank’s explanation.
Nickel sends a webhook each time a deposit leaves PROCESSING or is returned: check_deposit.deposited, check_deposit.rejected and check_deposit.returned. Each names the deposit, and you fetch its current state by id. Webhook Events says what to do on each.
Applying a deposit to an invoice
A deposited check that pays one of your invoices is applied to it, either in the same request that deposits it (applications) or afterward with POST /nickelBanking/checkDeposits/{checkDepositId}/apply. No new money is recorded, because the money is already in your account. Send an externalReferenceId when you apply one afterward, so a retried request can’t apply the deposit twice. Each application appears in two places: in the deposit’s applications, and in the invoice’s externalPayments with nickelBankingTransferId set to the deposit’s transferId. unappliedAmountCents on the deposit is what is left to apply.
To unapply a deposit, for example when it went to the wrong invoice, void the application with POST /paymentLink/{paymentLinkId}/externalPayment/{externalPaymentId}/void, passing the application’s id. The money stays in your account and its unappliedAmountCents goes back up.
Nickel also voids applications itself. If the bank returns or rejects the check, every application is voided and the invoices reopen. If the bank accepts less than the check’s amount, the newest applications are voided until what is applied fits. Each voided application’s voidReason says which happened.
Debit Protection
With Debit Protection on, Nickel holds every third-party ACH debit on the account, any pull another company makes, for your decision before it posts. Turn it on or off per account withPUT /nickelBanking/accounts/{accountId}/debitProtection. debitProtectionEnabled on the account says whether it’s on.
A held debit waits in PENDING_DECISION until decideBy, a few minutes before the bank would accept it on its own. Nickel sends held_debit.held when it holds one. Then you:
- Allow it. The bank accepts it on its own schedule. Send
"alwaysAllowCompany": trueto also stop holding that company’s later debits. - Block it. The bank declines it as “payment stopped”, and the money stays in the account.
companyId on a held debit). List them with GET /nickelBanking/accounts/{accountId}/allowedCompanies, add one with POST to the same path, and remove one with DELETE /nickelBanking/allowedCompanies/{allowedCompanyId}. A debit from an allowed company has status AUTO_ALLOWED, and no event is sent for it.
Turning Debit Protection off allows every debit still held on the account, and sends held_debit.allowed for each.
To try each outcome before you go live, have a company pull a debit in the sandbox, as Testing Debit Protection shows.
Reading held debits and allowed companies needs “Can see Nickel Banking balance”. Deciding a hold, turning Debit Protection on or off, and changing allowed companies need “Can withdraw from Nickel Banking account” too.
Transactions
GET /nickelBanking/transactions lists every movement of money into, out of, or on its way to your Nickel Banking accounts, newest first. Filter it to one account with accountId, to one card with cardId, or to a date range with startDate and endDate, which must be sent together.
amountCents is always positive. The type says what the money was:
Nickel adds types as the product grows, so handle a
type you don’t recognize instead of failing on it.
A PENDING card purchase is a hold: the bank approved it but it hasn’t posted, and its amount can still change when it does.
A transaction’s status doesn’t change when the money is later reversed. A customer ACH payment that settled stays COMPLETED after the bank returns it; the return is marked in its flags and listed as its own RETURN transaction. Treat a COMPLETED transaction as money you kept only when flags is empty.
This request lists one account’s transactions for September. The response is illustrative:
totalResults counts every matching transaction across pages. Page through the rest with page and pageSize.