Resolves who you want to pay to a payee with a walletId, without
paying them yet. A disbursement destination does the same thing
inline, so this call is optional: use it to invite someone ahead of
their first payment.
- A person, by
emailAddressand/ormobileNumber. If they
already have PayKeeper you get their existing wallet (200,
resolution: EXISTING); if not, PayKeeper creates them (201,
resolution: CREATED), withnamerequired. Money can land in
their wallet before they onboard. Add theirssnif you have it. - A company, by
organizationNameand theemailAddressof the
contact who will set it up (pluseinif you have it). A company
already on PayKeeper with that EIN is paid into its own wallet.
Otherwise PayKeeper holds its money under its name until the
contact finishes onboarding the company, then moves it into the
company's own wallet. The same company named again (by EIN, or by
contact and name) is the same payee. - A company already on PayKeeper, by
organizationId.
While a payee has not claimed their account, onboardingUrl is the
link that lets them. It is returned on every read until they claim,
and reissued automatically on your next call if it lapses (people's
links last 14 days, companies' 45). For a new person, notify: true also
has PayKeeper send it; by default (notify: false) nothing is sent. Company invitations are never sent by PayKeeper:
put the link in your own email.
Giving both an email address and a mobile number that belong to two
different people is refused rather than guessed at.
An email address or mobile number is one person. When someone
already has the one you send, name must be theirs: the same family
name and first name, where a short form such as Ben for Benjamin is
fine. Anything else is 409 name_mismatch and nothing is paid, so an
address several of your participants share (a business manager's,
say) can stand for only one of them. Give each person their own email
or mobile number, or pay a company when the money is owed to one: a
loan-out, an estate or a trust is a company payee, not a person. The
dependable pattern is to resolve each participant once here with your
own id as externalId, then pay them by payeeId.
A payee shows only what you have told PayKeeper. Its name,
emailAddress and mobileNumber are the ones you gave, never the
details PayKeeper holds for the person, so resolving someone by email
does not reveal their mobile number or name.
Tax ids are optional. A person takes an ssn and a company an
ein; neither is needed to be paid. PayKeeper stores an SSN only
encrypted, keeps it out of its logs and never returns it: the payee
shows ssnLast4 (a company, einLast4). An SSN for someone who
already has a different one on file with you is refused, not
replaced.
| Status | code | When |
|---|---|---|
| 400 | missing_contact | Nobody is named: no email, mobile number, company or organization id. |
| 400 | payee_name_required | The person is new to PayKeeper and no name was given. |
| 400 | missing_field | A company has no contact emailAddress, or an ein came without an organizationName (a person has an ssn, not an ein). |
| 400 | invalid_field | A field is the wrong type or too long, emailAddress is not an email address, an ein or ssn is not nine digits (or an impossible SSN, such as area 000), a company was given a mobileNumber or an ssn, or metadata breaks its limits. |
| 400 | ambiguous_payee | organizationId came with other payee fields. |
| 400 | invalid_body | The body is not a JSON object. |
| 400 | invalid_idempotency_key | The Idempotency-Key is longer than 255 characters, is not printable ASCII, or was sent twice. |
| 404 | organization_not_found | organizationId is not an organization on PayKeeper. |
| 409 | contact_mismatch | The email address and mobile number belong to two different people. |
| 409 | ssn_mismatch | You gave this person a different ssn before. |
| 409 | name_mismatch | The email address or mobile number belongs to someone else: the family name or first name in name is not theirs. |
| 409 | ein_name_mismatch | The ein belongs to a company with a different name. |
| 409 | payee_external_id_mismatch | This payee already has a different externalId; a payee has one. |
| 409 | external_id_already_exists | Another of your payees, or another of your objects, has this externalId. Nothing is created. |
| 409 | external_id_busy | Another request with this externalId is being processed. Nothing is created; send it again in a moment. |
| 409 | payee_busy | Another request is setting up the same new person right now. Nothing was created; send it again after Retry-After seconds. |
| 409 | idempotency_key_in_use | A request with this Idempotency-Key is still running. Send it again after Retry-After seconds. |
| 422 | invalid_mobile_number | mobileNumber is not a valid mobile number. |
| 422 | payee_not_created | PayKeeper could not create the person. |
| 422 | ssn_not_accepted | This environment cannot store an SSN yet. Leave ssn out. |
| 422 | idempotency_key_reused | This Idempotency-Key was already used for a different request. Use a new key. |
| 503 | upstream_busy | PayKeeper's banking provider asked it to slow down. Send it again after Retry-After seconds, with the same Idempotency-Key. |
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||