> ## Documentation Index
> Fetch the complete documentation index at: https://dev.nickel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How Nickel Banking Works

> Read your Nickel Banking accounts, debit cards, check deposits and transactions through the API

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.

<Warning>
  Amounts are always in cents. `balanceCents: 1250000` is \$12,500.00.
</Warning>

<Note>
  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.
</Note>

## Objects

| Object | What it represents |
| - | - |
| Account | One Nickel Banking account and its balance. An organization can have several. Listed by [`GET /nickelBanking/accounts`](/api-reference/nickel-banking/list-nickel-banking-accounts). |
| Card | A debit card that spends from one account. Listed by [`GET /nickelBanking/cards`](/api-reference/nickel-banking/list-nickel-banking-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`](/api-reference/nickel-banking/deposit-a-check), listed by [`GET /nickelBanking/checkDeposits`](/api-reference/nickel-banking/list-check-deposits), and read one at a time by [`GET /nickelBanking/checkDeposits/{checkDepositId}`](/api-reference/nickel-banking/get-a-check-deposit-by-id). |
| Transaction | One movement of money into, out of, or on its way to an account. Listed by [`GET /nickelBanking/transactions`](/api-reference/nickel-banking/list-nickel-banking-transactions). |

To pay a bill from Nickel Banking, pass the account's `NickelBalance` payment method from [`GET /billPaymentMethods`](/api-reference/bill-payment-method/list-bill-payment-methods) to [`POST /bill/pay`](/api-reference/bill/pay-bills). [How Bill Payments Work](/concepts/bill-payments) 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`](/api-reference/bill-payment-method/list-bill-payment-methods) 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`](/api-reference/nickel-banking/deposit-a-check), 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](/guides/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](/concepts/webhooks) 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`](/api-reference/nickel-banking/apply-a-check-deposit-to-a-payment-link). 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.

<Warning>
  Don't also record a Nickel Banking check deposit with [`POST /paymentLink/{paymentLinkId}/externalPayment`](/api-reference/payment-link/record-an-external-payment-on-a-payment-link). The application already counts it. Recording it again counts the same check twice and marks the invoice paid when it isn't.
</Warning>

To unapply a deposit, for example when it went to the wrong invoice, void the application with [`POST /paymentLink/{paymentLinkId}/externalPayment/{externalPaymentId}/void`](/api-reference/payment-link/void-an-external-payment-on-a-payment-link), 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`](/api-reference/nickel-banking/list-nickel-banking-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:

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

```json theme={null}
{
  "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`.