# Creating a payee

> Learn how to create and manage payees (beneficiaries) using the Nexpay API.

A payee is the recipient of funds in a Nexpay payment — also known as a beneficiary. Payees represent entities like universities, businesses, or individuals that receive money. Before creating a payment, you need a payee to send the funds to.

---

## Before you start

You will need a valid [API key](/docs/api-keys.md) to authenticate your requests.

> **Note — JSON examples show the unwrapped `data` payload**
>
> Every success response on the wire is `{ "data": { ... } }`. The JSON examples in this guide show the inner `data` value — what you get after `const { data } = await response.json()`. List responses also include top-level `hasMore`, `count`, and sometimes `total`. Error responses are **not** wrapped — see [Errors](/docs/errors.md).

## Checking for existing payees

Before creating a new payee, you can check if one already exists with the same details. This helps avoid duplicates:

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/payees/check-existing?name=University%20of%20Sydney&countryCode=AU&currencyCode=AUD' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'
```

**JavaScript**

```javascript
try {
  const params = new URLSearchParams({
    name: 'University of Sydney',
    countryCode: 'AU',
    currencyCode: 'AUD',
  });

  const response = await fetch(`https://api.nexpay.com.au/v2/payees/check-existing?${params}`, {
    method: 'GET',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
  });

  if (response.ok) {
    const { data } = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders(['X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret'])
    ->get('https://api.nexpay.com.au/v2/payees/check-existing', [
        'name' => 'University of Sydney',
        'countryCode' => 'AU',
        'currencyCode' => 'AUD',
    ]);

$data = $response->json('data');
print_r($data);
```

You can check by any combination of `name`, `countryCode`, `currencyCode`, and `accountNumber`.

---

## Creating a payee

To create a payee, send a `POST` request to the [Payees API](https://v2-spec.nexpay.com.au/#post-/v2/payees) with the payee's name and optionally their country and currency:

**cURL**

```bash
curl -X POST 'https://api.nexpay.com.au/v2/payees' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "University of Sydney",
    "countryCode": "AU",
    "currencyCode": "AUD"
  }'
```

**JavaScript**

```javascript
try {
  const response = await fetch('https://api.nexpay.com.au/v2/payees', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
    body: JSON.stringify({
      "name": "University of Sydney",
      "countryCode": "AU",
      "currencyCode": "AUD"
    }),
  });

  if (response.ok) {
    const { data } = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders(['X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret'])
    ->post('https://api.nexpay.com.au/v2/payees', [
        'name' => 'University of Sydney',
        'countryCode' => 'AU',
        'currencyCode' => 'AUD',
    ]);

$data = $response->json('data');
echo $data['id']; // the new payee id
```

The response will include the created payee with its `id`, which you will use when creating payments:

```javascript
{
  "id": 42,
  "name": "University of Sydney",
  "countryCode": "AU",
  "currencyCode": "AUD",
  "bankName": "ANZ Bank",
  "accountNumber": "****5678",
  "swiftCode": "ANZBAU3M",
  "type": "provider"
}
```

> **Note — Bank details**
>
> Bank account details (such as `bankName`, `accountNumber`, and `swiftCode`) are managed by Nexpay and will be populated once the payee is fully configured. Account numbers are masked in API responses for security.

### Fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | The payee's display name (max 255 characters). For example, `"University of Sydney"`. |
| `countryCode` | string | No | 2-letter [ISO 3166-1 alpha-2](/docs/currencies-countries.md#countries) country code (e.g. `AU`). |
| `currencyCode` | string | No | 3-letter [ISO 4217](/docs/currencies-countries.md#currencies) currency code (e.g. `AUD`). |

---

## Updating a payee

To update an existing payee, send a `PUT` request with the payee's `id`. Currently, only the `name` field can be updated:

**cURL**

```bash
curl -X PUT 'https://api.nexpay.com.au/v2/payees/42' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "University of Sydney - Main Campus"
  }'
```

**JavaScript**

```javascript
try {
  const response = await fetch('https://api.nexpay.com.au/v2/payees/42', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
    body: JSON.stringify({
      "name": "University of Sydney - Main Campus"
    }),
  });

  if (response.ok) {
    const { data } = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders(['X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret'])
    ->put('https://api.nexpay.com.au/v2/payees/42', [
        'name' => 'University of Sydney - Main Campus',
    ]);

$data = $response->json('data');
print_r($data);
```

---

## Listing payees

You can retrieve all payees for your organization using the [query parameters](/docs/queries.md) supported by Nexpay:

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/payees?limit=15&skip=0' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'
```

**JavaScript**

```javascript
try {
  const response = await fetch('https://api.nexpay.com.au/v2/payees?limit=15&skip=0', {
    method: 'GET',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
  });

  if (response.ok) {
    const { data } = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders(['X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret'])
    ->get('https://api.nexpay.com.au/v2/payees', [
        'limit' => 15,
        'skip' => 0,
    ]);

$data = $response->json('data');
print_r($data);
```

## Retrieving a single payee

To get a specific payee by its `id`:

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/payees/42' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'
```

**JavaScript**

```javascript
try {
  const response = await fetch('https://api.nexpay.com.au/v2/payees/42', {
    method: 'GET',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
  });

  if (response.ok) {
    const { data } = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders(['X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret'])
    ->get('https://api.nexpay.com.au/v2/payees/42');

$data = $response->json('data');
print_r($data);
```

---

## Your own company (the "My company" recipient)

When the money goes to **your own tenant** — for example a student paying you directly, with no school involved — the recipient is your **own-company payee**, not a created beneficiary. `GET /v2/payees/tenant` returns them (one per currency), resolved from your organisation, each flagged `isOwnCompany: true`:

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/payees/tenant' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'
```

**JavaScript**

```javascript
const { data } = await fetch('https://api.nexpay.com.au/v2/payees/tenant', {
  headers: { 'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret' },
}).then(r => r.json());

// data.payees: [{ id, name, countryCode, currencyCode, isOwnCompany: true }, ...]
const myCompany = data.payees.find(p => p.currencyCode === 'AUD');
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders(['X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret'])
    ->get('https://api.nexpay.com.au/v2/payees/tenant');

$data = $response->json('data');
// $data['payees']: [['id' => 51, 'name' => ..., 'currencyCode' => 'AUD', 'isOwnCompany' => true], ...]
$myCompany = collect($data['payees'])->firstWhere('currencyCode', 'AUD');
```

```javascript
{
  "payees": [
    {
      "id": 51,
      "name": "Your Org Pty Ltd",
      "countryCode": "AU",
      "currencyCode": "AUD",
      "isOwnCompany": true
    }
  ]
}
```

Use the matching payee's `id` as the recipient `connectorPayeeId` in a `public_payee` role — see [Pay the tenant directly](/docs/guides/payment-intents-manual.md#pay-the-tenant-directly-no-school). This is a reliable, name-independent alternative to searching the public lookup for your own organisation's name (whose legal name need not match its payee names). Pick the entry whose `currencyCode` matches the account you want to receive into; if you only have one, use it.

---

## Things to know

* Only the `name` field is required to create a payee. Country and currency codes are optional but recommended for faster payment processing.
* Payee `id` values are numeric integers (e.g. `42`), unlike payers which use MongoDB ObjectIds.
* Bank account details are masked in responses — only the last 4 digits of the account number are visible.
* Attempting to create a duplicate payee will return a `409 Conflict` error.
* Payees are scoped to your tenant and are not shared across organizations.