Payable lifecycle and statuses

This page explains the three status fields on a payable, what each value means, and which API calls move a payable from one state to the next. V1's single invoice status plus client and member workflow statuses map onto these three fields.

Three independent fields

A payable carries three status fields because three different parties make decisions about it.

Approving a payable doesn't change its status. A payable can be Opened and Approved at the same time, which is exactly what a payroll run looks for.

Payment status

stateDiagram-v2
    [*] --> Created
    Created --> Opened: open
    Created --> [*]: delete
    Created --> Cancelled: cancel
    Opened --> Pending: payment blocked
    Pending --> Opened: blocker cleared
    Opened --> PaymentInTransit: pay or payroll run
    PaymentInTransit --> Paid
    PaymentInTransit --> PartiallyPaid
    PaymentInTransit --> Returned: bank return
    Opened --> PaidOffPlatform: pay-off-platform
    Opened --> Cancelled: cancel
    Paid --> Refunded: refund
    Paid --> PartiallyRefunded: partial refund
    Paid --> Returned: bank return

When a payable moves from Created to Opened, Wingspan assigns its invoiceNumber.

Why a payable is pending

While a payable is Pending, its read-only pendingStatusReason field records why Wingspan's eligibility check held it, such as MemberPayoutMethodNotSelected or PayeeTaxVerificationPending. In every other status it's null. A null on a Pending payable means no reason was recorded, not that the payable is clear to pay. See Find incomplete payables for every value and how to clear it.

Paid and deposit confirmation

Paid is Wingspan's internal state. DepositConfirmed means Wingspan's originating bank or provider reported its terminal processed state. It never means the recipient's bank received the money, funds are available, or the payment can't be returned. On a payable, deposit confirmation appears as events.depositConfirmedAt, separate from events.paidAt. The Payable.DepositConfirmed webhook isn't subscribable yet, so read the payable to check it. See Paid vs DepositConfirmed.

Actions that change status

State changes are always a POST to a verb on the payable, never a status value in a PATCH. The verb records what happened (an approval, a cancellation, a payment) instead of only the resulting value, which is what makes the events and actors history trustworthy.

These actions notify the payee without changing status:

• POST /v3/payments/payables/{payableId}/send emails the payee about an Opened payable. You can include a customMessage.
• POST /v3/payments/payables/{payableId}/remind sends a reminder about an Opened payable.

Payer approval

Set your approval decision with PATCH /v3/payments/payables/{payableId}/workflow-status. It works on Opened and Pending payables.

curl -X PATCH "https://api.wingspan.app/v3/payments/payables/Hb4Xk9Qw2Rt7Vn1Mz8Pc3L/workflow-status" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "payerApprovalStatus": "Approved", "reason": "Hours verified against timesheet" }'

Approval doesn't bypass eligibility. A direct pay still checks that the payee's engagement is payments eligible. V1 required approvals in the app; in V3 you can approve through the API.

Payee review

Payees act on the invoice side of the same document. You'll see their decisions in payeeReviewStatus and events.

• Accept. The payee confirms the amount and terms of an Opened payable. payeeReviewStatus becomes Accepted.
• Reject. The payee sends an Opened payable back for correction, with a required reason.
• Dispute. The payee disputes a payable after accepting it. Payment processing stops until the dispute is resolved, and events.disputedAt is set.
• Resubmit. After you decline, the payee can revise and resubmit. payeeReviewStatus becomes Resubmitted.

Contractor acceptance before payment isn't turned on for every payer. Contact your Wingspan account manager to enable it.

Reading the fields together

Webhooks

These payable events are available to subscribe to today:

Other transitions are recorded in the payable's events timestamps but don't have subscribable webhooks yet, including Payable.Opened, Payable.WorkflowStatusChanged, and Payable.DepositConfirmed. Read the payable to check them. See Event types for the current list.

Common mistakes

• Sending status in a PATCH. It's rejected. Use the action endpoints.
• Retrying open without If-Match. open, accept, reject, and PATCH require the payable's current ETag (or *). A stale ETag returns 412 with code: PreconditionFailed; read the payable again and retry.
• Assuming Paid means the contractor has the money. It doesn't. A bank can still return the payment.
• Retrying a Returned payable. You can't pay a returned payable again or switch its funding source. Create a new payable.

Related pages

• Create a payable
• Payroll runs
• Find incomplete payables
• Invoice lifecycle for the payee's view