Payroll settings and funding

This page shows you how to set the account Wingspan debits to fund your payroll runs, how Wingspan picks a funding source when you pay in more than one currency, and which payroll settings you can change. In V1 this was PATCH /payments/payroll-settings/{id} with your client ID in the path. In V3, your own settings live at one path with no ID: /v3/payments/payer-settings.

Read your settings

Call GET /v3/payments/payer-settings. The request is scoped to your session, or to a child Account with X-Wingspan-Account.

curl "https://api.wingspan.app/v3/payments/payer-settings" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

// (trimmed)
{
  "id": "Ps4Vn9Kx2Wq7Lt1Rz5Mb8H",
  "accountId": "Aq9Zt4Mx1Kc7Rv3Ln8Pw2B",
  "defaultAccountCurrency": "USD",
  "defaultPaymentMethod": { "type": "ExternalBankAccount", "id": "Fs6Lp1Rk9Vx3Nq7Tz2Wb5H" },
  "payoutDelay": 0,
  "instantPayoutEligible": true,
  "payrollSettings": {
    "runsPayroll": true,
    "status": "Active",
    "defaultFundingSource": { "type": "ExternalBankAccount", "id": "Fs6Lp1Rk9Vx3Nq7Tz2Wb5H" },
    "fundingSourcesByCurrency": {},
    "enablePlannedPayroll": false,
    "instantPayoutFeePaidByClient": false,
    "fxConversionFeePaidByClient": false
  },
  "employerPayrollSettings": { "status": "Active" }
}

Payroll cadence isn't here. It lives on your payroll schedules.

Set your payroll funding source

Set payrollSettings.defaultFundingSource with PATCH /v3/payments/payer-settings. A contractor payroll run can't be finalized without one.

curl -X PATCH "https://api.wingspan.app/v3/payments/payer-settings" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "payrollSettings": {
      "runsPayroll": true,
      "defaultFundingSource": { "type": "ExternalBankAccount", "id": "Fs6Lp1Rk9Vx3Nq7Tz2Wb5H" }
    }
  }'

Each funding source is a { type, id } reference to an instrument your Account already owns. You never send bank or card numbers here.

`type`	What it must be
`ExternalBankAccount`	A bank account owned by your Account that's active, a depository account, verified, set to `Business` or `Mixed` usage, and enabled for payments. Link one with `/v3/finance/external-bank-accounts`.
`InternalAccount`	Your Wingspan Wallet, owned by your Account. Add money to it before payroll runs.
`PaymentCard`	An active, verified card owned by your Account. USD runs only.

This is a sensitive change, so it requires recent multi-factor authentication. Without it you get 403 with code: StepUpMfaRequired. Wingspan records every funding source change, with who made it, when, and what it replaced.

The V1 field name fundingSource isn't accepted; use defaultFundingSource. Sending "defaultFundingSource": null removes it and leaves your Account with no payroll funding source. Do that when you're deleting the instrument it names, and set a new source before your next run.

There's no automatic fallback. Your defaultPaymentMethod never funds payroll, so an Account with a linked bank account but no payroll funding source gets 422 when it finalizes a run.

Pay payroll in more than one currency

If you run payroll in several currencies, set a source per currency in fundingSourcesByCurrency. Each key is a currency code, and the instrument's own currency must match the key.

{
  "payrollSettings": {
    "fundingSourcesByCurrency": {
      "CAD": { "type": "ExternalBankAccount", "id": "Dd6Wq1Zk8Tx3Nv5Lm9Rb2H" },
      "GBP": null
    }
  }
}

Send null for a currency to remove its override, so runs in that currency fall back on defaultFundingSource. Other currencies keep theirs.

For a run in currency C, Wingspan picks the funding source in this order:

fundingSourcesByCurrency[C], if set.
Otherwise defaultFundingSource, whatever its currency. Currency conversion applies according to your Account's fee configuration.
Otherwise the run can't be funded. Finalize returns 422 and the run stays Draft.

Contractor and employee payroll use the same funding configuration. There's no separate employee funding source.

fundingSourcesByCurrency applies to payroll only. Paying a single payable directly names its own fundingSource on the pay request.

Other settings you can change

Field	What it does
`defaultAccountCurrency`	Your Account's default currency.
`defaultPaymentMethod`	A convenience default for paying invoices, as `{ type, id }` with `type` `PaymentCard` or `ExternalBankAccount`. It prefills a choice; it never pays anything on its own and doesn't fund payroll.
`payrollSettings.runsPayroll`	Whether your Account runs payroll.
`payrollSettings.status`	`Active` or `Cancelled`. `Cancelled` stops scheduled contractor payroll without losing your cadence; set `Active` to resume.
`employerPayrollSettings.status`	`Active` or `Inactive`. `Inactive` stops new on-cycle employee pay periods. Existing pay periods and runs aren't touched, and off-cycle runs against an existing period still work. Requires an existing employer payroll setup.

Settings Wingspan manages

These fields appear on reads but you can't set them. Sending one returns 422 naming the field, with detailCode: payments.PayerSettingsReadOnlyField. Nothing is silently ignored.

Field	Meaning
`payoutDelay`	Payout timing configured for your Account.
`instantPayoutEligible`	Whether your payees can take instant payouts.
`payrollSettings.enablePlannedPayroll`	A Wingspan-managed enablement flag.
`payrollSettings.instantPayoutFeePaidByClient`	Whether you cover contractors' instant payout fees.
`payrollSettings.fxConversionFeePaidByClient`	Whether you cover contractors' currency conversion fees.

To change these, contact your Wingspan account manager.

What can go wrong

Status and `code`	`detailCode`	Cause and fix
`404 ResourceNotFound`		The funding source doesn't exist, isn't yours, or doesn't qualify (not verified, wrong usage, inactive). The error doesn't say which, on purpose. Check each requirement in the table above.
`422 ValidationError`	`payments.PayrollFundingSourceCurrencyMismatch`	A `fundingSourcesByCurrency` entry names an instrument in a different currency than its key.
`422 ValidationError`	`payments.PayerSettingsReadOnlyField`	You sent a Wingspan-managed field.
`422 ValidationError`	`payments.PayerSettingsRemovedField`	You sent a field V3 no longer accepts, such as `payrollSettings.internationalPayroll` or `employerPayrollSettings.fundingSource`.
`422 ValidationError`	`payments.PayerSettingsDefaultPaymentMethodUnsupported`	`defaultPaymentMethod` named an `InternalAccount`, which isn't supported yet.
`403 Forbidden`	`payments.PayerSettingsRelationshipWriteForbidden`	You called `PATCH /v3/payments/payers/{payerId}/settings`. That path names someone who pays you, not your own Account. Use `/v3/payments/payer-settings`.
`403 StepUpMfaRequired`		Complete the MFA challenge and retry.

Funding timing

Wingspan debits your funding source when you finalize a run, and payouts to payees wait for that debit to clear. A bank debit takes longer to clear than a Wingspan Wallet with money already in it. A run's events.estimatedDepositAt shows when its funding is estimated to clear. Plan your finalize time so funding clears before the date you've promised your payees.

Common mistakes

Setting defaultPaymentMethod and expecting payroll to use it. Payroll only uses payrollSettings.defaultFundingSource and fundingSourcesByCurrency.
Using a card for a non-USD run. A card is rejected as a non-USD entry in fundingSourcesByCurrency.
An empty wallet. A Wallet-funded run needs money in the Wallet before you finalize.
Writing through the payer relationship. /v3/payments/payers/{payerId}/settings is for reading a counterparty's settings, not changing yours.