Creating a payee

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 to authenticate your requests.

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.

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 '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'

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);
}

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 with the payee's name and optionally their country and currency:

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"
  }'

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);
}

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:

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

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 country code (e.g. `AU`).
`currencyCode`	string	No	3-letter ISO 4217 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 -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"
  }'

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);
}

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 supported by Nexpay:

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'

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);
}

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 'https://api.nexpay.com.au/v2/payees/42' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'

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);
}

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 'https://api.nexpay.com.au/v2/payees/tenant' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'

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');

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');

{
  "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. 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.