API reference

Signed links

Signed links are public URLs to an invoice PDF, a receipt PDF or an invoice's payment page. They need no API key, so you can show them to your customers on a billing page or in your own emails.

Creating links#

EndpointReturnsScope
POST /api/v1/invoices/{id}/linkspdfUrl and payUrlinvoices:read
POST /api/v1/receipts/{invoiceId}/linkspdfUrl (the receipt)invoices:read
curl -X POST "$FLUX_BASE_URL/api/v1/invoices/5012/links" \
  -H "Authorization: ApiKey $FLUX_API_KEY"

Public, signed URLs you can show to end customers.

FieldDescription
pdfUrlstringOpens the PDF. No API key needed.
payUrlstring · nullableRedirects to Paystack checkout. null when the invoice is paid or voided, and always on receipt links.
expiresAttimestamp (UTC)When the links stop working. UTC, with Z.
Signed links
{
  "pdfUrl": "https://api.flux.example/public/invoices/NDIuNTAxMi5pcC4xNzk2MTE2NDAw.mJb2Kc0r1oB7yWq4sZ0eD9xVh3tLnA6uPfRkGiE8ScQ/pdf",
  "payUrl": "https://api.flux.example/public/invoices/NDIuNTAxMi5wYXkuMTc5NjExNjQwMA.Q2pXv8nTz1sLcR0aB4yHk7uWm3eJd6gFoNiV5qYtKxE/pay",
  "expiresAt": "2026-12-01T10:00:00.5236411Z"
}

What the links open#

LinkOpens
/public/invoices/{token}/pdfThe invoice PDF.
/public/receipts/{token}/pdfThe receipt PDF.
/public/invoices/{token}/payRedirects to Paystack checkout. If the invoice is already paid, voided or not set up for online payment, it shows a short message instead.
  • A token works only for its own kind of document: a PDF link can't be used to pay.
  • An invalid or expired link returns 404 with “This link is invalid or has expired.”
  • PDF responses are sent with Cache-Control: private, no-store and X-Robots-Tag: noindex.

Expiry#

Links last 30 days by default (a server setting), shown in expiresAt. After that they stop working. Ask for fresh links when you show them, such as when your billing page loads, instead of storing them. Creating links is cheap and doesn't change anything.

Security#

  • A link's token is signed with HMAC-SHA256 and names one organization, one invoice, one kind of document and an expiry. It can't be guessed or altered.
  • Anyone who has a link can open it until it expires. Show links only to the customer they belong to, and send them only over HTTPS.
  • If the server has no link-signing key configured, both endpoints return 503 links_not_configured.