> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.transxact.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.transxact.io/_mcp/server.

# Invoices

An Invoice is a request for payment with its own hosted page. It is not a
payment: when a Customer pays it, Transxact creates an ordinary Checkout
Session, so fees, Payouts and webhooks work as they do for any other payment.

The Invoices API is for **Business accounts**. A key from any other account
gets `403 business_only`.

## The flow

1. `POST /v1/invoices` creates a draft.
2. `POST /v1/invoices/{id}/send` gives it a number (`INV-0007`) and makes its
   `url` work. Share that URL with your Customer.
3. The Customer opens `url`, pays, and you hear about it by webhook.

A sent Invoice can't be edited, because it may already be on the Customer's
phone. To change one, void it and make another.

```bash
curl https://api.transxact.io/v1/invoices \
  -H "Authorization: Bearer $TRANSXACT_SECRET_KEY" \
  -H "Idempotency-Key: $ORDER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "Mere Tuilagi",
    "dueDate": "2026-11-30",
    "items": [{ "description": "Tiling, kitchen", "quantity": 2, "unitPrice": 12000 }],
    "taxLabel": "VAT",
    "taxPercent": 15
  }'
```

Amounts are integers in FJD cents. The total, with tax, must be under FJD
5,000.00 (at most `499999`), in Test mode and Live mode alike.

## Idempotency

`create`, `send` and `void` require an `Idempotency-Key`. Retrying with the same
key returns the original result: no second draft, no second number, no second
void. A new key on an Invoice that has already moved on gets
`409 invalid_state`.

## Modes

An Invoice belongs to the mode of the key that created it. A `sk_test_` key
only sees Test mode Invoices and a `sk_live_` key only Live mode ones; the
other mode's Invoices read as `404`.

## Finding the Invoice a payment is for

The Checkout Session created when a Customer pays an Invoice carries
`invoiceNumber`, both in `GET /v1/checkout-sessions/{id}` and in the
`checkout_session.*` webhook payload. Sessions that don't pay an Invoice omit
the field. There is no separate Invoice webhook event.

## PDF

`pdfUrl` on a sent Invoice is where to `GET` its PDF, with your secret key. It
is the same file the Customer's page and emails carry.