Payer relationship settings writes are forbidden

patch deprecated

https://api.wingspan.app/v3/payments/payers/{payerId}/settings

This relationship-scoped mutation is retained only as a compatibility endpoint. Valid, authenticated requests return 403 with detailCode payments.PayerSettingsRelationshipWriteForbidden. A payee cannot change a linked payer Account's global payment or payroll settings. Payer Accounts configure their own contractor-payroll funding source through /payments/payer-settings.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

payerId

string

required

^[A-Za-z0-9_.]{22,80}$

Body Params

PATCH semantics: omitted fields are left unchanged. There is no clear mechanism for any of these fields — each is a plain replace-on-presence.

payoutDelay

integer

instantPayoutEligible

boolean

defaultAccountCurrency

string

enum

ISO 4217 currency code

defaultPaymentMethod

object

Sets the canonical Client profile pointer. PaymentCard and ExternalBankAccount references must resolve to instruments owned by the Account. InternalAccount is not representable by that profile and returns 422 payments.PayerSettingsDefaultPaymentMethodUnsupported.

payrollSettings

object

Non-empty payroll policy mutation. Omitted properties are unchanged. defaultFundingSource cannot be cleared through this endpoint. Cadence is not writable here — use PATCH /payments/payroll-schedules/{type}.

employerPayrollSettings

object

Lifecycle only. Requires an existing EmployerPayrollProfile whose schedule has been initialized — 422 when the Account has no cadence yet, 404 when it has no profile. Cadence is written through PATCH /payments/payroll-schedules/Employee.

Headers

Idempotency-Key

string

length between 1 and 255

^[\x21-\x7e]{1,255}$

Optional idempotency token for authenticated POST and PATCH requests. Reusing the same key and body returns the cached response for 24 hours, except credential operations that explicitly document a 409 because one-time secret material is never cached; reusing it with a different body returns 409 IdempotencyKeyConflict. Use 1-255 printable ASCII characters.

X-Wingspan-Account

string

^(?:[A-Za-z0-9_.]{22}|[a-f0-9]{24})$

Select the Account for an Account-scoped operation. A direct ServiceAccount API key MUST supply this header, and the target must be within the ServiceAccount owner's or Authorization grant's Account boundary. A Person bearer may select an Account on which it has an active Stakeholder, and an Account session may select its bound Account (or a descendant only when the session explicitly includes descendants).

Responses

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/problem+json

400Malformed request syntax

401Unauthenticated

403Forbidden

404Resource not found

422Validation error

501This operation is not yet available