Creating a payer

A payer is the person or entity sending money through Nexpay. Before creating a payment, you need to create a payer record with their details. Payers can be saved and reused across multiple payments, so you only need to collect their information once.

Before you start

You will need a valid API key to authenticate your requests.

Creating a payer

To create a payer, send a POST request to the Payers API with the payer's type and email address.

Payers can be either an individual or a business:

try {
  const response = await fetch('https://api.nexpay.com/v2/payers', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
    },
    body: JSON.stringify({
      "payerType": "individual",
      "email": "jane.doe@example.com",
      "profile": {
        "firstName": "Jane",
        "lastName": "Doe",
        "phone": "+61412345678",
        "dob": "1990-05-15"
      },
      "address": {
        "country": "AU",
        "line1": "123 Main Street",
        "line2": "Suite 4",
        "city": "Sydney",
        "state": "NSW",
        "postalCode": "2000"
      }
    }),
  });

  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 payer with its _id, which you will use when creating payments:

{
  "_id": "507f1f77bcf86cd799439011",
  "payerType": "individual",
  "email": "jane.doe@example.com",
  "profile": {
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+61412345678",
    "dob": "1990-05-15"
  },
  "address": {
    "country": "AU",
    "line1": "123 Main Street",
    "line2": "Suite 4",
    "city": "Sydney",
    "state": "NSW",
    "postalCode": "2000"
  },
  "createdAt": "2026-04-06T10:00:00.000Z",
  "updatedAt": "2026-04-06T10:00:00.000Z"
}

Required fields

Only payerType and email are required to create a payer. All other fields are optional and can be added later via an update.

Payer types

When creating a saved payer record, you specify a broad type:

Adding profile details

The profile object contains personal information about the payer. All fields within profile are optional:

Adding an address

The address object contains the payer's residential or business address. All fields are optional, but if you provide country, it must be a 2-letter ISO 3166-1 alpha-2 code.

Creating a business payer

When creating a business payer, you can include the company object with the business details:

try {
  const response = await fetch('https://api.nexpay.com/v2/payers', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
    },
    body: JSON.stringify({
      "payerType": "business",
      "email": "accounts@acmecorp.com",
      "company": {
        "name": "ACME Corp",
        "abn": "51 824 753 556"
      },
      "taxIdentificationNumber": "123456789",
      "address": {
        "country": "AU",
        "line1": "456 George Street",
        "city": "Sydney",
        "state": "NSW",
        "postalCode": "2000"
      }
    }),
  });

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

Updating a payer

To update an existing payer, send a PUT request with the payer's _id. Only include the fields you want to change — all fields are optional in update requests:

try {
  const response = await fetch('https://api.nexpay.com/v2/payers/507f1f77bcf86cd799439011', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
    },
    body: JSON.stringify({
      "profile": {
        "phone": "+61498765432"
      },
      "address": {
        "line1": "789 New Street",
        "city": "Melbourne",
        "state": "VIC",
        "postalCode": "3000"
      }
    }),
  });

  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 payers

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

try {
  const response = await fetch('https://api.nexpay.com/v2/payers?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);
}

Things to know

• Payer email addresses must be unique within your organization. Attempting to create a duplicate will return a 409 Conflict error.
• Payers are scoped to your tenant — they are not shared across organizations.
• Once created, payers can be referenced by their _id when creating payments.