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.

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.

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:

curl -X POST 'https://api.nexpay.com.au/v2/payers' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -H 'Content-Type: application/json' \
  -d '{
  "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"
  }
}'

try {
  const response = await fetch('https://api.nexpay.com.au/v2/payers', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
    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: payer } = await response.json();

    console.log(payer);
  } 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/payers', [
    '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',
    ],
]);

$payer = $response->json('data');

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.

Field	Description
`payerType`	Either `individual` or `business`.
`email`	The payer's email address. Must be unique per tenant.

Payer types

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

Type	Description
`individual`	A person sending money (e.g. a student, parent, or private individual).
`business`	A company or organization sending money.

Payment payer types

When sending payer details on a payment intent, the payer.details.payerType field uses more granular types (e.g. student, parent, agent, education-agency). These describe the payer's relationship to the payment, not the saved payer record type.

Adding profile details

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

Field	Type	Description
`firstName`	string	Payer's first name.
`lastName`	string	Payer's last name.
`phone`	string	Phone number with country code (e.g. `+61412345678`).
`dob`	string	Date of birth in `YYYY-MM-DD` format.

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.

Field	Type	Description
`country`	string	2-letter country code (e.g. `AU`).
`line1`	string	Street address.
`line2`	string	Additional address details (apartment, suite, etc.).
`city`	string	City name.
`state`	string	State or province.
`postalCode`	string	Postal or ZIP code.

Creating a business payer

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

curl -X POST 'https://api.nexpay.com.au/v2/payers' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -H 'Content-Type: application/json' \
  -d '{
  "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"
  }
}'

try {
  const response = await fetch('https://api.nexpay.com.au/v2/payers', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
    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: payer } = await response.json();

    console.log(payer);
  } 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/payers', [
    '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',
    ],
]);

$payer = $response->json('data');

Tax identification

The taxIdentificationNumber field can be used for any tax ID format. The company.abn field is specific to Australian Business Numbers.

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:

curl -X PUT 'https://api.nexpay.com.au/v2/payers/507f1f77bcf86cd799439011' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -H 'Content-Type: application/json' \
  -d '{
  "profile": {
    "phone": "+61498765432"
  },
  "address": {
    "line1": "789 New Street",
    "city": "Melbourne",
    "state": "VIC",
    "postalCode": "3000"
  }
}'

try {
  const response = await fetch('https://api.nexpay.com.au/v2/payers/507f1f77bcf86cd799439011', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
    body: JSON.stringify({
      "profile": {
        "phone": "+61498765432"
      },
      "address": {
        "line1": "789 New Street",
        "city": "Melbourne",
        "state": "VIC",
        "postalCode": "3000"
      }
    }),
  });

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

    console.log(payer);
  } 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/payers/507f1f77bcf86cd799439011', [
    'profile' => [
        'phone' => '+61498765432',
    ],
    'address' => [
        'line1' => '789 New Street',
        'city' => 'Melbourne',
        'state' => 'VIC',
        'postalCode' => '3000',
    ],
]);

$payer = $response->json('data');

Listing payers

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

curl 'https://api.nexpay.com.au/v2/payers?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/payers?limit=15&skip=0', {
    method: 'GET',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
  });

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

    console.log(payerList);
  } 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/payers', [
    'limit' => 15,
    'skip' => 0,
]);

$payerList = $response->json('data');

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.