> ## 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.

# Deposit a Check

> Deposit a customer check into Nickel Banking and mark the invoices it pays

A customer mailed you a check for two invoices. This guide deposits it into your Nickel Banking account from photos of its front and back, marks both invoices paid in the same request, and follows the deposit until the bank settles it. For accounts, deposit states and what applying a deposit means, see [How Nickel Banking Works](/concepts/nickel-banking).

<Info>
  **Before you start**: You need a sandbox API key (see the
  [Quickstart](/guides/quickstart)), an open Nickel Banking account, and a
  photo of each side of the check. The key's team member needs permission to
  deposit into Nickel Banking and to see its deposits.
</Info>

<Warning>
  Amounts are always in cents. A check for \$1,550.55 is `155055`.
</Warning>

<Note>
  In the API, an invoice is a **payment link** (`/paymentLink`). This guide
  says "invoice" in prose and keeps the API's names in paths and fields.
</Note>

<Steps>
  <Step title="Find the account">
    An organization can have more than one Nickel Banking account, so every deposit names the one it goes into. List them with [`GET /nickelBanking/accounts`](/api-reference/nickel-banking/list-nickel-banking-accounts):

    ```bash theme={null}
    curl https://rest.staging.nickel.com/nickelBanking/accounts \
      -H "Authorization: Bearer $NICKEL_SANDBOX_KEY"
    ```

    The response below is illustrative:

    ```json theme={null}
    {
      "accounts": [
        {
          "id": "cmf1nba0001qz8x4k2v7c9d3e",
          "nickname": "Operating",
          "accountNumberLastFour": "6789",
          "balanceCents": 1250000,
          "pendingCardHoldsCents": 0,
          "createdAt": "2026-09-01T15:30:00.000Z"
        }
      ]
    }
    ```

    Keep the account's `id`. A `403` here means the key can't see Nickel Banking; its `code` and message say why.
  </Step>

  <Step title="Deposit the check and apply it">
    Send both photos with [`POST /nickelBanking/checkDeposits`](/api-reference/nickel-banking/deposit-a-check) as `multipart/form-data`. Give the check's amount exactly as written on it. `applications` is a JSON array of the invoices the check pays: here \$1,000.00 to one and \$550.55 to another.

    ```bash theme={null}
    curl -X POST https://rest.staging.nickel.com/nickelBanking/checkDeposits \
      -H "Authorization: Bearer $NICKEL_SANDBOX_KEY" \
      -F front=@check-front.jpg \
      -F back=@check-back.jpg \
      -F accountId=cmf1nba0001qz8x4k2v7c9d3e \
      -F amountCents=155055 \
      -F payerName="Acme Corp" \
      -F 'applications=[{"paymentLinkId":"cmq7ab3cd000gsf02e5f6g7h8","amountCents":100000},{"paymentLinkId":"cmq7ab3cd000gsf02e5f6g7h9","amountCents":55055}]'
    ```

    The response below is illustrative:

    ```json theme={null}
    {
      "checkDeposit": {
        "id": "cmf2dep0001qz8x4k2v7c9d3e",
        "transferId": "cmf2nbt0001qz8x4k2v7c9d3e",
        "accountId": "cmf1nba0001qz8x4k2v7c9d3e",
        "amountCents": 155055,
        "status": "PROCESSING",
        "payerName": "Acme Corp",
        "depositedAt": null,
        "unappliedAmountCents": 0,
        "applications": [
          { "id": "cmr9zx1bq000gsf02h1d5w4t8", "amountCents": 100000, "paymentLinkId": "cmq7ab3cd000gsf02e5f6g7h8", "voided": false, "voidReason": null },
          { "id": "cmr9zx1bq000gsf02h1d5w4t9", "amountCents": 55055, "paymentLinkId": "cmq7ab3cd000gsf02e5f6g7h9", "voided": false, "voidReason": null }
        ],
        ...
      }
    }
    ```

    Both invoices read paid as soon as this returns, even though the check is still `PROCESSING`. If any application is refused, for example because it's more than an invoice has left to pay, nothing is deposited and the response says which.

    <Tip>
      Retrying is safe. The photos identify the check, so sending the same two
      photos again returns this deposit and nothing reaches the bank twice.
      Applications sent with a repeat aren't written, so check `applications` on
      what comes back.
    </Tip>
  </Step>

  <Step title="Or apply it later">
    If you don't know which invoices a check pays when you deposit it, leave out `applications` and apply the deposit afterward with [`POST /nickelBanking/checkDeposits/{checkDepositId}/apply`](/api-reference/nickel-banking/apply-a-check-deposit-to-a-payment-link):

    ```bash theme={null}
    curl -X POST https://rest.staging.nickel.com/nickelBanking/checkDeposits/cmf2dep0001qz8x4k2v7c9d3e/apply \
      -H "Authorization: Bearer $NICKEL_SANDBOX_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "paymentLinkId": "cmq7ab3cd000gsf02e5f6g7h8",
        "amountCents": 100000,
        "externalReferenceId": "apply_8f3a2c"
      }'
    ```

    The response has the same shape as recording an external payment: the new `externalPayment`, with `nickelBankingTransferId` set to the deposit's `transferId`, and the updated `paymentLink`.

    Always send an `externalReferenceId`. If the request times out and you retry with the same one, Nickel returns the application it already made instead of applying the deposit twice.

    <Warning>
      Don't also record the check with
      [`POST /paymentLink/{paymentLinkId}/externalPayment`](/api-reference/payment-link/record-an-external-payment-on-a-payment-link).
      The money is already in your account, and recording it as outside money too
      counts the same check twice.
    </Warning>
  </Step>

  <Step title="Follow the deposit">
    The deposit stays `PROCESSING` while the bank reviews the check, and a deposited check can still be reversed after that. Rather than polling, let Nickel tell you: each change below sends a webhook to the endpoint you registered in [Receive webhooks](/guides/receive-webhooks).

    | Event | Status | What to do |
    | - | - | - |
    | `check_deposit.deposited` | `DEPOSITED` | The money is yours. `depositedAt` says when it settled. |
    | `check_deposit.rejected` | `REJECTED` | The bank refused the check. Nickel voids its applications and the invoices reopen. Deposit it again or ask for a new check. |
    | `check_deposit.returned` | `RETURNED` | The bank reversed the check after depositing it, and the money leaves the account again. The applications are voided the same way. |

    The event carries only the deposit's `id`. Fetch its current state with [`GET /nickelBanking/checkDeposits/{checkDepositId}`](/api-reference/nickel-banking/get-a-check-deposit-by-id), which answers in the same shape as the deposit above:

    ```bash theme={null}
    curl https://rest.staging.nickel.com/nickelBanking/checkDeposits/cmf2dep0001qz8x4k2v7c9d3e \
      -H "Authorization: Bearer $NICKEL_SANDBOX_KEY"
    ```

    A voided application's `voidReason` says which of these happened. To catch up after your endpoint was down, list deposits with [`GET /nickelBanking/checkDeposits`](/api-reference/nickel-banking/list-check-deposits), filtered by `status`; to find the ones that still have money to apply, filter with `unappliedOnly=true`.
  </Step>
</Steps>

## Where to go next

<Columns cols={2}>
  <Card title="How Nickel Banking works" href="/concepts/nickel-banking" icon="building-columns">
    Accounts, balances, deposits and transactions.
  </Card>

  <Card title="Send an invoice" href="/guides/send-an-invoice" icon="file-invoice">
    Create the payment links a check pays.
  </Card>

  <Card title="Receive webhooks" href="/guides/receive-webhooks" icon="bolt">
    Register the endpoint the deposit's events go to.
  </Card>
</Columns>