Spend management platforms

This guide is for corporate card, accounts payable (AP) automation, and expense platforms whose customers want to pay independent contractors next to their other vendors. It covers the Account model, how an approved bill in your product becomes a Wingspan payable, and what to sync back.

What your customers get

Contractor onboarding with tax information collection and payout method setup, handled by Wingspan.
Contractor payments from the customer's own Account, with status you can show in your product.
Year-end 1099 filing based on the payments made through Wingspan, plus any you record as paid elsewhere.

See Send payments, Payees and onboarding, and Tax filing for each area.

Model your customers

Each customer that pays contractors is a child Account under your platform's root Account. Your backend uses one ServiceAccount key and names the customer with X-Wingspan-Account on each call. Contractors are Payees owned by the customer's Account. See Embed Wingspan in your app.

Map your objects

Your object	Wingspan object	Notes
Customer company	Child Account	`externalId` = your customer ID
Vendor flagged as a 1099 contractor	Payee	`externalId` = your vendor ID
Approved bill	Payable	`externalId` = your bill ID; line items carry `accounting` dimensions (`glAccountCode`, `class`, `project`, and others)
Bill attachment	Payable attachment	Upload to the vault first, then attach by `fileId`
Bill paid by card or another rail outside Wingspan	Payable marked paid off-platform	Keeps 1099 totals complete
GL coding	Line-item `accounting` dimensions	Returned as sent; if the customer uses QuickBooks Online, see Connect QuickBooks Online

From approved bill to payment

sequenceDiagram
  participant SM as Your platform
  participant WS as Wingspan API
  SM->>WS: POST /v3/payments/payees (first bill for a new contractor)
  SM->>WS: POST /payees/{id}/invite
  SM->>WS: POST /v3/payments/payables (externalId = bill ID)
  SM->>WS: POST /payables/{id}/open
  SM->>WS: POST /payables/{id}/pay
  WS-->>SM: Payable.Paid or Payable.Returned

Create the payable on the customer's Account when the bill is approved:

curl -X POST https://api.wingspan.app/v3/payments/payables \
  -H "Authorization: Bearer $WINGSPAN_API_KEY" \
  -H "X-Wingspan-Account: Ap4tYs8KqW2nLm6xRb1cVe" \
  -H "Idempotency-Key: bill-77031-create" \
  -H "Content-Type: application/json" \
  -d '{
    "payeeId": "Py3mQw7kLx2tRb9nVd4sHa",
    "currency": "USD",
    "dueDate": "2026-10-15",
    "externalId": "bill-77031",
    "lineItems": [
      {
        "description": "September design work",
        "totalCost": 2400.00,
        "accounting": { "glAccountCode": "6100", "class": "Marketing" }
      }
    ]
  }'

Then open and pay it, or leave it for the customer to approve in a payroll run. See Create a payable and Payable lifecycle and statuses.

If the customer paid the bill some other way (for example, with a card in your product), create the payable and mark it paid with POST /v3/payments/payables/{payableId}/pay-off-platform so it still counts toward the contractor's 1099.

What to sync back

You want to show	Source
The contractor finished onboarding	Poll the payee's `linkRequestStatus` and the engagement's `paymentsEligibility`. No webhook yet.
The bill was paid	`Payable.Paid` webhook. This is Wingspan's internal state, not confirmation that the contractor's bank received the funds.
The payment came back	`Payable.Returned` webhook. Create a new payable once the contractor fixes their payout method.
Money-movement detail for reconciliation	`FundsMovement.*` webhooks

Match each event to your bill by fetching the payable (data.id) and reading externalId. See Webhooks overview.

Pitfalls

Paying a bill twice. Set externalId to the bill ID. A second create returns 409 ResourceConflict instead of a duplicate payable.
Creating a payee per bill. Look the contractor up by filter[externalId][eq] first and reuse the payee.
Putting all customers' contractors on your platform's Account. Each customer is the payer. Use their Account so funding and 1099s are theirs.
Mixing currencies on one payable. currency is set once per payable; every line item uses it.