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.

Checking for existing payees

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

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

  const response = await fetch(`https://api.nexpay.com/v2/payees/check-existing?${params}`, {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey your-api-key-here',
    },
  });

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

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:

try {
  const response = await fetch('https://api.nexpay.com/v2/payees', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
    },
    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);
}

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

Fields

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:

try {
  const response = await fetch('https://api.nexpay.com/v2/payees/42', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
    },
    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);
}

Listing payees

You can retrieve all payees for your organization using the query parameters supported by Nexpay:

try {
  const response = await fetch('https://api.nexpay.com/v2/payees?limit=15&skip=0', {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey your-api-key-here',
    },
  });

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

Retrieving a single payee

To get a specific payee by its id:

try {
  const response = await fetch('https://api.nexpay.com/v2/payees/42', {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey your-api-key-here',
    },
  });

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

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.