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:
- Create Payees (
email,referenceId) - Create Payment and Create Virtual Payment (
payeeEmail,payeeReferenceId) - Get Widget URL (
payeeEmail,payeeReferenceId) - Payment Imports (the
Email AddressandPayee Reference IDcolumns) - Invite Wallet Holder and Bulk Invite Wallet Holders (
email,referenceId)
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.
| Reference ID | Result | |
|---|---|---|
| — | — | Error REQUIRED_VALUES_MISSING. |
| — | new | Error REFERENCE_ID_NOT_FOUND. A new payee needs an email. |
| — | existing | The 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. |
| new | new | A new payee is created with both values, and may be invited. |
| existing | — | The payee with that email is used. |
| existing | same payee's | The payee is used. Nothing changes. |
| existing | new | The payee with that email is used, and their reference ID is changed to the one you sent. |
| new | existing | The payee with that reference ID is used, and their email is changed to the one you sent. |
| existing | another payee's | Error 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:
userAction | Meaning |
|---|---|
NO_CHANGE | The row matches an existing payee and changes nothing. |
NEW_PAYEE | A new payee will be created. |
EMAIL_CHANGED | An existing payee's email will change. |
REFERENCE_CHANGED | An 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
| Code | Meaning | What to do |
|---|---|---|
REQUIRED_VALUES_MISSING | Neither email nor reference ID was sent. | Send the email, and the reference ID if you have one. |
REFERENCE_ID_NOT_FOUND | Only a reference ID was sent and no payee has it. | Send the email as well to create the payee. |
EMAIL_ALREADY_IN_USE | The 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
Updated 21 days ago
What’s Next
Next: Funding and Ledger Accounts.
