Payee Reference IDs

How Payment Labs matches a payee from the email and reference ID you send, and when it changes a payee's details.

Every time you name a payee, you send an email, a reference ID, or both. Payment Labs uses them to find the payee, create one, or update the one it finds. Getting this right is what keeps one person from becoming two payees, and keeps a payout from reaching the wrong person.

Before you start

The same rules apply wherever you name a payee:

What a reference ID is

  • Your own identifier for the person, for example the user ID in your database. Use a value that never changes and is never reused for another person.
  • Unique within your account: two of your payees can never share one.
  • Compared exactly as sent, including letter case.
  • Optional on a new payee. If you leave it out, the payee's email (in lower case) becomes their reference ID.

Emails are trimmed and compared in lower case.

The matching rules

In the table, new means no payee of yours has that value, and existing means one does.

EmailReference IDResult
——Error REQUIRED_VALUES_MISSING.
—newError REFERENCE_ID_NOT_FOUND. A new payee needs an email.
—existingThe payee with that reference ID is used. This is the only case where the email can be left out.
new—A new payee is created, with the email as reference ID, and may be invited.
newnewA new payee is created with both values, and may be invited.
existing—The payee with that email is used.
existingsame payee'sThe payee is used. Nothing changes.
existingnewThe payee with that email is used, and their reference ID is changed to the one you sent.
newexistingThe payee with that reference ID is used, and their email is changed to the one you sent.
existinganother payee'sError EMAIL_ALREADY_IN_USE. The email and reference ID belong to two different payees.

Errors come back as 400 with the code above on single-object calls, and as a row error on Create Payees and imports. Create Payees and Get Widget URL require an email, so a row without one fails validation (MISSING_REQUIRED_FIELD) instead.

⚠️

The last three rows change or protect real records. Sending a known email with a new reference ID re-keys that payee: later calls with the old reference ID no longer find them. Sending a known reference ID with a new email moves that payee, and their future payouts, to the new email. Only send a changed value when you mean to change it.

Change a payee's email or reference ID

To change a payee's email on purpose, call Update Payee Email. Otherwise, the two "is changed" rows above change a payee's details as a side effect of any call that names the payee:

  • New email: send the payee's existing reference ID with the new email.
  • New reference ID: send the payee's existing email with the new reference ID.

Depending on the payee's account, the email they sign in with may change too. All your payments to that payee are updated to show the new email and reference ID.

Check before you send

Validate Payee tells you what an email and reference ID would do, without saving anything. Call it before you create a payee or a payment when you are not sure the pair matches your records:

{ "email": "[email protected]", "referenceId": "user-1001" }

The response is always 200. When success is true, effect is NO_CHANGE, NEW_PAYEE, EMAIL_CHANGED or REFERENCE_CHANGED, and summary holds the matched payee. When success is false, error.code is one of the codes in the table below.

In a payment import, every row reports what will happen in userAction before you finish the import:

userActionMeaning
NO_CHANGEThe row matches an existing payee and changes nothing.
NEW_PAYEEA new payee will be created.
EMAIL_CHANGEDAn existing payee's email will change.
REFERENCE_CHANGEDAn existing payee's reference ID will change.

Review every EMAIL_CHANGED and REFERENCE_CHANGED row before you finish the import. An import also refuses a file in which one reference ID appears with two different emails (INCONSISTENT_REFERENCE_ID).

Errors and edge cases

CodeMeaningWhat to do
REQUIRED_VALUES_MISSINGNeither email nor reference ID was sent.Send the email, and the reference ID if you have one.
REFERENCE_ID_NOT_FOUNDOnly a reference ID was sent and no payee has it.Send the email as well to create the payee.
EMAIL_ALREADY_IN_USEThe email belongs to one payee and the reference ID to another.Decide which payee you meant and send that payee's email and reference ID.

Next steps


What’s Next

Did this page help you?