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

# Quickstart

> Make your first API call and create an invoice in about five minutes

This guide takes you from an API key to a live, payable invoice. You'll make your first request, create a customer, create an invoice for them, and open the checkout page your customer would see — all in the sandbox, where no real money moves.

<Note>
  In the API, an invoice is a **payment link** — the endpoints and field names below say `paymentLink`. Same thing; these guides say "invoice" because that's what your customer sees.
</Note>

<Info>
  **Before you start**: You need an API token. Organizations on the Nickel Pro plan create and manage tokens in the dashboard under **Settings → API** — each token is shown once at creation, so store it securely. If you don't have a Pro plan yet, [get in touch](https://www.nickel.com/integrations/api) about API access. This guide uses a **sandbox** token against `https://rest.staging.nickel.com`, so you can experiment freely.
</Info>

<Steps>
  <Step title="Set up your key">
    Every request carries your API token in the `Authorization` header. Export your sandbox token once so you can copy-paste the commands below as-is:

    ```bash theme={null}
    export NICKEL_SANDBOX_KEY="nkl_your_sandbox_key_here"
    ```
  </Step>

  <Step title="Make your first request">
    List your customers with [`GET /customers`](/api-reference/customer/list-customers). This is a read-only request, so it's a safe way to confirm your key works:

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

    On a fresh account the list is empty:

    ```json theme={null}
    { "customers": [], "totalResults": 0 }
    ```

    If you get a `401` instead — `{"error": "Missing or invalid authorization header"}` — check that the header reads exactly `Authorization: Bearer nkl_...`.
  </Step>

  <Step title="Create a customer">
    A customer is who you're billing. Create one with [`POST /customer`](/api-reference/customer/create-a-customer) — all it needs is a name and at least one email address:

    ```bash theme={null}
    curl -X POST https://rest.staging.nickel.com/customer \
      -H "Authorization: Bearer $NICKEL_SANDBOX_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name": "Acme Landscaping", "emails": ["ap@acmelandscaping.com"]}'
    ```

    ```json theme={null}
    {
      "id": "cmr9zja1s0000sf028pvdtpsh",
      "name": "Acme Landscaping",
      "emails": ["ap@acmelandscaping.com"],
      "achEnabled": null,
      "feePassthroughPercent": 50
    }
    ```

    Hold on to the `id` — the next step uses it. The other fields echo your **organization's** payment settings, not anything you sent: `feePassthroughPercent` is the share of the card processing fee your customers cover, and this sandbox organization is configured to pass 50% through (a new organization starts at 100). You can override these per customer later with [`PUT /customer/{customerId}`](/api-reference/customer/update-a-customer).
  </Step>

  <Step title="Create the invoice">
    Create the invoice with [`POST /paymentLink`](/api-reference/payment-link/create-a-new-payment-link), giving it a name (your invoice number works well), the customer's `id`, an amount, and a due date:

    ```bash theme={null}
    curl -X POST https://rest.staging.nickel.com/paymentLink \
      -H "Authorization: Bearer $NICKEL_SANDBOX_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "INV-123",
        "customerId": "cmr9zja1s0000sf028pvdtpsh",
        "requestedAmountCents": 12055,
        "dueDate": "2026-08-01"
      }'
    ```

    <Warning>
      Amounts are always in **cents**: `12055` is \$120.55. Sending `120.55` here would create an invoice for about a dollar.
    </Warning>

    ```json theme={null}
    {
      "id": "cmr9zjev80002sf027g6f8pdd",
      "name": "INV-123",
      "status": "ACTIVE",
      "url": "https://nickel.staging.nickelpayments.com/pay/vKzQLZwb",
      "payments": [],
      "dueDate": "2026-08-01",
      "customerId": "cmr9zja1s0000sf028pvdtpsh",
      "requestedAmountCents": 12055,
      "completedAmountCents": 0,
      "feePassthroughPercent": null,
      "achEnabled": null,
      "creditCardEnabled": null,
      "amountEditable": false
    }
    ```

    The invoice starts out `ACTIVE` with no payments against it. As your customer pays, `completedAmountCents` climbs and the `status` moves to `COMPLETED`.
  </Step>

  <Step title="See what your customer sees">
    Open the `url` from the response in your browser. That's the hosted checkout page where your customer views the invoice and pays by card or bank transfer — no code required on your side. The subdomain is yours: you choose it when you set up your Nickel account, and this sandbox organization chose `nickel`. Production checkout pages live at `<your-subdomain>.nickelpayments.com`; sandbox ones at `<your-subdomain>.staging.nickelpayments.com`.

    From here you'd typically email the invoice to your customer with [`POST /paymentLink/{paymentLinkId}/send`](/api-reference/payment-link/send-a-payment-link-to-recipients) and get notified of the payment by webhook.
  </Step>
</Steps>

<Note>
  The [interactive playground](/api-reference/payment-link/create-a-new-payment-link) on the API Reference pages runs against the sandbox environment too — use your sandbox key there.
</Note>

## Where to go next

<Columns cols={2}>
  <Card title="Send an invoice and get paid" href="/guides/send-an-invoice" icon="envelope">
    The full workflow: create, send, get paid, get notified.
  </Card>

  <Card title="How payments work" href="/concepts/payments" icon="credit-card">
    Card vs. ACH, payment statuses, and what happens after your customer pays.
  </Card>

  <Card title="Webhook events" href="/concepts/webhooks" icon="bolt">
    Get notified when a payment lands instead of polling.
  </Card>

  <Card title="Pay a vendor bill" href="/guides/pay-a-bill" icon="money-bill-transfer">
    The other direction: paying your vendors through the API.
  </Card>
</Columns>