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.

Uploading a document

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

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

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

The response includes the document id (UUID), which you'll use when creating payments or commission requests:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "fileName": "passport-scan.pdf",
  "contentType": "application/pdf",
  "fileSize": 204800
}

Where document IDs are used

Uploaded document IDs are referenced in other API calls:

Downloading a document

To download a previously uploaded document, use its id:

try {
  const response = await fetch('https://api.nexpay.com/v2/documents/f47ac10b-58cc-4372-a567-0e02b2c3d479', {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey your-api-key-here',
    },
  });

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

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:

try {
  const response = await fetch('https://api.nexpay.com/v2/documents/combine', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
    },
    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);
}

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

Things to know

• Documents are scoped to your tenant and cannot be accessed across organizations.
• All document IDs are UUID v4 format.
• Uploaded documents can be referenced in multiple places (payments, conversations, commissions).
• The combine endpoint creates a new document — the original documents remain available.