# Creating a payer

> Learn how to create and manage payers using the Nexpay API.

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](/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).

## Creating a payer

To create a payer, send a `POST` request to the [Payers API](https://v2-spec.nexpay.com.au/#post-/v2/payers) with the payer's type and email address.

Payers can be either an `individual` or a `business`:

**cURL**

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

**JavaScript**

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

**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/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:

```javascript
{
  "_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. |

> **Note — Payment payer types**
>
> When sending payer details on a [payment intent](/docs/guides/payment-intents-manual.md), 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](/docs/currencies-countries.md#countries) 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**

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

**JavaScript**

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

**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/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');
```

> **Note — 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**

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

**JavaScript**

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

**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/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](/docs/queries.md) supported by Nexpay:

**cURL**

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

**JavaScript**

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

**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/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.