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"
  }
}

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.