Skip to content
Space Invoices Documentation

Fintechs

Use this path when invoicing is adjacent to money movement: card acquiring, bank accounts, business payments, lending, or treasury workflows. The main value is keeping documents, payments, and compliance in the same product surface without inventing invoice logic from scratch.

Common Underestimation

The hard part is not issuing the first PDF. It is keeping invoice state, payment state, reversals, reconciliation, and cross-border compliance behavior aligned over time.

Who This Is For

  • fintech products serving business customers
  • teams that already handle payment events and want invoices to follow them
  • platforms that need reconciliation, auditability, and country-aware issuance

Best Fit / Not A Fit

Best fit

  • payment success or settlement events already exist in your platform
  • you need invoicing next to balances, transfers, or payment history
  • one business customer should usually map to one isolated entity

Not a fit

  • you are only looking for subscription billing logic
  • you do not want your backend involved in event handling
  • your product does not have a business identity model for customers yet
  • use an account key on your backend to manage customer entities
  • use the JavaScript SDK for event-driven creation, payment recording, and reconciliation
  • add dashboard or embed access later if end users need direct document management

Start with one real payment event and prove that invoice creation, rendering, and reversal handling behave correctly in sandbox before you add broader UI.

Entity Model

Typical fintech model:

  • one business customer = one entity
  • payment rails and ledger stay in your system
  • invoices, customers, items, and document rendering live in Space Invoices

This keeps invoicing isolated while letting your product own balances, payouts, and money movement.

First Sandbox Milestone

Validate this before go-live:

  1. create one entity for a business customer
  2. trigger invoice creation from a payment or account event
  3. render the invoice
  4. record or reconcile the payment status
  5. test one refund or failed-payment edge case

Invoice After Payment

Create invoices when payments are processed:

Payment invoicetypescript
// title: Create invoice for payment
const _invoice = await sdk.invoices.create(
  {
    customer: { name: payment.merchantName, email: payment.merchantEmail },
    items: [
      {
        name: `Transaction fee - ${payment.transactionId}`,
        quantity: 1,
        price: payment.feeAmount,
      },
    ],
    payment: {
      type: "bank",
      amount: payment.feeAmount,
      date: new Date().toISOString().split("T")[0],
    },
  },
  { entity_id: entityId },
);
Create Invoice API →

Recurring Subscriptions

Handle subscription billing:

Subscriptiontypescript
// title: Create subscription invoice
const _invoice = await sdk.invoices.create(
  {
    customer: { name: merchant.name, email: merchant.email },
    items: [
      {
        name: `${plan.name} - ${billingPeriod}`,
        quantity: 1,
        price: plan.price,
      },
    ],
    dateService: billingPeriod,
    dateDue: new Date(Date.now() + 14 * 24 * 60 * 60 * 1000).toISOString().split("T")[0],
  },
  { entity_id: entityId },
);

Common Workflow And Gotchas

  • do not tightly couple payment success and final document issuance until you know the exact business rules
  • persist external payment IDs in metadata for reconciliation and support workflows
  • use credit notes for reversals rather than rewriting finalized invoices
  • separate document issuance rules from settlement timing if your product has delayed capture or delayed payout
  • decide early whether users need direct invoice editing or only visibility

Compliance Notes

  • customer entity country drives many default compliance rules
  • cross-border issuance can require special tax treatment even when the payment is domestic
  • regulated payment workflows and invoicing workflows should share identifiers, not necessarily the same lifecycle
  • sandbox should be used for both document creation and payment-linking validation

Why This Model Works

  • Payment linking — Use metadata to connect invoices to payments
  • Reconciliation — Match invoices to transactions
  • Multi-country — Compliance across jurisdictions
  • Real-time — Create invoices instantly on payment events

Integration Points

Payment EventInvoice Action
Payment succeededCreate invoice
Subscription renewedCreate recurring invoice
Refund processedCreate credit note
Dispute wonNo action
Dispute lostCreate credit note

Webhook Flow

Fintech integration flow
┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│   Payment    │     │   Your Fintech  │     │    Space     │
│   Processed  │────▶│   Platform      │────▶│   Invoices   │
└──────────────┘     └─────────────────┘     └──────────────┘
                            │                       │
                            │  1. Payment received  │
                            │─────────────────────▶│
                            │                       │
                            │  2. Create invoice    │
                            │─────────────────────▶│
                            │                       │
                            │  3. Mark as paid      │
                            │─────────────────────▶│
                            │                       │

Clear Next Action

Pick one real payment event from your system and prove the invoice-plus-reconciliation flow in sandbox before you add broader product UI.