Payee Payability Changed

payee-payability-changed tells you that a payee can now be paid, or can no longer be paid. A payee is payable when all of these are true:

Their personal or business information is complete.
They have a valid payout method.
They passed identity verification, if your account requires it.
Their tax forms are complete, if your account requires them.
They are not blocked.

When it fires

When the payee's payable value changes, in either direction.
When payableByJurisdiction changes, for example when the payee completes the tax form for one more jurisdiction while payable stays the same.

Payability changes as the payee onboards in the payee widget, and when Payment Labs re-checks a payee, for example after a payout method fails validation.

What to do

When payable becomes true, submit the payee's draft payments with Submit Payment. Payments with auto-submit on are submitted for you.
When payable becomes false, read currentStep and ask the payee to finish that step.

Payload

data is the payee, read when the webhook is sent. Fields with no value are omitted.

Field	Type	Description
`userId`	string	Payee ID. Use it wherever the API asks for a `payeeId`.
`payorId`	string	Your payor ID.
`referenceId`	string	Your own reference for the payee.
`email`	string	Payee's email address.
`payable`	boolean	`true` if the payee can be paid now.
`payableByJurisdiction`	object	Payability per tax jurisdiction. Keys are jurisdiction codes (`us`, `de`, `fi`, `gb`, `my`, `pl`, `sa`, `se`, `none`). Values are `true` if the payee can be paid under that jurisdiction's rules. `none` covers payments with no tax jurisdiction.
`type`	string	`personal` or `business`.
`firstName`	string	Payee's first name.
`middleName`	string	Payee's middle name.
`lastName`	string	Payee's last name.
`businessName`	string	Business name, for a `business` payee.
`contactFirstName`	string	First name of the business's contact person.
`contactLastName`	string	Last name of the business's contact person.
`displayFirstName`	string	First name to show in lists.
`displayLastName`	string	Last name to show in lists.
`taxJurisdictions`	string[]	Tax jurisdictions that apply to the payee.
`currentStep`	string	Onboarding step the payee must finish next: `identityVerification`, `personalInformation`, `paymentMethods`, or `taxForms`. Absent once onboarding is complete.
`onboarded`	boolean	`true` once the payee's personal information has been accepted. It stays `true` afterwards and does not cover payout methods or tax forms: use `payable` to know whether the payee can be paid.

data is null if the payee no longer exists when the webhook is sent.

Example

The full request body Payment Labs sends:

{
  "payorId": "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
  "event": "payee-payability-changed",
  "timestamp": "2026-03-12T11:47:30.215Z",
  "data": {
    "userId": "U-01JBX6M2N8P4Q6R8S0T2V4W6Y8",
    "payorId": "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
    "referenceId": "player-1042",
    "email": "[email protected]",
    "onboarded": true,
    "payable": true,
    "payableByJurisdiction": {
      "none": true,
      "us": true
    },
    "firstName": "Jordan",
    "lastName": "Lee",
    "type": "personal",
    "displayFirstName": "Jordan",
    "displayLastName": "Lee",
    "taxJurisdictions": ["us"]
  }
}