Paid vs DepositConfirmed

This page explains the difference between the Paid and DepositConfirmed payment events, so you can pick the right one 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.

The two 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`	Wingspan's originating bank or payment provider reported that it finished processing the outbound payment.	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.

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

Important: A payment can still be returned after DepositConfirmed. ACH and similar rails allow returns after processing. Listen for Invoice.Returned (and Payable.Returned for payables) and handle them 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

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`	Always `OriginatingBankProcessed` today. 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.

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 the underlying money movement step by step	`FundsMovement.*`

Don't tell a recipient that funds are "in your account" or "available" based on either event. Neither one reports the recipient's bank.

What's available today

Resource	`Paid`	`DepositConfirmed`	`Returned`
Invoice	`Invoice.Paid`	`Invoice.DepositConfirmed`	`Invoice.Returned`
Payable	`Payable.Paid`	Not yet available as a webhook	`Payable.Returned`
Payout	Not yet available as a webhook	Not yet available as a webhook	Not yet available as a webhook

For payables, the payable resource has an events.depositConfirmedAt timestamp with the same meaning. Until the webhook is published, read it from GET /v3/payments/payables/{payableId} after Payable.Paid, or watch the FundsMovement.* events for the payment. Check Event types for the current list.

The two signals

A typical sequence

What's in a DepositConfirmed event

Which one to use

What's available today

Related pages