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

# Testing in the Sandbox

> Test card numbers, test bank details, how to make a sandbox payment settle, fail or come back, and how to fund a Nickel Banking account and test Debit Protection.

The sandbox, `https://rest.staging.nickel.com`, runs the same API as production with no real money behind it. Card payments go to a card processor's test environment, and bank (ACH) payments go to a test bank. This page gives you the card numbers and bank details to pay with, and the amounts and words that make a payment fail, settle or come back, so you can build against each outcome in minutes instead of days.

> [!NOTE]
>
> Prose on this page says **invoice**. In the API, an invoice is a `paymentLink`.

## Paying an invoice in the sandbox

Create an invoice as [Send an Invoice and Get Paid](https://dev.nickel.com/guides/send-an-invoice.md) shows, then open its `url` in a browser. That's the checkout page your customer would see. Pay it with the card numbers or bank details below.

Use an email address you control, or one at `example.com`, as the payer's email. Nickel sends the payer a receipt, as it would in production.

## Card payments

Enter any future expiry date and any three-digit CVV with these cards.

| Card number | What happens |
| - | - |
| `4111 1111 1111 1111` | The charge succeeds. The payment is `SUCCEEDED` straight away. |
| `4023 8984 9398 8028` | The charge succeeds, then your customer disputes it within a few minutes. |

A card is declined by the amount charged, not by its number. Any charge between \$2,000.00 and \$2,999.99 is declined. The amount charged includes your customer's share of the platform fee, so check the total on the **Pay** button. A \$2,750.00 invoice with a 2.9% share comes to \$2,829.75, and is declined.

A declined card leaves the payment `FAILED`, sends no webhook event, and leaves the invoice open. Your customer sees the decline on the checkout page and can pay with another card.

### Testing a disputed payment

A **dispute**, or chargeback, is your customer asking their card issuer to take a card payment back. Pay with `4023 8984 9398 8028` to test one. The charge succeeds, and a few minutes later the dispute opens:

* The payment moves from `SUCCEEDED` to `FAILED`, and Nickel sends `payment.disputed`.
* The invoice reopens, so your customer can pay it again.

[Webhook events](https://dev.nickel.com/concepts/webhooks.md#payment-disputed) explains what to do when a dispute opens.

## Bank (ACH) payments

On the checkout page, choose **Pay by Bank** and enter any valid routing number, such as `021000021`, with any account number.

In production, a bank payment takes a few business days to settle. In the sandbox it settles about 15 to 20 minutes after your customer pays, so you can follow the whole lifecycle in one sitting:

1. Your customer pays. The payment is `PENDING`, and Nickel sends `payment.made`.
2. About 15 to 20 minutes later, the debit settles. The payment is `SUCCEEDED`, and Nickel sends `payment.succeeded`.

### Testing a returned payment

A customer's bank can return a bank payment after it settles, for example when the account has insufficient funds. To test a return, put the word `return`, in lowercase, in the invoice's `memo` when you [create the invoice](https://dev.nickel.com/api-reference/payment-link/create-a-new-payment-link.md). When your customer pays it by bank, the payment settles and is then returned:

* The payment ends `FAILED`, and Nickel sends `payment.failed`. You may receive `payment.succeeded` first, so act on the status you fetch, not on the order events arrive in.
* The invoice reopens, so your customer can pay it again.

The memo is shown to your customer on the checkout page, and the word only triggers a return in the sandbox.

## Nickel Banking

### Adding money to an account

A new sandbox account has no money in it. To add some, have another company send it an ACH credit with [`POST /sandbox/nickelBanking/accounts/{accountId}/inboundAchCredits`](https://dev.nickel.com/api-reference/sandbox/simulate-an-ach-credit-from-another-company):

```bash theme={null}
curl -X POST https://rest.staging.nickel.com/sandbox/nickelBanking/accounts/cmf1nba0001qz8x4k2v7c9d3e/inboundAchCredits \
  -H "Authorization: Bearer $NICKEL_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents": 50000}'
```

`amountCents` is in cents, so `50000` is \$500.00. The sandbox bank accepts the credit at once, and the account's `balanceCents` rises within a few seconds, once Nickel books it.

### Testing Debit Protection

[Debit Protection](https://dev.nickel.com/concepts/nickel-banking.md#debit-protection) holds an ACH debit when another company, such as a payroll provider, a tax agency or a vendor on autopay, pulls money from a Nickel Banking account. In production only that company can start one. In the sandbox, you start one yourself with [`POST /sandbox/nickelBanking/accounts/{accountId}/inboundAchDebits`](https://dev.nickel.com/api-reference/sandbox/simulate-an-ach-debit-from-another-company).

**1. Turn Debit Protection on**

```bash theme={null}
curl -X PUT https://rest.staging.nickel.com/nickelBanking/accounts/cmf1nba0001qz8x4k2v7c9d3e/debitProtection \
  -H "Authorization: Bearer $NICKEL_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

**2. Have a company pull a debit**

Name the company and its ACH Company ID, as a real debit would carry them. Both are optional:

```bash theme={null}
curl -X POST https://rest.staging.nickel.com/sandbox/nickelBanking/accounts/cmf1nba0001qz8x4k2v7c9d3e/inboundAchDebits \
  -H "Authorization: Bearer $NICKEL_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents": 1234, "companyName": "Gusto Payroll", "companyId": "1943827561", "entryDescription": "PAYROLL"}'
```

Nickel answers `201` with what it sent the sandbox bank:

```json theme={null}
{
  "simulatedDebit": {
    "accountId": "cmf1nba0001qz8x4k2v7c9d3e",
    "amountCents": 1234,
    "companyName": "GUSTO PAYROLL",
    "companyId": "1943827561",
    "entryDescription": "PAYROLL",
    "automaticallyResolvesAt": "2026-11-10T23:04:10.000Z"
  }
}
```

`amountCents` is in cents, so `1234` is \$12.34. The debit stays pending for 20 minutes, until `automaticallyResolvesAt`.

**3. Decide the hold**

Within a few seconds, Nickel holds the debit and sends [`held_debit.held`](https://dev.nickel.com/concepts/webhooks#held_debit-held). Fetch the held debit, then [allow](https://dev.nickel.com/api-reference/nickel-banking/allow-a-held-debit.md) or [block](https://dev.nickel.com/api-reference/nickel-banking/block-a-held-debit.md) it. Its `decideBy` is 5 minutes before `automaticallyResolvesAt`, so you have about 15 minutes.

To test each path, pull a debit for each:

* **Allow it.** Nickel sends `held_debit.allowed`. At `automaticallyResolvesAt`, the bank takes the money if the account has it.
* **Block it.** Nickel sends `held_debit.blocked`, and the money stays in the account.
* **Leave it.** At `decideBy`, Nickel blocks it, its `status` becomes `EXPIRED_BLOCKED`, and Nickel sends `held_debit.blocked`.
* **Allow the company.** Allow a hold with `"alwaysAllowCompany": true`, then pull another debit with the same `companyId`. It isn't held: its `status` is `AUTO_ALLOWED`, and no event is sent.
* **Turn Debit Protection off** while a debit is held. Nickel allows it and sends `held_debit.allowed`.

A debit you allow, or one from an allowed company, is declined for insufficient funds when it resolves if the account can't cover it, as it would be in production. That doesn't change the held debit: it stays `ALLOWED` or `AUTO_ALLOWED`. To watch one post, [add money to the account](#adding-money-to-an-account) first.

Production answers this request with `400`.

## Where to go next

> [card] [How payments work](https://dev.nickel.com/concepts/payments.md)
>
> Each payment status, and what moves a payment between them.

> [card] [Webhook events](https://dev.nickel.com/concepts/webhooks.md)
>
> What each payment event means, and what to do when it arrives.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.