Invoicing

An invoice is a bill you raise against a customer, with a number, a due date and a hosted page where they pay by card. You build it as a draft, finalize it when it is right, and send it. If it goes unpaid we email reminders on a schedule until it is paid, voided or written off.

The lifecycle

Create, add lines, finalize, send

# 1. A draft. Its money comes from the lines you add next, not from this call.
curl https://api.secureprocessing.app/v1/invoices \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
        "customer": "cus_9aB1cD3eF5gH7iJ9kL1mN3oP",
        "currency": "usd",
        "days_until_due": 14,
        "memo": "Thanks for diving with us."
      }'

# 2. A line. Quote a price, or write the line yourself in minor units.
curl https://api.secureprocessing.app/v1/invoice_items \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
        "invoice": "in_1aB3cD5eF7gH9jK1lM3nP5qR",
        "description": "Blue Hole Two-Tank Dive",
        "unit_amount": 50000,
        "quantity": 2,
        "tax_rate": "txr_5jK7lM9nP1qR3sT5uV7wX9yZ"
      }'

# 3. Finalize. Assigns the number, freezes the totals, and moves it to open.
curl -X POST https://api.secureprocessing.app/v1/invoices/in_.../finalize \
  -H "Authorization: Bearer sk_test_..."

# 4. Send. Emails the customer a link to the hosted page. A 503 or 400 means it did not go.
curl -X POST https://api.secureprocessing.app/v1/invoices/in_.../send \
  -H "Authorization: Bearer sk_test_..."

const invoice = await sp.invoices.create({
  customer: customer.id,
  currency: "usd",
  days_until_due: 14,
});

await sp.invoiceItems.create({
  invoice: invoice.id,
  description: "Blue Hole Two-Tank Dive",
  unit_amount: 50000, // minor units — $500.00
  quantity: 2,
  tax_rate: gst.id,
});

const open = await sp.invoices.finalize(invoice.id);
console.log(open.number);              // "INV-0007"
console.log(open.total);               // 112500  — minor units, $1,125.00
console.log(open.hosted_invoice_url);  // send the customer here

await sp.invoices.send(invoice.id);

days_until_due is counted from the moment you finalize, not from when you created the draft — a draft that sat for a fortnight is not already overdue the day you send it. Give due_date instead if you want a fixed date. Not both.

send answers 200 only once the email has gone to our email provider. That is when sent_at is set and invoice.sent fires. If the email did not go, sent_at stays as it was, no event fires, and the answer is one of these two:

Invoice numbers

Numbers come from a counter of your own, per account and per mode, and they are consecutive with no gaps — INV-0001, INV-0002, and so on. Five finalizes at the same instant get five consecutive numbers. A finalize that fails puts its number back rather than burning it, which is why we do not use a database sequence: a gap is a question an auditor asks, and “a transaction rolled back” has never been an answer anybody accepts.

Test mode has its own counter, so rehearsing does not advance your real numbering.

Tax

A tax rate is a row you own. Belize GST — 12.5%, added on top of the line — is created for you when your account is. Put a rate on a line and the tax is computed per line, rounded half-up to the minor unit, and added into the invoice’s tax.

curl https://api.secureprocessing.app/v1/tax_rates \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"display_name": "GST", "percentage": 12.5, "inclusive": false, "jurisdiction": "Belize"}'

The hosted page

hosted_invoice_url is where you send the customer. It shows the line items, the totals, anything you put in memo and footer, and a button that takes them to a secure page hosted by the bank. You never see a card number and neither do we.

invoice_pdf is the same document as an A4 PDF, generated on request. It needs your API key, so it is for your records and your emails rather than something to link a customer to.

Partial payments

Set allow_partial: true and the hosted page shows an amount box. The customer can pay any part of what is outstanding; the balance stays owed and keeps being chased. Each payment fires invoice.payment_succeeded, and the one that settles the bill also fires invoice.paid, once, alongside its own invoice.payment_succeeded.

Reminders

An open invoice with a due date is chased automatically, at most one email a day, on this schedule:

Reminders stop the moment the invoice is paid, voided or marked uncollectible, and they stop for good after the last one — an invoice still unpaid a fortnight after it was due needs a person, not a sixth email. An invoice you finalize the day before it is due does not get the earlier reminders retroactively; it starts at the stage that actually applies. Each one fires invoice.reminder_sent.

Charging a saved card

await sp.invoices.pay(invoice.id, { payment_method: "pm_2xY4zA6bC8dE0fG2hI4jK6lM" });

There is no way to charge a card the customer has not already saved. Send the invoice and let them pay on the hosted page — which is what send is for.

A 202 — an invoice whose amount_paid has not moved — means the charge was sent and the bank’s answer has not reached us yet. The card may already have been charged, so do not charge it again: the payment settles on its own within minutes, and invoice.payment_succeeded follows if it went through — with invoice.paid alongside it if that payment settled the invoice.

Events

Subscribe on the webhooks page. The one to fulfil on is invoice.paid; the one to reconcile a bank statement against is invoice.payment_succeeded, which fires once for every payment. Fulfil idempotently, keyed on the invoice id: delivery is at-least-once, so the same event can reach you more than once.

These match Stripe. invoice.payment_succeeded fires for every payment attached to the invoice, including the one that settles it and any overpayment after it. invoice.paid fires exactly once, when the invoice changes to paid, and never for a later overpayment. A payment that settles the invoice therefore fires both, alongside each other, each carrying the invoice as it stood after that payment. They share the same created and no order between them is guaranteed — in the events list or in delivery — so do not make one handler wait for the other.