Skip to main content
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.
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.
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 about API access. This guide uses a sandbox token against https://rest.staging.nickel.com, so you can experiment freely.
1

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:
export NICKEL_SANDBOX_KEY="nkl_your_sandbox_key_here"
2

Make your first request

List your customers with GET /customers. This is a read-only request, so it’s a safe way to confirm your key works:
curl https://rest.staging.nickel.com/customers \
  -H "Authorization: Bearer $NICKEL_SANDBOX_KEY"
On a fresh account the list is empty:
{ "customers": [], "totalResults": 0 }
If you get a 401 instead — {"error": "Missing or invalid authorization header"} — check that the header reads exactly Authorization: Bearer nkl_....
3

Create a customer

A customer is who you’re billing. Create one with POST /customer — all it needs is a name and at least one email address:
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"]}'

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

Create the invoice

Create the invoice with POST /paymentLink, giving it a name (your invoice number works well), the customer’s id, an amount, and a due date:
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"
  }'
Amounts are always in cents: 12055 is $120.55. Sending 120.55 here would create an invoice for about a dollar.
{
  "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.
5

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 and get notified of the payment by webhook.
The interactive playground on the API Reference pages runs against the sandbox environment too — use your sandbox key there.

​
Where to go next

Send an invoice and get paid

The full workflow: create, send, get paid, get notified.

How payments work

Card vs. ACH, payment statuses, and what happens after your customer pays.

Webhook events

Get notified when a payment lands instead of polling.

Pay a vendor bill

The other direction: paying your vendors through the API.