Commissions

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

Listing commissions

Retrieve a paginated list of commissions for your organization:

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'

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

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:

{
  "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 'https://api.nexpay.com.au/v2/commissions/outstanding' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'

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

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

{
  "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 '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

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

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

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

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

{
  "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 'https://api.nexpay.com.au/v2/commissions/requests' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'

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

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 'https://api.nexpay.com.au/v2/commissions/requests/1' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'

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

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

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

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

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

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

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

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