How Nickel Banking Works

Nickel Banking is a business bank account you open with Nickel. Customer payments can settle into it, you can pay bills and spend from it with Nickel debit cards, and you can deposit checks into it. The API reads all of it: your accounts and their balances, your cards, the checks you’ve deposited, and every transaction. It also deposits checks and applies them to your invoices. You open accounts and issue cards in the Nickel dashboard.

Amounts are always in cents. balanceCents: 1250000 is $12,500.00.

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

Object	What it represents
Account	One Nickel Banking account and its balance. An organization can have several. Listed by `GET /nickelBanking/accounts`.
Card	A debit card that spends from one account. Listed by `GET /nickelBanking/cards`. The full card number and CVC are never returned.
Check deposit	A check you deposited into an account, and the invoices it paid. Made with `POST /nickelBanking/checkDeposits`, listed by `GET /nickelBanking/checkDeposits`, and read one at a time by `GET /nickelBanking/checkDeposits/{checkDepositId}`.
Transaction	One movement of money into, out of, or on its way to an account. Listed by `GET /nickelBanking/transactions`.

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. 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 answers 403 instead. An empty list therefore always means there is nothing to show.

`code`	What it means	What to do
`NICKEL_BANKING_NOT_ACTIVE`	Your organization doesn’t have an active Nickel Banking account.	Open one in the Nickel dashboard.
`MISSING_PERMISSION`	The team member the key belongs to doesn’t have the permission the list needs. The `error` message names it, for example “Can see Nickel Banking balance”.	Ask an administrator to add the permission to the member’s role, or use a key created by a member who has it.

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 to POST /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.

Don’t also record a Nickel Banking check deposit with POST /paymentLink/{paymentLinkId}/externalPayment. The application already counts it. Recording it again counts the same check twice and marks the invoice paid when it isn’t.

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.

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:

`type`	What it is
`DEPOSIT`	Money in: an ACH or wire sent to the account, a transfer from your linked bank, a deposited check, a card refund.
`WITHDRAWAL`	Money out: a transfer to your linked bank, a card purchase.
`INTEREST`	Interest Nickel paid on the balance. `counterpartyName` is `Nickel`.
`FEE`	A Nickel fee taken from the balance, or given back to it. `amountCents` is the whole fee, even when the balance covered only part of it and the rest was taken later.
`NB_TRANSFER`	Money moved between Nickel Banking accounts: between two of your own, listed once under the account the money left, or to or from another organization’s account.
`RECEIVABLE`	A customer payment that settled, or is settling, into the account. `paymentId` identifies it.
`PAYABLE`	A bill paid from the account. `billPaymentId` identifies it.
`REFUND`	A refund of a customer payment, paid from the account.
`RETURN`	A bank return: of a customer’s ACH payment, which takes the money back out, or of a payment to a vendor, which brings it back in.
`CHARGEBACK`	A disputed customer card payment taken back.
`CHARGEBACK_WON`	A dispute decided in your favor, the money returned.

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:

curl "https://rest.staging.nickel.com/nickelBanking/transactions?accountId=cmf1nba0001qz8x4k2v7c9d3e&startDate=2026-09-01&endDate=2026-09-30" \
  -H "Authorization: Bearer $NICKEL_SANDBOX_KEY"

{
  "transactions": [
    {
      "id": "cmf3act0001qz8x4k2v7c9d3e",
      "type": "WITHDRAWAL",
      "status": "COMPLETED",
      "amountCents": 250000,
      "createdAt": "2026-09-14T16:02:11.000Z",
      "description": "September rent",
      "counterpartyName": "Office Landlord LLC",
      "note": null,
      "flags": [],
      "account": {
        "id": "cmf1nba0001qz8x4k2v7c9d3e",
        "nickname": "Operating",
        "accountNumberLastFour": "6789"
      },
      "paymentId": null,
      "billPaymentId": null
    },
    ...
  ],
  "totalResults": 37
}

totalResults counts every matching transaction across pages. Page through the rest with page and pageSize.

Getting Started

Core Concepts

Getting Paid

Paying Bills

Webhooks

Objects

Who can read it

Balances

Check deposits

Applying a deposit to an invoice

Transactions

​Objects

​Who can read it

​Balances

​Check deposits

​Applying a deposit to an invoice

​Transactions

Objects

Who can read it

Balances

Check deposits

Applying a deposit to an invoice

Transactions