# Commissions

> Learn how to track, export, and withdraw commissions using the Nexpay API.

Commissions are earnings accrued by your organization on payments processed through Nexpay. You can track commissions per payment, view outstanding totals, export reports, and submit withdrawal requests with supporting invoices.

---

## 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).

## Listing commissions

Retrieve a paginated list of commissions for your organization:

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/commissions?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/commissions?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);
}
```

**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/commissions', [
    'limit' => 15,
    'skip' => 0,
]);

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

print_r($data);
```

Each commission entry is tied to a payment and includes the amounts and spread:

```javascript
{
  "commissions": [
    {
      "paymentId": 123,
      "studentName": "John Doe",
      "payeeName": "University of Sydney",
      "payerAmount": 5125.5,
      "payerCurrency": "USD",
      "commissionAmount": 51.25,
      "commissionCurrency": "AUD",
      "commissionSpread": 0.01,
      "paymentDate": "2026-03-10T08:30:00.000Z"
    }
  ]
}
```

### Commission fields

| Field | Description |
| --- | --- |
| `paymentId` | The payment this commission was earned on. |
| `payerAmount` | Total amount the payer sent. |
| `commissionAmount` | Commission earned on this payment. |
| `commissionCurrency` | Currency of the commission. |
| `commissionSpread` | Commission rate as a decimal (e.g. `0.01` = 1%). |
| `paymentDate` | When the payment was completed. |
| `commissionRequestDate` | When a withdrawal was requested (if applicable). |
| `commissionPaidDate` | When the commission was paid out (if applicable). |

---

## Viewing outstanding commissions

Get a summary of commissions that haven't been requested for withdrawal yet, with per-currency totals:

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/commissions/outstanding' \
  -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/commissions/outstanding', {
    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);
}
```

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

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

print_r($data);
```

```javascript
{
  "items": [
    {
      "paymentId": 123,
      "commissionAmount": 51.25,
      "commissionCurrency": "AUD",
      "paymentDate": "2026-03-10T08:30:00.000Z"
    }
  ],
  "totals": [
    { "currency": "AUD", "amount": 512.5 },
    { "currency": "USD", "amount": 125.0 }
  ],
  "thresholdMet": true
}
```

The `thresholdMet` field indicates whether your outstanding commissions meet the minimum payout threshold.

---

## Exporting commissions

Download a CSV report of commissions for a specific month:

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/commissions/export?reportPeriod=2026-03' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -o commissions-2026-03.csv
```

**JavaScript**

```javascript
try {
  const response = await fetch('https://api.nexpay.com.au/v2/commissions/export?reportPeriod=2026-03', {
    method: 'GET',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
  });

  if (response.ok) {
    const blob = await response.blob();

    // Save the CSV file
    console.log('Exported CSV:', blob.size, 'bytes');
  } 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/commissions/export', [
    'reportPeriod' => '2026-03',
]);

// Save the CSV file
file_put_contents('commissions-2026-03.csv', $response->body());
```

The `reportPeriod` query parameter must be in `yyyy-MM` format (e.g. `2026-03` for March 2026).

---

## Creating a commission request

To withdraw your accrued commissions, submit a commission request with the payment IDs and total amount. You can optionally attach an invoice:

**cURL**

```bash
curl -X POST 'https://api.nexpay.com.au/v2/commissions/requests' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -F 'paymentIds=[123,456,789]' \
  -F 'commissionTotalAmount=512.50' \
  -F 'invoice=@invoice.pdf'
```

**JavaScript**

```javascript
try {
  const formData = new FormData();
  formData.append('paymentIds', JSON.stringify([123, 456, 789]));
  formData.append('commissionTotalAmount', '512.50');
  formData.append('invoice', invoiceFile); // Optional invoice file

  const response = await fetch('https://api.nexpay.com.au/v2/commissions/requests', {
    method: 'POST',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
    body: formData,
  });

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

    console.log(commissionRequest);
  } 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',
])
    ->attach('invoice', file_get_contents('invoice.pdf'), 'invoice.pdf')
    ->post('https://api.nexpay.com.au/v2/commissions/requests', [
        'paymentIds' => json_encode([123, 456, 789]),
        'commissionTotalAmount' => '512.50',
    ]);

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

