Paid vs DepositConfirmed

This page explains the difference between the Paid and DepositConfirmed payment events and the Payout.Completed aggregate outcome, so you can pick the right signal to update your books, notify a contractor, or close out a payment.

They mean different things, and reading Paid as "the money has landed" leads to telling contractors their money arrived before it has.

Payment and payout signals

Event	What it means	What it doesn't mean
`Invoice.Paid`, `Payable.Paid`	Wingspan's own record moved to paid. The payment is under way inside Wingspan.	That money has left our bank, or reached anyone. Funds may still be in transit.
`Invoice.DepositConfirmed`, `Payout.DepositConfirmed`	Wingspan recorded terminal processing evidence from its originating bank or payment provider. The `confirmation` object identifies the observation.	That the recipient's bank received or posted it, that the funds are available to the recipient, or that the payment can't be returned.
`Payout.Completed`	Every delivery transfer is Sent, with nothing left to originate. Sent records the originating bank or provider's terminal processed state.	That the receiving bank posted the funds, that funds are available, or that a later return is impossible.

DepositConfirmed describes what our side of the payment observed. It says nothing about the receiving bank.

Payout.Completed is the payout aggregate's outcome. Payable.Paid concerns an obligation, and FundsMovement.Completed concerns one movement; neither alone proves the aggregate completed. Read the payout's transfers and recovery state when handling Payout.Failed or Payout.Returned. A transfer can fail while recovery continues; aggregate Failed means recovery stopped with an undelivered amount.

Important: A payment can still be returned after DepositConfirmed. ACH and similar rails allow returns after processing. Listen for Invoice.Returned, Payable.Returned, or Payout.Returned for the resource you track, and handle returns even when you've already seen DepositConfirmed.

A typical sequence

sequenceDiagram
    participant W as Wingspan
    participant B as Wingspan's bank or provider
    participant R as Recipient's bank
    W->>W: Invoice.PaymentInTransit
    W->>W: Invoice.Paid (Wingspan's record)
    W->>B: Send payment
    B-->>W: Processed
    W->>W: Invoice.DepositConfirmed
    B->>R: Funds travel on the rail
    Note over R: Posting and availability happen here. Wingspan doesn't report them.
    R--xB: Possible return, even later
    W->>W: Invoice.Returned

Events can arrive out of order. Read the invoice to see its current state rather than inferring it from which event came last.

What's in a DepositConfirmed event

Invoice.DepositConfirmed and Payout.DepositConfirmed events carry a confirmation object that tells you exactly what we observed:

// (trimmed)
{
  "type": "Invoice.DepositConfirmed",
  "data": { "id": "H7kP2wQx9LmN4vRt6yZa1b" },
  "confirmation": {
    "basis": "OriginatingBankProcessed",
    "rail": "...",
    "observedAt": "2026-09-25T13:05:41Z",
    "providerStatus": "..."
  }
}

Field	Meaning
`basis`	`OriginatingBankProcessed`. It names the evidence: our originating bank or provider processed the payment.
`rail`	The payment rail used, as a normalized string.
`observedAt`	When Wingspan observed the provider's processed status.
`providerStatus`	The provider's terminal processed status, normalized by Wingspan.

The same moment is recorded on the invoice as events.depositedAt. events.paidAt records the Paid transition. Payables use a different name: events.depositConfirmedAt records the DepositConfirmed moment, and events.paidAt the Paid transition. Invoices and payroll pay statements use events.depositedAt.

Which one to use

You want to	Use
Show a payment as "sent" or "processing" in your UI	`Paid`
Tell a contractor their payment has been sent from our side	`DepositConfirmed`
Mark a payment as settled in your ledger	`DepositConfirmed`, and reverse it if a `Returned` event follows
Catch a payment that bounced	`Returned`, on the invoice or payable
Track payout completion, stopped recovery, or a recorded payout return	`Payout.Completed`, `Payout.Failed`, and `Payout.Returned`, then read the payout
Track the underlying money movement step by step	`FundsMovement.*`

Don't tell a recipient that funds are "in your account" or "available" based on these signals. They do not report receiving-bank posting or availability.

Events by resource

Resource	`Paid` or `Completed`	`DepositConfirmed`	`Returned`
Invoice	`Invoice.Paid`	`Invoice.DepositConfirmed`	`Invoice.Returned`
Payable	`Payable.Paid`	`Payable.DepositConfirmed`. It matches `events.depositConfirmedAt` on the payable.	`Payable.Returned`
Payout	`Payout.Completed`	`Payout.DepositConfirmed`	`Payout.Returned`

Each event carries the resource ID in data.id. Read that resource to reconcile its current state and amounts. DepositConfirmed events add the same closed confirmation object described above; they do not add a resource snapshot or receiving-bank receipt fields. See Event types for routing scopes.

Payment and payout signals

A typical sequence

What's in a DepositConfirmed event

Which one to use

Events by resource

Related pages