Changelog

API changes, new endpoints, and upcoming releases. No breaking changes without advance notice. All changes are additive unless marked otherwise.

2026-06-21 Released
New payment method — Bitcoin on-chain
  • BTC on-chain is live. Native Bitcoin acceptance via Boltz cross-chain swap. Opt-in per merchant from Dashboard → Setup → Payment Methods. When enabled and the order meets Boltz's 25,000-sat minimum, methods includes "bitcoin" and btc_address / btc_amount_sat are populated. Integrations that already check methods pick this up with no code changes.
  • Settlement timing: Bitcoin on-chain settles in 10–60 minutes after chain confirmations — materially different from Lightning (seconds) and Liquid (~60s). payment.confirmed fires when the Boltz chain swap is claimed. See Bitcoin on-chain in the docs for the full lifecycle.
  • BTC on-chain now fires payment.confirmed and generates a PDF invoice on settlement. Previously this settlement path was silent.
  • Headless QR: Encode a BIP21 URI — bitcoin:{btc_address}?amount={btc_amount_sat/1e8:.8f} — for both the QR image and the tap-to-pay href. Do not use the bare address as the QR content (customers would have to enter the amount manually).
New — Invoices & receipts API
  • Auto-generated PDFs on every settlement. AvoPay now creates a numbered PDF invoice (INV-YYYY-NNNNN) for every payment.confirmed event across all three payment rails. No configuration required.
  • GET /api/v1/payments/:id/invoice — Download the PDF for a settled payment. Auth: Bearer ak_live_…. Returns application/pdf. Returns 404 if not yet settled.
  • POST /api/v1/payments/:id/resend-receipt — Re-send the PDF to the buyer's email on file. Auth: Bearer ak_live_…. Returns 404 if no buyer email is recorded.
  • GET /api/v1/invoices — List all invoices for your account in JSON or CSV (?format=csv). Auth: Bearer ak_live_…. The CSV includes an invoice_status column for accounting exports.
New webhook — invoice.reissued
  • invoice.reissued fires when a buyer updates their name or email in the 30-minute grace window after payment. The PDF is regenerated with the new details and re-delivered. Can fire more than once per payment if the buyer resubmits. Use reissued_at (not delivery time) to determine which event is latest.
  • Payload includes: event, payment_id, invoice_number, amount_fiat, currency, amount_sats, metadata, reissued_at.
  • Handler pattern: Unlike payment.confirmed, do not skip on duplicate payment_id. Always overwrite buyer details and compare reissued_at to handle out-of-order delivery.
New — Buyer info endpoint
  • POST /api/v1/checkout/:id/buyer-info (no auth) — Lets buyers submit their name, email, and VAT number for PDF invoicing. The hosted checkout page calls this automatically after payment. Headless integrations can call it directly. Within 30 minutes of payment: triggers PDF regeneration and invoice.reissued. After 30 minutes: returns 409.
Pro plan — Invoice customisation
  • Logo: Pro merchants can set a logo URL (Dashboard → Invoice Settings). The logo is fetched at PDF generation time and rendered in the header.
  • VAT: Pro merchants can configure VAT mode (inclusive or reverse_charge) and rate. A VAT line is added to every invoice accordingly.
  • Invoice digest: Instead of one merchant email per payment, opt into a daily digest at 08:00 UTC summarising all previous-day settlements.
All changes are additive. No existing fields were removed or renamed. Integrations that don't use the new fields continue to work unchanged. BTC on-chain is opt-in — existing merchants who don't enable it see no change.
2026-06-19 Released
New fields — Payment object
  • invoice_sats — The exact satoshi amount encoded in the Lightning invoice. Usually equal to amount_sats, but may be higher when the fiat total converts below Boltz's minimum swap size. Always use invoice_sats for the Lightning payment display; use amount_sats for the order total.
  • methods — Array of payment rails available for this payment: ["lightning", "liquid"] by default. Includes "bitcoin" when the merchant has BTC on-chain enabled and the amount meets Boltz's minimum. Headless integrations should render tabs based on this array.
  • lightning_invoice — The raw BOLT11 invoice string. Render this directly as a QR code (bare, no prefix) or as a lightning: URI deep link.
  • liquid_address — The Liquid BTC confidential address. Render bare (no URI prefix) as a QR code for headless checkout.
  • btc_address — Native Bitcoin address. null unless methods includes "bitcoin".
  • btc_amount_sat — Satoshi amount for the BTC on-chain payment. Convert to BTC (/ 1e8) and combine with btc_address to construct a BIP21 QR URI. null when BTC on-chain is not active.
  • amount_fiat — The original fiat amount passed at creation.
  • currency — The ISO 4217 currency code.
  • settled_at — ISO 8601 timestamp set when the payment is confirmed. null while pending. Available on GET /api/v1/payments/:id.
New feature — Idempotency keys
  • Idempotency-Key header on POST /api/v1/payments — Send a unique key (e.g. your internal order ID) per payment creation request. Re-sending the same key with the same body replays the original response safely — no duplicate payment is created. Sending the same key with a different body returns 422 idempotency_key_reused_with_different_payload. Keys expire after 24 hours and are scoped per merchant. See Create payment for details.
Rate limits — POST /api/v1/payments
  • 30 requests/minute per API key on payment creation. Standard merchant integrations never approach this limit. Returns 429 rate_limit_exceeded with a Retry-After header when exceeded.
  • Maximum 50 open (pending) payments per merchant. A payment is open until it is paid, expired, or cancelled. Returns 429 too_many_open_payments if the limit is reached. This is a safeguard against runaway scripts — legitimate integrations will never hit it.
All fields are additive — no existing fields were removed or renamed. Integrations that don't use the new fields continue to work unchanged.