Payees and Onboarding

A payee is a person or business you pay. Before a payee can receive money they must complete onboarding, after which Payment Labs marks them payable. This page shows the ways a payee is created, what onboarding asks for, and how you track it.

Before you start

• Creating payees and changing their email need the Write permission (roles Administrator, Expert User and User). Searching and exporting need any payout role. See Permissions.
• Decide what you will use as each payee's referenceId: the ID of that person in your own system. It is how you find the payee again and how Payment Labs tells payees apart. Read Payee Reference IDs before you send your first one.

How a payee is created

A payee belongs to your account and is identified by an email and a referenceId. Any of these creates one:

All of them apply the same matching rules on email and referenceId, so the same person is never created twice. An existing payee is reused, and may have their email or reference ID updated, as the reference ID rules describe.

Step 1: Invite payees

Send an array of 1 to 100 payees to Create Payees.

curl -X POST https://api-sandbox.paymentlabs.io/payors/me/payees \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "email": "[email protected]", "referenceId": "user-1001", "taxJurisdiction": "us" },
    { "email": "[email protected]", "referenceId": "user-1002" }
  ]'

The response is 200 with one result per row, in the same order:

[
  {
    "userId": "U-01JD9A2B3C4D5E6F7G8H9J0K1M",
    "payorId": "C-01JD0Z9Y8X7W6V5T4S3R2Q1P0N",
    "referenceId": "user-1001",
    "email": "[email protected]",
    "onboarded": false,
    "payable": false,
    "currentStep": "personalInformation",
    "result": "success"
  },
  {
    "referenceId": "user-1002",
    "email": "[email protected]",
    "result": "error",
    "error": { "code": "EMAIL_ALREADY_IN_USE", "message": "..." }
  }
]

A 200 does not mean every row succeeded. Check result on each row. A row with "result": "error" changed nothing.

When the row creates a payee, Payment Labs may email them an invitation to set up their account and onboard. The userId is the payee's ID; you use it in calls such as List Payee Payments.

Step 2: Let the payee onboard

Onboarding collects what Payment Labs needs to pay the person legally. currentStep on the payee tells you where they are:

The payee completes these steps either on the Payment Labs payee portal (from the invitation email) or inside your site through the Payee Widget.

Step 3: Know when a payee is payable

A payee is payable when they have complete personal details, a valid payout method, a completed identity check (if your account requires one), the tax form their jurisdiction needs, and are not blocked by Payment Labs.

• payable is true when the payee can be paid under every jurisdiction they have.
• payableByJurisdiction breaks this down per tax jurisdiction, for example { "none": true, "us": false }. A payment uses the value for its own taxJurisdiction.

Subscribe to payee-payability-changed. It fires whenever payable or payableByJurisdiction changes, in either direction. A payee can stop being payable, for example when their payout method becomes invalid.

You do not have to wait for payability before you create or submit payments: submit with autoSubmit: true and each payment is sent as soon as its payee becomes payable. See Creating and Submitting Payments.

Find payees

Use Search Payees. You can filter and sort on userId, referenceId, email, displayFirstName, displayLastName, businessName, type, payable and currentStep. The request format is described in Search, Exports and Pagination.

{
  "filter": {
    "all": [
      { "fact": "payable", "operator": "equals", "value": false },
      { "fact": "currentStep", "operator": "equals", "value": "paymentMethods" }
    ]
  },
  "page": 1,
  "pageSize": 50
}

Search results can be a few seconds behind. To list the payments of one payee, call List Payee Payments. To download every matching payee as a CSV or Excel file, use Export Payees; see Search, Exports and Pagination.

Update a payee's email

Update Payee Email changes the email of one payee, identified by its userId:

curl -X PUT https://api-sandbox.paymentlabs.io/payors/me/payees/U-01JD9A2B3C4D5E6F7G8H9J0K1M \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

• It returns 204. No invitation email is sent.
• If the payee's reference ID was their old email (you created them without one), the reference ID changes to the new email too.
• The payee's sign-in email changes only if they have not finished onboarding and are not a payee of anyone else.
• Your payments to the payee show the new email shortly after.
• 400 EMAIL_ALREADY_IN_USE means another of your payees already has that email.

Change a payee's email or reference ID by sending it

You can also change a payee's email or reference ID by sending the changed value to Create Payees, with a payment, or with a widget URL request. Payee Reference IDs explains when that happens.

Errors and edge cases

Per-row errors on Create Payees:

Errors on the whole request:

Sending the same payee again is safe: a row that matches an existing payee returns that payee with "result": "success" and does not send another invitation.

Next steps

• Payee Widget
• Payee Reference IDs
• Creating and Submitting Payments