Invoices

Invoices let you bill customers for line items, generate hosted payment pages, and collect payment using saved cards.

Invoice lifecycle

Create a draft invoice
Add line items to the invoice
Finalize the invoice (generates a hosted URL and PDF)
Pay the invoice with a saved payment method, or send the hosted URL to the customer

Step 1: Create an invoice

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/invoices \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "accounts/acct_YOUR_ACCOUNT/customers/cus_CUSTOMER_ID",
    "currency": "USD"
  }'

Response

{
  "name": "accounts/acct_YOUR_ACCOUNT/invoices/in_INVOICE_ID",
  "currency": "USD",
  "customer": "accounts/acct_YOUR_ACCOUNT/customers/cus_CUSTOMER_ID",
  "state": "DRAFT",
  "number": "WR0SSFN0-DRAFT",
  "subtotal": "0",
  "tax": "0",
  "total": "0",
  "lines": []
}

Step 2: Add line items

API reference

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/customers/cus_CUSTOMER_ID/invoice-items \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "item": {
      "invoice": "accounts/acct_YOUR_ACCOUNT/invoices/in_INVOICE_ID",
      "display_name": "Example service",
      "currency": "USD",
      "unit_amount": "50000",
      "quantity": "3"
    }
  }'

Response

{
  "name": "accounts/acct_YOUR_ACCOUNT/customers/cus_CUSTOMER_ID/invoice-items/ii_ITEM_ID",
  "display_name": "Example service",
  "currency": "USD",
  "unit_amount": "50000",
  "quantity": "3",
  "amount": "150000",
  "invoice": "accounts/acct_YOUR_ACCOUNT/invoices/in_INVOICE_ID"
}

The amount is computed automatically: unit_amount * quantity = 500.00 * 3 = 1,500.00 USD.

Step 3: Finalize the invoice

API reference

Finalizing locks the invoice, assigns an invoice number, and generates a hosted payment page and PDF.

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/invoices/in_INVOICE_ID:finalize \
  -H "Authorization: Api-Key $API_KEY"

Response

{
  "name": "accounts/acct_YOUR_ACCOUNT/invoices/in_INVOICE_ID",
  "state": "OPEN",
  "number": "WR0SSFN0-0001",
  "total": "150000",
  "subtotal": "150000",
  "hosted_invoice_url": "https://pay.synaptopay.com/i/acct_YOUR_ACCOUNT/in_INVOICE_ID",
  "pdf_url": "https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/invoices/in_INVOICE_ID/documents/PDF",
  "payment_intent": "accounts/acct_YOUR_ACCOUNT/payment-intents/pi_GENERATED_PI",
  "state_transitions": {
    "finalize_time": "2025-10-27T19:28:56Z"
  }
}

You can send the hosted_invoice_url to your customer, or use the pdf_url to attach the invoice as a PDF.

Step 4: Pay the invoice

API reference

Charge a saved payment method:

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/invoices/in_INVOICE_ID:pay \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "accounts/acct_YOUR_ACCOUNT/payment-methods/pm_PAYMENT_METHOD_ID"
  }'

Response

{
  "invoice": {
    "name": "accounts/acct_YOUR_ACCOUNT/invoices/in_INVOICE_ID",
    "state": "PAID",
    "total": "150000",
    "state_transitions": {
      "finalize_time": "2025-10-27T19:28:56Z",
      "paid_time": "2025-10-27T19:30:16Z"
    }
  },
  "payment_intent": {
    "name": "accounts/acct_YOUR_ACCOUNT/payment-intents/pi_GENERATED_PI",
    "amount": "150000",
    "state": "SUCCEEDED"
  }
}

Applying tax rates

Tax rates are reusable resources scoped to your account — create one per jurisdiction/percentage combination, then attach it by name to an invoice or to individual line items.

Create a tax rate

API reference

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/tax-rates \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "VAT – UK (20%)",
    "percentage": 20,
    "behavior": "EXCLUSIVE"
  }'

behavior is either EXCLUSIVE (tax is added on top of the line amount — typical for B2B) or INCLUSIVE (the line amount already includes tax, and the net is calculated backwards).

Attach to an invoice or line item

Set default_tax_rates on the invoice to apply the rate to every line, or tax_rates on an individual invoice item to override per line:

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/invoices \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "accounts/acct_YOUR_ACCOUNT/customers/cus_CUSTOMER_ID",
    "currency": "GBP",
    "default_tax_rates": [
      "accounts/acct_YOUR_ACCOUNT/tax-rates/txr_TAX_RATE_ID"
    ]
  }'

Once the invoice finalizes, the response includes a per-line taxes array and an invoice-level total_taxes breakdown showing the tax amount applied. For an EXCLUSIVE 20% UK VAT rate on a £500 line item, tax will be 10000 (£100.00) and total will be 60000 (£600.00).

Voiding an invoice

API reference

Void a finalized invoice that hasn't been paid. This cancels the associated payment intent and prevents further payment.

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/invoices/in_INVOICE_ID:void \
  -H "Authorization: Api-Key $API_KEY"

The invoice state changes to VOID. This is a final state — voided invoices cannot be reopened.

Marking an invoice uncollectible

API reference

Mark an open invoice as uncollectible when you don't expect to receive payment. The invoice can still be paid after being marked uncollectible.

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/invoices/in_INVOICE_ID:mark-uncollectible \
  -H "Authorization: Api-Key $API_KEY"

Invoice states

State	Description
`DRAFT`	Invoice is being composed, line items can be added or removed
`OPEN`	Invoice is finalized and awaiting payment
`PAID`	Payment has been collected (final)
`VOID`	Invoice has been voided (final)
`UNCOLLECTIBLE`	Marked as uncollectible — can still be paid

Webhooks

When an invoice is paid, an invoice.paid event is sent to your webhook endpoints. See Webhooks for setup instructions.