Checking Payments

Checking payments

The shared rules for every call — ids, paging, previewing a write, what the tools cannot do — are in the using-wingspan-tools skill. Apply them here.

A payable is one payment owed to one contractor — the row on the Payables screen in the Wingspan app. A contractor is a person or business the company pays. An engagement is the named working arrangement a payment is filed under.

Two tools cover most of this: search_payables lists and filters, get_payable reads one payment in full. Every row a search returns carries a payableId, and that is the id get_payable takes. A third, get_payroll_preview, reads what the next payroll run would pay as things stand today.

Listing and searching

search_payables with no arguments lists every payment except cancelled ones, 25 to a page.

There are no other filters. Do not invent one.

What each status view holds:

• all — every payment except cancelled ones.
• draft — created but not yet opened, so the contractor cannot see it.
• toApprove — open and waiting for someone at the company to approve it.
• scheduled — approved and waiting for a payroll run.
• paid — paid or in transit only. Payments recorded off-platform, partially paid or refunded are not in this view; use all for a complete history.
• cancelled — cancelled. Hidden everywhere else, which is why totals stay honest.

Every view, all included, also leaves out two kinds of row: the batch-level total a payroll run creates, which would double-count against the individual payments, and personal payment-link invoices. Neither can be read by id either.

Totals

A list normally carries a summary with a count and an amount total, covering every payment matching the filters, not only this page. Use it for "how much do we owe" instead of adding up a page, and say which filters it covers. When summary is null the totals were unavailable — say so rather than summing the page and presenting it as the total.

A correct total over the wrong set of payments is still the wrong answer, so pick the view before reading the summary:

• "What do we owe?" means approved-and-unpaid plus open-and-unapproved. Read scheduled (approved, waiting for a payroll run) and toApprove (open, waiting for approval) separately and report both figures with their names. Do not read all: it includes paid, in-transit, off-platform and refunded payments.
• Drafts are not owed yet. draft payments are invisible to the contractor and not scheduled. Report them as a separate line if the user asks what is in the pipeline, never inside the owed figure.
• Partial payments are not separable here. A partially paid payable shows its full amount in whichever view holds it; the summary has no remaining-balance figure. If the roster has partially paid payables, say the owed figure may overstate what remains, and point to the Wingspan app for the exact balance.
• paid is history, not liability. It answers "what have we paid", and only for payments paid or in transit; off-platform and refunded records sit under all.

The words on a row

Each row's status is the wording the Wingspan app shows, not a raw code, so it can be read to the user as-is.

One more value can appear on a row: Unknown, when the payment is in a state the row wording has no pill for — a returned deposit is the common case. Read get_payable for it; the detail headline names it, Returned. The money did not land, the payment stays on the payroll run it was part of, and it is final for that payment: a replacement is a new payment, created in the Wingspan app.

Approval is a separate field from status. A payment can be open and unapproved, or open and approved; the status wording above folds that in, but they are two different things underneath. Approving happens in the app.

One payment in full

get_payable returns what the Payables detail panel shows:

• The panel headline and the row's status wording.
• Any alert on it. Two exist: the contractor has not finished setting up digital payments, and the contractor disputed the invoice — their reason is in the activity timeline.
• The amount, with the breakdown from gross to net and a named row per deduction.
• The line items, the due date, whether the due date was rescheduled, and the original date if it was.
• How it was paid, the attachments, any notes and purchase-order or project labels.
• activity — the full timeline of everything that has happened to it, newest first.

Quirks of the timeline are worth knowing before you conclude something did not happen. At most two views of the invoice link are ever listed — the first, and the first more than an hour after it — so a short timeline is not evidence the contractor stopped looking. Views after the payment was paid are dropped. A "due today" reminder sent on the same day the payment was opened is suppressed.

What these tools cannot see

Where the money is in the banking system. No payout or bank-transfer record is read, matching what the Payables screen itself shows. The furthest either tool goes is the date the deposit was confirmed. A confirmed deposit means the sending bank finished processing, not that the money is available or final — a payment can still come back afterwards, and that shows up on the payment itself, where get_payable names the state Returned. A question like "has the bank transfer landed" or "why did the transfer fail" belongs in the Wingspan app, or with Wingspan support.

Past payroll runs and funding sources. A payroll run is the batch that funds and pays a set of approved payments, and the funding source is the account Wingspan debits to fund it. get_payroll_preview reads the next run before it goes out — when it processes, how much moves, what is funded but held on eligibility, and what gets left behind. Runs that have already happened, and the account behind any of them, are not readable here. When a user asks why a scheduled batch has not gone out, or which account funded it, send them to the Payroll screens in the app.

What the preview is worth predicting with: nothing. It is today's data, not a forecast. It reports what the next run would pay if it went out against the records as they stand right now, and it models none of what happens between now and then — a contractor finishing a requirement and becoming eligible, someone opening or approving a draft, an amount edited, a payment cancelled, a new payable created. Any of those changes the answer. Report it as "as things stand today" and never as what the run will pay.

Why is this not paid yet

Work down this list.

1. get_payable. If the status is Draft, it was never opened. If it says action required, the secondary line on the row says which of the three it is — approval, a dispute or a resubmission. If it says awaiting contractor, the contractor was not eligible when the payment came up.
2. If the answer points at the contractor, get_contractor with the contractorId on the payment. Its alert gives the single reason — invited and not signed up, tax information not shared, archived, payments eligibility pending, an outstanding requirement, or one expired or expiring. The finding-contractors skill lists all eight outcomes.
3. If the payment is paid but the contractor says the money has not arrived, that is the banking question above: Wingspan app, or Wingspan support.

"Awaiting contractor" is not a reason to cancel anything. It means the contractor was not eligible at the moment payment came up. Fix the contractor and the payment carries on. Cancelling and recreating loses the record and, because a payment's engagement is fixed when it is created, is sometimes unrecoverable.

Finish these in the Wingspan app

• Approving or unapproving a payment, rescheduling it, cancelling it, and paying it. Releasing a draft is not app work — that is open_payables.
• Starting a payroll run, funding sources, invoices, payment splits and accounting integrations.
• Resolving a dispute with a contractor.
• Anything about a bank transfer after Wingspan has sent the payment.