Invoice lifecycle

This page explains each status an invoice can be in, which call or event moves it there, and what
you can still change at each step.

Why status changes are action calls

You never change an invoice's status with PATCH. Each change is its own POST
(/send, /void, /pay, and so on). That way the API knows what happened, not only the result,
and records who did it and when in events and actors. PATCH only edits fields.

Statuses

Created corresponds to V1's Draft, and Opened to V1's Open.

An invoice paid in part stays Opened or Overdue until the rest is paid, and its amountPaid and amountDue show what's been paid and what's left. See Partial and off-platform payments.

stateDiagram-v2
    [*] --> Created
    Created --> Opened: send
    Created --> [*]: DELETE
    Opened --> Overdue: due date passes
    Opened --> PaymentInTransit: pay
    Overdue --> PaymentInTransit: pay
    Opened --> PaidOffPlatform: pay-off-platform
    Overdue --> PaidOffPlatform: pay-off-platform
    Opened --> Cancelled: void
    Overdue --> Cancelled: void
    PaymentInTransit --> Paid
    PaymentInTransit --> PartiallyPaid: split payout partly fails
    PaymentInTransit --> Returned
    Paid --> Refunded: refund
    Paid --> PartiallyRefunded: refund (partial)

The diagram shows the common paths. Wingspan can also move an invoice between states on its own,
for example when a payment fails and can be retried.

Actions

All paths are under /v3/payments/invoices/{invoiceId}.

Errors you'll see on transitions

Branch on code. detailCode is there to help you debug and may change. See
Errors.

Review and approval run separately from status

Two more fields track workflow that sits beside status:

• payerApprovalStatus (Pending, PreApproved, Approved, Declined) is the payer's approval
  of the obligation. The payer manages it from its side as a payable. See
  Payable lifecycle and statuses.
• payeeReviewStatus (Pending, Accepted, Disputed, Resubmitted) is your review as the
  payee, set by accept and dispute.

Neither one moves money by itself.

Webhooks

Use invoice events to track collection. See Event types for routing scopes and payload details.

You can subscribe to all of these events, including Invoice.Opened, Invoice.Overdue, Invoice.Cancelled, Invoice.Refunded, and the Invoice.Refund* events. You can also read the invoice to see each transition.

Invoice.Opened describes issuance or reopening, not the payer viewing the invoice, email delivery, or a newly sent message. Invoice.Cancelled concerns the invoice itself; deleting a draft or receiving InvoicePayment.Cancelled is a different action.

Once the refund events are published, they will carry the invoice ID in data.id and the refund ID in context.refundId. They distinguish multiple refunds against one invoice. Use Invoice.RefundCompleted for the refund's completed transition; neither Invoice.RefundInitiated, aggregate Invoice.Refunded, nor the refund action's HTTP success proves cash movement completed. Refunds and credit adjustments are separate operations.

Invoice.Paid and Invoice.DepositConfirmed are different signals. Paid is Wingspan's internal
state. DepositConfirmed means Wingspan's originating bank or provider reported its terminal
processed state. It doesn't mean the recipient's bank received the money, that funds are available,
or that the payment can't be returned, so an Invoice.Returned can still follow. See
Paid vs DepositConfirmed.

Read the invoice with GET /v3/payments/invoices/{invoiceId} using the event's data.id to reconcile
its current status, amounts, and timestamps. The event is a reference to a transition; it does not
replace the current resource representation.

Webhook delivery is best effort and can send duplicates. Dedupe on the event id, and recover
anything you missed from the event log. See Webhooks overview
and Recover missed events.

Related pages

• Components of an invoice
• Collect payment
• Concurrency and ETags
• Partial and off-platform payments