Uploading documents

Documents in Nexpay are used to attach supporting files to payments — such as payer identity documents, purpose proof, and invoices. You must upload documents before referencing them in payment or commission requests.

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(). The upload endpoint returns { data: { documentId: "<uuid>" } }; reuse that documentId when referencing the document elsewhere.

Uploading a document

To upload a document, send a POST request with the file as multipart/form-data:

curl -X POST 'https://api.nexpay.com.au/v2/documents' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -F 'file=@passport.jpg'

try {
  const formData = new FormData();
  formData.append('file', fileInput.files[0]);

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

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret',
])->attach('file', file_get_contents('passport.jpg'), 'passport.jpg')
  ->post('https://api.nexpay.com.au/v2/documents');

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

echo $data['documentId'];

The response includes the document's documentId (a UUID), which you'll use when creating payments or commission requests. The field is named documentId, not id — pass it verbatim wherever an upstream call asks for payerIdentityDocumentId, purposeProofDocumentId, etc.

{
  "documentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

File size limit

The maximum file size is 16 MB. Requests exceeding this limit will be rejected.

Where document IDs are used

Uploaded document IDs are referenced in other API calls:

Context	Field	Description
Manual payment with splits	`payerIdentityDocumentId`	Payer's identity document (e.g. passport, driver's license).
Manual payment with splits	`purposeProofDocumentId`	Proof of payment purpose (e.g. invoice, enrollment letter). One per recipient on a split, and every id on the intent must be unique (see "Document uniqueness within an intent" below).
Commissions	`invoice` (file upload)	Invoice for commission withdrawal request.
Conversations	`attachments`	File attachments in conversation messages.

Downloading a document

To download a previously uploaded document, use its documentId. The response is a binary file stream — do NOT call response.json():

curl 'https://api.nexpay.com.au/v2/documents/f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  --output downloaded-file

try {
  const response = await fetch('https://api.nexpay.com.au/v2/documents/f47ac10b-58cc-4372-a567-0e02b2c3d479', {
    method: 'GET',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
  });

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

    // Save or display the file
    console.log('Downloaded file:', 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/documents/f47ac10b-58cc-4372-a567-0e02b2c3d479');

// Binary file stream — do not call ->json()
$contents = $response->body();

echo 'Downloaded file: ' . strlen($contents) . ' bytes';

The response is a binary file stream with application/octet-stream content type.

Combining documents

You can merge multiple uploaded documents into a single ZIP or PDF file. This is useful when you need to bundle several supporting documents together:

curl -X POST 'https://api.nexpay.com.au/v2/documents/combine' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret' \
  -H 'Content-Type: application/json' \
  -d '{
  "documentIds": [
    "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "a23bc45d-67ef-8901-b234-5c6d7e8f9012"
  ]
}'

try {
  const response = await fetch('https://api.nexpay.com.au/v2/documents/combine', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
    body: JSON.stringify({
      "documentIds": [
        "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "a23bc45d-67ef-8901-b234-5c6d7e8f9012"
      ]
    }),
  });

  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',
])->post('https://api.nexpay.com.au/v2/documents/combine', [
    'documentIds' => [
        'f47ac10b-58cc-4372-a567-0e02b2c3d479',
        'a23bc45d-67ef-8901-b234-5c6d7e8f9012',
    ],
]);

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

echo $data['id'];

The response returns a new document with its own id:

{
  "id": "d89ef012-34ab-5678-cdef-901234567890",
  "fileName": "combined.pdf",
  "contentType": "application/pdf",
  "fileSize": 409600
}

Combine fields

Field	Type	Required	Description
`documentIds`	string[]	Yes	Array of document UUIDs to combine. Must contain at least 1 document.

Document uniqueness within an intent

A document can be referenced from multiple contexts (a payment, a conversation, a commission). But within a single payment intent, every document id must be distinct — each recipient's purposeProofDocumentId and the payerIdentityDocumentId must differ. Re-using one documentId across two recipients fails the documents.uniqueDocumentIds rule at submit ([GEN9002]). When the same underlying file legitimately backs two legs (for example a single enrolment letter), upload it once per leg so each gets its own documentId.

Things to know

Documents are scoped to your tenant and cannot be accessed across organizations.
All document IDs are UUID v4 format.
The combine endpoint creates a new document — the original documents remain available.