Payees

A payee is a person or business you send payouts to. A payee is created with a name and an email address, and becomes payable once they have a verified bank account, called a payee address. You can collect the bank details in your own product and submit them through the API, or have the payee enter them on a page hosted by Infinity.

Key concepts

status: where the payee is in onboarding. Only active payees are paid immediately; payouts to anyone else are created on hold.
currency: the currency the payee is paid in. It’s set by their bank account, or by the first payout created for them while they’re still onboarding, and it doesn’t change after that.
send_invite: whether Infinity emails the payee their onboarding link. With false, Infinity never contacts the payee, and you receive the link to deliver yourself.
reference and metadata: your own identifiers and data, returned on every read and event.

Create a payee

curl "$BASE/payees" \
  -H "Authorization: Bearer $INFINITY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Maria",
    "last_name": "Lopez",
    "email": "maria@example.com",
    "send_invite": false,
    "reference": "vendor-829",
    "metadata": { "team": "design" }
  }'

Response

{
  "id": "payee_c8pnahcrxqzd3z8d",
  "first_name": "Maria",
  "last_name": "Lopez",
  "email": "maria@example.com",
  "currency": null,
  "status": "invited",
  "send_invite": false,
  "onboarding_url": "https://…",
  "reference": "vendor-829",
  "metadata": { "team": "design" },
  "created_at": "2026-10-26T10:00:00Z",
  "updated_at": "2026-10-26T10:00:00Z"
}

Field	Required	Rules
`first_name`, `last_name`	Yes	Up to 100 characters each. For a business payee, use the business name.
`email`	Yes	A valid address, up to 255 characters, unique within your account.
`send_invite`	No	Defaults to `true`.
`reference`	No	Up to 100 characters. Doesn’t have to be unique.
`metadata`	No	Up to 20 string key-value pairs.

The request doesn’t take a currency. The Idempotency-Key header is optional here and recommended if you retry creates automatically.

Collecting bank details

	Direct (API)	Hosted onboarding
How	You call `POST /payees/{id}/addresses` with the bank details	The payee opens `onboarding_url` and completes Infinity’s form
Payee experience	Entirely inside your product	Infinity-hosted page
Payable	As soon as the address is added	When the payee finishes the form and verification
Available for	USD, EUR and GBP payees	All payees; required for INR

Hosted onboarding

With send_invite: true, Infinity emails the payee a link to sign up and add their bank details.
With send_invite: false, the create response carries onboarding_url for you to deliver through your own channel.

onboarding_url is returned only in the create and resend-invite responses. It’s null on every other read and inside events, so the link never sits in event stores or logs. Deliver it, or store it securely, when you receive it.

Payee statuses

Status	Meaning	Payouts created now
`invited`	Created; the payee hasn’t signed up.	Are created on hold
`details_pending`	Signed up, but hasn’t submitted bank details.	Are created on hold
`verifying`	Details submitted; verification is running. INR payees complete identity checks here.	Are created on hold
`active`	Ready to be paid.	Are sent immediately
`inactive`	Can’t receive payouts.	Are rejected

Payouts created on hold are reserved in the wallet and released automatically once the payee becomes active. See Payouts on hold.

Find a payee

An email address can belong to only one payee per account. A second create with the same email fails with 409 payee_exists, and the error message names the existing payee’s ID. To look a payee up by email:

curl "$BASE/payees?email=maria@example.com" -H "Authorization: Bearer $INFINITY_KEY"

GET /payees also filters by status and pages with limit and starting_after, newest first.

Resend an invite

curl -X POST "$BASE/payees/payee_c8pnahcrxqzd3z8d/invite" -H "Authorization: Bearer $INFINITY_KEY"

Resending rotates the onboarding link, so any earlier link stops working. With send_invite: true Infinity emails the new link; with send_invite: false the response carries it in onboarding_url. A payee who is already active returns 409 payee_already_active.

Payees in India

On accounts enabled for payouts to India, every payee’s currency is inr from creation. INR payees must complete identity verification and add their bank details through hosted onboarding, so send them onboarding_url or use send_invite: true. Adding an INR bank account through the API fails with 400 kyc_required.

Events

Subscribe to payee.* on a webhook endpoint. Most integrations act on payee.active, which signals that payouts to the payee are now sent immediately and that any payouts on hold will be released at the next daily release.

Not available in v1

Updating or deleting a payee.
Creating payees in bulk through the API. The dashboard’s CSV upload covers bulk onboarding.

In the sandbox

The sandbox never emails payees, and onboarding_url doesn’t lead to a working page. Add bank details through the API, or use the activate helper.

Get started

Concepts

Build reliably