Skip to main content
This is the core Nickel workflow, end to end: you create an invoice, email it to your customer, they pay on the hosted checkout page, and you confirm the money is on its way. No checkout code, no card handling on your side.
In the API, an invoice is a payment link — the endpoints and field names below say paymentLink. Same thing; this guide says “invoice” because that’s what your customer sees.
Before you start: You need a sandbox API key and a customer to bill. The Quickstart covers both — this guide picks up the same example. Requests below use https://rest.staging.nickel.com.
1

Create the customer

Every invoice belongs to a customer. Create one with POST /customer if they don’t exist yet:
feePassthroughPercent echoes your organization’s setting, not anything you sent: it’s the share of the card processing fee your customers cover. This sandbox organization passes 50% through (a new organization starts at 100) — you’ll see that 50% again when we read the payment’s charged amount below.
If your account has QuickBooks Online connected, pass "syncToQbo": true to also create the customer in QuickBooks. See QuickBooks for exactly what does and doesn’t sync.
2

Create the invoice

Create the invoice with POST /paymentLink. The name is what your customer sees — an invoice number works well:
Amounts are always in cents — 12055 is $120.55.
A few optional fields let you control checkout per invoice — creditCardEnabled and achEnabled toggle payment methods, amountEditable lets the customer change the amount (useful for deposits), and feePassthroughPercent sets how much of the card processing fee the customer covers. Omit them to inherit your customer and organization settings.
3

Attach the invoice PDF (optional)

If you generate a PDF for the invoice, attach it so your customer can view and download it on the payment page. It’s two calls: upload the file, then attach it by ID.Upload the PDF as multipart/form-data to POST /file with type=INVOICE_PDF (PDFs up to 10MB):
Then attach it by sending the file’s id — not the key, and not the file itself — to POST /paymentLink/{paymentLinkId}/uploadPdf as JSON:
The response is the updated invoice.
Files can only be attached by the API key that uploaded them — use the same key for both calls.
4

Send it

Email the invoice to your customer with POST /paymentLink/{paymentLinkId}/send. Nickel sends a payment request email with your branding and the link:
Call this endpoint again to nudge a slow payer — Nickel automatically treats repeat sends to the same recipient as reminders. Omit sendSms to use your organization’s SMS setting for recipients with a phoneNumber.
5

Your customer pays

The email links to the hosted checkout page (the invoice’s url). Your customer sees the invoice details and the attached PDF, and pays by card or bank transfer (ACH) — whichever you’ve left enabled. If you pass part of the card fee through, the checkout shows the customer their share as a line item before they confirm.You don’t need to build anything for this step.
6

Get notified when the payment lands

Subscribe to webhooks and listen for payment.made. The event tells you which payment changed; fetch the full details with GET /payment/{paymentId}:
Reading the money fields: amountInCents is the invoice amount (120.55),‘platformFeeInCents‘isthetotalprocessingfee(120.55), `platformFeeInCents` is the total processing fee (3.50), and chargedAmountInCents is what the customer’s card was actually charged ($122.30 — the invoice plus their half of the fee, since this account passes 50% through).
Card payments show SUCCEEDED right away. Bank (ACH) payments sit in PENDING for a few business days first, and can still fail up to 60 days later if the customer’s bank returns the debit. See How Payments Work before you treat ACH money as final.
7

Confirm the invoice is settled

The invoice tracks its own progress — fetch it any time with GET /paymentLink/{paymentLinkId}:
completedAmountCents climbs as payments come in, and status flips from ACTIVE to COMPLETED when the invoice is fully paid.
8

Record offline payments (optional)

If the customer pays outside Nickel — a mailed check, cash, a bank transfer straight to you — tell Nickel about it so the invoice stops chasing them. An external payment is a record that money satisfied part or all of the invoice outside Nickel. No money moves; the invoice’s completedAmountCents and status are re-derived from its Nickel payments plus these records.To record a partial or back-dated payment, call POST /paymentLink/{paymentLinkId}/externalPayment. Both fields are optional: amountCents defaults to the full remaining balance and paidAt to today.
The response is illustrative:
A partial amount leaves the invoice ACTIVE with the amount counted, and reminders continue for the remainder. Recording the rest later flips it to COMPLETED. Nickel refuses an amount above the remaining balance, a paidAt in the future, and an invoice that is already fully paid — each returns a 400 that says why.If the customer simply paid in full, POST /paymentLink/{paymentLinkId}/markPaid with no body does the same thing for the full remaining balance, dated today.To undo a record — the check bounced, or it was entered against the wrong invoice — void it with POST /paymentLink/{paymentLinkId}/externalPayment/{externalPaymentId}/void. The invoice reopens for whatever the record was covering. Every invoice response lists its live records under externalPayments, so the id is always at hand.
An external payment records money you received. To reduce what the customer owes without receiving money — a discount, a write-off — lower the invoice’s requestedAmountCents with PUT /paymentLink/{paymentLinkId} instead. Lowering it to what has already been paid marks the invoice COMPLETED.
Payments on API-created invoices are never recorded in QuickBooks by Nickel, even with the integration connected — book them yourself without double-entry risk. Details in QuickBooks.

​
Where to go next

Refund or void a payment

Give money back the right way — and know when it’s fee-free.

Track your payouts

Match Nickel payments to the deposits on your bank statement.

Webhook events

Every event you can subscribe to, and how delivery works.

Charge customers automatically

Skip the waiting — pay invoices from an authorization on file.