print_r($commissionRequest);
```

```javascript
{
  "requestId": 1,
  "status": "submitted",
  "totalAmount": 512.5,
  "paymentCount": 3,
  "createdOn": "2026-03-12T10:00:00.000Z",
  "payments": [
    {
      "paymentId": 123,
      "studentName": "John Doe",
      "commissionAmount": 51.25,
      "commissionCurrency": "AUD"
    }
  ]
}
```

### Request fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `paymentIds` | number[] | Yes | Array of payment IDs to include in the request (minimum 1). |
| `commissionTotalAmount` | string | Yes | Total commission amount being requested. |
| `invoice` | file | No | Invoice document (multipart file upload). |

---

## Managing commission requests

### Listing requests

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/commissions/requests' \
  -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/commissions/requests', {
    method: 'GET',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
  });

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

    console.log(requests);
  } 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/commissions/requests');

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

print_r($requests);
```

### Getting a single request

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/commissions/requests/1' \
  -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/commissions/requests/1', {
    method: 'GET',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
  });

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

    console.log(commissionRequest);
  } 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/commissions/requests/1');

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

print_r($commissionRequest);
```

### Updating a request (re-uploading invoice)

You can re-upload an invoice for a request that hasn't been paid yet:

**cURL**

```bash
curl -X PUT 'https://api.nexpay.com.au/v2/commissions/requests/1' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -F 'invoice=@invoice.pdf'
```

**JavaScript**

```javascript
try {
  const formData = new FormData();
  formData.append('invoice', updatedInvoiceFile);

  const response = await fetch('https://api.nexpay.com.au/v2/commissions/requests/1', {
    method: 'PUT',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
    body: formData,
  });

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

    console.log(commissionRequest);
  } 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',
])
    ->attach('invoice', file_get_contents('invoice.pdf'), 'invoice.pdf')
    ->put('https://api.nexpay.com.au/v2/commissions/requests/1');

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

print_r($commissionRequest);
```

---

## Downloading documents

### Invoice

Download the invoice attached to a commission request:

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/commissions/requests/1/invoice' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -o invoice.pdf
```

**JavaScript**

```javascript
const response = await fetch('https://api.nexpay.com.au/v2/commissions/requests/1/invoice', {
  headers: { 'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret' },
});
// Response is a PDF binary stream
```

**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/commissions/requests/1/invoice');

// Response is a PDF binary stream
file_put_contents('invoice.pdf', $response->body());
```

### Proof of payment

After a commission request is marked as paid, download the proof of payment:

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/commissions/requests/1/proof' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -o proof-of-payment.pdf
```

**JavaScript**

```javascript
const response = await fetch('https://api.nexpay.com.au/v2/commissions/requests/1/proof', {
  headers: { 'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret' },
});
// Response is a PDF binary stream
```

**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/commissions/requests/1/proof');

// Response is a PDF binary stream
file_put_contents('proof-of-payment.pdf', $response->body());
```

---

## Commission request statuses

| Status | Description |
| --- | --- |
| `submitted` | Request has been submitted and is awaiting review. |
| `paid` | Commission has been paid out. Proof of payment is available for download. |
| `rejected` | Request was rejected. You can review and resubmit with updated details. |

---

## Things to know

* Commissions are automatically calculated for each payment based on your organization's commission spread.
* The `commissionSpread` is a decimal value (e.g. `0.01` = 1%). See [Percentages](/docs/currencies-countries.md#percentages).
* Outstanding commissions must meet a minimum threshold before a withdrawal request can be submitted.
* You can only re-upload invoices for requests in `submitted` status.
* Proof of payment documents are only available after a request is marked as `paid`.