> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infinityapp.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Payees

> Register the people and businesses you pay, collect their bank details yourself or through a hosted page, and track when they become payable.

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](https://docs.infinityapp.in/guides/payee-addresses.md). 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

```bash theme={null}
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" }
  }'
```

```json Response theme={null}
{
  "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`](https://docs.infinityapp.in/guides/payee-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](#resend-an-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

```mermaid theme={null}
stateDiagram-v2
  [*] --> invited
  invited --> details_pending: signs up
  details_pending --> verifying: submits details
  verifying --> active: checks pass
  invited --> active: address added via API
  details_pending --> active: address added via API
  active --> inactive
```

| 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](https://docs.infinityapp.in/guides/payouts.md#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:

```bash theme={null}
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

```bash theme={null}
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](https://docs.infinityapp.in/guides/webhooks.md). 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](https://docs.infinityapp.in/guides/sandbox.md#activate-a-payee).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.