Tax Invoices

View issued Tax Invoices for your Paypercut account and download their PDFs for your accounting records. Use the Merchant Dashboard for individual downloads or the API to access invoices from your own systems.

For an overview of these documents, see Taxes.

Through the Dashboard

Sign in to the Merchant Dashboard.
Select the account whose invoices you need and open Settings → Invoices.
Find the invoice by its number, billing period, amount, currency, or invoice date. Select Load More Results if you need to view more invoices.
Open the invoice's actions menu and select Download PDF.

Only issued invoices appear in the list. If Download PDF is unavailable, the invoice's PDF is still preparing; return to the page later. If the list is empty, check that you have selected the intended account.

Through the API

Make requests from your backend using an API credential authorized for the account. Use the same account and test or live mode for listing and downloading. An authorized platform can select a connected account with the Paypercut-Account header.

List issued invoices

Call List Tax Invoices to receive issued invoices in newest-first order.

curl --get 'https://api.paypercut.io/v1/tax_invoices' \
  --header "Authorization: Bearer $PAYPERCUT_SECRET_KEY" \
  --data-urlencode 'limit=50'

limit defaults to 50 and accepts values from 1 to 100. When has_more is true, pass the returned last_key unchanged on the next request. Keep the same account and mode. Stop when has_more is false; the final page returns last_key: null. An empty list returns data: [].

Store each invoice's id for downloads and event reconciliation. Keep its number as a string to preserve leading zeros. See the Tax Invoice object for the full response fields.

Read dates and amounts

period.start_date is the first included date and period.end_exclusive is the first date after the invoiced period. For example, 2026-08-01 through 2026-09-01 covers August; September 1 is excluded. issue_date is the date the document was issued.

amount is the total including tax, expressed as an integer at currency.scale decimal places. For example, 12000 with currency.code: EUR and currency.scale: 2 means EUR 120.00. Use the returned scale and preserve integer precision when parsing JSON.

Download the PDF

When download_available is true, call the invoice's download_url or Download a Tax Invoice with the invoice id:

curl 'https://api.paypercut.io/v1/tax_invoices/vati_01KAGY7ZM69W83AXEH3NRXP6JD/download' \
  --header "Authorization: Bearer $PAYPERCUT_SECRET_KEY"

The response contains a temporary download link and its expiry time. This example is illustrative:

{
  "url": "https://files.example.com/invoice.pdf",
  "expires_at": "2026-09-29T10:30:00Z"
}

Download the PDF from the returned url before expires_at. Request another link if it expires. Use your Paypercut API credentials for the API request only; do not send them when opening the download link.

An invoice can be issued before its PDF is ready. The presence of download_url alone does not mean that it can be downloaded.

Follow PDF availability

Register the event identifiers you need in your webhook endpoint's enabled_events. Both events include the Tax Invoice summary in data.object.

Event	What to do
`tax_invoice.finalized`	Store the issued invoice's details. Its event snapshot has `download_available: false`; wait for PDF availability.
`tax_invoice.available`	The PDF is ready. Request a download link when you need it.

Verify webhook signatures and handle repeated deliveries idempotently. Event data reflects the time of the event; the download operation checks current PDF availability.

Handle API errors

Response	What to do
`400`	Use a limit from `1` to `100`. Reuse the returned cursor unchanged with the same account and mode, or omit it to start again.
`401`	Check the API credential.
`403`	Check the selected account and the credential's permissions.
`404` on download	Use an issued invoice ID from the selected account's list or events and verify the account and mode.
`409` with `tax_invoice_pdf_not_ready`	Wait for `tax_invoice.available` before requesting another download link.
`500`	Retry with bounded backoff. Retain the error's `trace_id`, when supplied, for troubleshooting.

Overview