Overview

When adding payments, you can specify a payeeEmail and a payeeReferenceId. Below is a table that explains the behavior of the platform based on what you specify for each of those fields.

To help with clear context, here's a definition of the terms used in the table:

NULL: Empty, null or undefined value
NEW: A value not used before. Example: for payeeEmail it means an email you have not added before. For payeeReferenceId it means a unique ID not currently in use by any payee
EXISTING: A value for payeeEmail or payeeReferenceId that is currently associated with an existing payee.

`payeeEmail`	`payeeReferenceId`	Expected Behavior
`NULL`	`NULL`	Validation Error
`NEW`	`NULL`	New payee is created and automatically invited to onboard
`NULL`	`NEW`	Validation Error
`NEW`	`NEW`	New payee is created and automatically invited to onboard
`NULL`	`EXISTING`	The existing referenced payee will be used. Note: This is the only scenario where the `payeeEmail` field is not required.
`EXISTING`	`NULL`	The existing referenced payee will be used.
`EXISTING`	`NEW`	The existing referenced payee associated with the `payeeEmail` will be used. Additionally that payee's reference ID will be changed to the new `payeeReferenceId` value. NOTE: This is the way to change a payee's reference ID on file.
`NEW`	`EXISTING`	The referenced existing payee associated with the `payeeReferenceId` will be used. Additionally that payee's email will be changed t the newly informed `payeeEmail`. NOTE: This is the way to change a payee's email on file.
`EXISTING`	`EXISTING`	One of two things will happen here: If the email and reference ID here points to the same payee, then the referenced payee is used. If the email and reference ID here points to different payees, then you will be given a validation error.