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.

Listing commissions

Retrieve a paginated list of commissions for your organization:

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

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

Viewing outstanding commissions

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

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

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

try {
  const response = await fetch('https://api.nexpay.com/v2/commissions/export?reportPeriod=2026-03', {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey your-api-key-here',
    },
  });

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

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:

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/v2/commissions/requests', {
    method: 'POST',
    headers: {
      'Authorization': 'ApiKey your-api-key-here',
    },
    body: formData,
  });

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

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

Managing commission requests

Listing requests

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

Getting a single request

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

Updating a request (re-uploading invoice)

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

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

  const response = await fetch('https://api.nexpay.com/v2/commissions/requests/1', {
    method: 'PUT',
    headers: {
      'Authorization': 'ApiKey your-api-key-here',
    },
    body: formData,
  });

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

Downloading documents

Invoice

Download the invoice attached to a commission request:

const response = await fetch('https://api.nexpay.com/v2/commissions/requests/1/invoice', {
  headers: { 'Authorization': 'ApiKey your-api-key-here' },
});
// Response is a PDF binary stream

Proof of payment

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

const response = await fetch('https://api.nexpay.com/v2/commissions/requests/1/proof', {
  headers: { 'Authorization': 'ApiKey your-api-key-here' },
});
// Response is a PDF binary stream

Commission request statuses

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.