Deposit a Check

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.

Before you start: You need a sandbox API key (see the 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.

Amounts are always in cents. A check for $1,550.55 is 155055.

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.

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:

curl https://rest.staging.nickel.com/nickelBanking/accounts \
  -H "Authorization: Bearer $NICKEL_SANDBOX_KEY"

The response below is illustrative:

{
  "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.

Deposit the check and apply it

Send both photos with POST /nickelBanking/checkDeposits 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.

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:

{
  "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.

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.

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:

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.

Don’t also record the check with POST /paymentLink/{paymentLinkId}/externalPayment. The money is already in your account, and recording it as outside money too counts the same check twice.

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.

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}, which answers in the same shape as the deposit above:

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, filtered by status; to find the ones that still have money to apply, filter with unappliedOnly=true.

Getting Started

Core Concepts

Getting Paid

Paying Bills

Webhooks

Where to go next

How Nickel Banking works

Send an invoice

Receive webhooks

​Where to go next

How Nickel Banking works

Send an invoice

Receive webhooks

Where to go next