Payables overview

This page explains what a payable is, how it fits with payees, engagements, and invoices, and which paths you can use to pay one.

Payers, payees, and payables

A payer is the Account that sends money. A payee is the person or business it pays. In V1 these were the client and the member (or collaborator). In V3:

• Your company is an Account. When you pay someone, you are the payer.
• Each person or business you pay is a Payee: your own record of that counterparty. A Payee can be paid before the person has created or linked a Wingspan Account. See Payees.
• A PayeeEngagement is the working relationship a payment is made under, such as a contractor engagement. Eligibility requirements (tax information, signed documents, payout method) are tracked per engagement. See Engagements.
• A Payable is one payment obligation from you to one Payee.

Payable and invoice are two views of one document

A payable and an invoice are the same underlying document seen from opposite sides. You, the payer, see a Payable at /v3/payments/payables. Your payee sees the same document as an Invoice at /v3/payments/invoices. When a contractor invoices you, the invoice they send shows up in your payables list. When you create a payable, it shows up in the contractor's invoices once you open it.

Because the document is shared, some fields belong to one side. The creator controls the shared fields such as line items and due date. Payer-specific fields, such as your approval decision, are editable only by you. Lifecycle and payment fields are set by Wingspan. See Components of a payable.

Ways to pay a payable

Payables can also come from other resources. An approved work log for a contractor engagement produces a payable, and a recurring payable generates one each period.

The basic flow

sequenceDiagram
    participant Payer as Payer (your Account)
    participant WS as Wingspan
    participant Payee
    Payer->>WS: POST /v3/payments/payables (status Created)
    Payer->>WS: POST /payables/{id}/open
    WS-->>Payee: Payable visible as an Invoice
    Payer->>WS: PATCH /payables/{id}/workflow-status (Approved)
    Payer->>WS: POST /payables/{id}/pay, or include it in a payroll run
    WS-->>Payer: Payable moves to PaymentInTransit, then Paid
    WS-->>Payee: Payout to the payee's payout method

1. Create the payable. It starts in Created and the payee can't see it yet.
2. Open it. It moves to Opened and becomes visible to the payee. Opening fails if the payee's engagement hasn't met its payment eligibility requirements.
3. Approve it. Only payables you mark Approved are selected into payroll runs.
4. Pay it, directly or through a payroll run.
5. Reconcile. Read the payable's status and events, or subscribe to the Payable.Paid webhook.

Paid is not the same as deposited

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. A payable can still move to Returned after both. See Paid vs DepositConfirmed.

Common mistakes

• Treating Created as sent. A Created payable is a draft. The payee can't see it and it can't be paid until you open it.
• Forgetting approval. An opened payable that isn't Approved is skipped by payroll runs. Nothing errors; it just doesn't get paid.
• Burying your own ID in metadata. Send your system's identifier as externalId. It's echoed on every read, filterable with filter[externalId][eq], and a duplicate returns 409 ResourceConflict so you can't pay the same bill twice by accident.
• Polling for payment status. Subscribe to webhooks and use the event log to catch anything you missed. See Webhooks overview.

Related pages

• Components of a payable
• Payable lifecycle and statuses
• Create a payable
• Invoices overview for the payee's side of the same document