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.To show your customer a note — a PO number, payment terms, a thank-you — pass memo (up to 1,000 characters). It appears on the payment page and in the invoice email. Change it later with PUT /paymentLink/{paymentLinkId}, or send "memo": "" to remove it.
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.
A file belongs to your organization, so any of your API keys can attach it. A file belonging to another organization is answered as 404 File not found.
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:
If your organization’s approval rules require approval to send this invoice, nothing is sent yet: the response has "heldForApproval": true and the approvalRequestId, and the invoice goes to its recipients once an approver approves it in the Nickel dashboard.
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 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 — payment.succeeded fires when they settle — 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. Every field is optional: amountCents defaults to the full remaining balance and paidAt to today. Pass externalReferenceId — your own transaction id for the money — when your system might send the same payment twice, on a retry or from two workers at once: a repeat with the same reference on the same invoice returns the existing record instead of creating another, and a repeat whose amountCents or paidAt disagree with the existing record is refused with 409 and code REFERENCE_CONFLICT, so a mix-up in your ids surfaces instead of silently recording the wrong amount. Voiding a record releases its reference.
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.
9

Add charges after the invoice is sent (optional)

Sometimes the customer owes more than the invoice said: their check bounced and you charge a returned-check fee, the invoice went past due and accrues a finance charge, or shipping was added to the order. A debit memo is a record of an amount added to the invoice after it was issued. It is the mirror of an external payment: an external payment brings the balance down, a debit memo brings it up.Record one with POST /paymentLink/{paymentLinkId}/debitMemo. Both amountCents and description are required. Your customer sees the description on the payment page next to the amount, so write it for them. Pass externalReferenceId — the memo’s number in your own system — so a retry returns the memo that was already recorded instead of charging the fee twice.
The response is illustrative:
requestedAmountCents is the invoice’s total, memos included, and debitMemoAmountCents is the part that came from memos. If the invoice was already paid, the memo reopens it for the new amount and reminders pick back up.With external payments and debit memos together, you never calculate the balance yourself. Send each transaction from your own books as it happens — a payment, a credit, a fee, a reversal — and Nickel keeps the total and the amount due.
Send a debit memo before the payment that covers it. Nickel refuses an external payment larger than the remaining balance, so if a $35 fee and the $155.55 check that pays it arrive together, post the fee first — or retry the payment’s 400 once the fee lands.
To reverse a memo, void it with POST /paymentLink/{paymentLinkId}/debitMemo/{debitMemoId}/void. Its amount comes back off the total. If the customer had already paid it, the void still goes through and overCollectedAmountCents in the response tells you how much they paid beyond the new total; whether to refund that is up to you.Nickel refuses a debit memo on an invoice synced with QuickBooks — add the charge to the invoice in QuickBooks, and it syncs to Nickel.
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.