Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fluveo.com/llms.txt

Use this file to discover all available pages before exploring further.

An Invoice is a statement of amounts owed by a customer. Fluveo supports two collection flows:
  • charge_automatically (default): Fluveo charges the customer’s default payment method as soon as you call /pay (or on subscription renewal).
  • send_invoice: You call /send to email a hosted link to the customer, who pays via the hosted page.

​
MVP scope

  • Card-only payment via Stripe. PIX invoices are a future feature; sending payment_method_types=["pix"] returns 422 unsupported_payment_method_type.
  • PSP-agnostic routing: the invoice stores payment_method_types (defaults to ["card"]). /pay resolves the PSP adapter from this list; MVP always lands on Stripe.
  • Hosted link: tokens are persisted in the invoice_hosted_tokens store with a 30-day expiry. Re-calling /send revokes older tokens so the newest email is always the active link.

​
Create

POST /v1/invoices

{
  "customer": "cus_123",
  "currency": "usd",
  "collection_method": "charge_automatically",
  "payment_method_types": ["card"]
}

​
Add items

POST /v1/invoice_items

{
  "invoice": "in_abc",
  "customer": "cus_123",
  "currency": "usd",
  "amount": 4200,
  "description": "Consulting"
}

​
Finalize

POST /v1/invoices/{id}/finalize
Moves the invoice from draft → open and assigns a sequential number (per merchant, via pg_advisory_xact_lock).

​
Pay

POST /v1/invoices/{id}/pay

{ "payment_method": "pm_card_visa" }
The server logs the structured event chain: 
invoice.pay.attempt      { invoiceId, paymentIntentId, provider, currency, paymentMethodTypes }
invoice.pay.succeeded    { invoiceId, paymentIntentId, provider }
   — or —
invoice.pay.failed       { invoiceId, paymentIntentId, provider, outcome }
invoice.pay.psp_error    { invoiceId, paymentIntentId, provider, error }
Successful payment transitions the invoice to paid and emits invoice.paid on your events stream. 
POST /v1/invoices/{id}/send
Generates a 32-byte opaque token, persists it with a 30-day expiry, revokes any prior tokens for this invoice, and emails the customer a https://checkout.leanrails.com/invoice/{token} URL. The hosted page resolves the token via GET /internal/invoice-hosted/{token} and renders the invoice summary plus accepted payment methods. Direct hosted invoice payment is a follow-up; for MVP, collect card payment through /v1/invoices/{id}/pay or the recurring billing flow.

​
Events emitted

  • invoice.created
  • invoice.finalized
  • invoice.paid
  • invoice.payment_failed
  • invoice.voided
  • invoice.marked_uncollectible