DEVELOPER TOOLS

Node.js SDK

Integrate payments, bank accounts, check proofs, documents and tax files into your Node.js application. This guide covers installation, sandbox requests, file uploads, response handling and production configuration.

Node.js 22+Version 1.0.1
Download SDK

Install the SDK

Download and extract the package, then run these commands from the extracted smartpayables-nodejs directory.

Uses native fetch and fast-xml-parser. Designed for server-side JavaScript with ES modules.

TERMINALInstallation
npm install

Import Client from src/index.js. To use the SDK from another project, run npm install /path/to/smartpayables-nodejs and import from @smartpayables/sdk. The included pnpm lockfile is available for pnpm users.

Make your first request

Set SMARTPAYABLES_CLIENT_ID and SMARTPAYABLES_API_KEY in your server environment using your sandbox credentials. The client sends client_id and akey automatically. Your account must allow your public IP address.

This example retrieves the first 10 payments from the sandbox. It is included as examples/quickstart.mjs in the download.

JAVASCRIPTSandbox quickstart
import { Client, ApiError } from '../src/index.js';

const client = new Client(
	process.env.SMARTPAYABLES_CLIENT_ID,
	process.env.SMARTPAYABLES_API_KEY,
);

try {
	const response = await client.request('payments/get-payment-list', {
		page: 1,
		per_page: 10,
	});

	if (response.format === 'json') {
		console.log(response.json());
	} else {
		console.log(response.xml());
	}
} catch (error) {
	if (!(error instanceof ApiError)) {
		throw error;
	}

	// Inspect error.response for API details in your application.
	console.error(error.message);
	process.exitCode = 1;
}
TERMINALRun the example
node examples/quickstart.mjs

Work with responses

Response format is configured for your account. Contact SmartPayables support to enable JSON. XML remains supported, and authentication errors may return XML even when JSON is enabled. Check the response format property before accessing the parsed body. The SDK detects the format; an Accept header does not change your account configuration.

Use response.json() for a JavaScript object, response.xml() for a parsed XML object, and response.body for a Buffer. XML attributes use the @_ prefix. ApiError.response contains the response when available. The timeout is in milliseconds.

Response property Meaning
statusCode HTTP status code. Check API error details as well as the HTTP status.
format json, xml or binary.
contentType Content-Type header returned by the API.
body Original response body, including binary downloads.

Send parameters and files

Pass an endpoint path without a leading slash, followed by a map of API parameters. All calls use POST. Field names and required parameters match the API reference. Send amounts as decimal strings, such as "1250.00". Null values are omitted; booleans become 1 or 0. For repeated values or files, use indexed keys such as item[0], item[1] or insert_file_multiple[0].

Pass file field names and local file paths as the third argument. The SDK builds the multipart request. This example uploads a check payment file using your configured CSV mapping:

JAVASCRIPTFile upload
const uploaded = await client.request('payments/upload',
	{ method_id: 2 },
	{ userfile: './payments.csv' },
);
Adding or uploading payments does not release them. Review the returned records and IDs, then call the appropriate Confirm endpoint explicitly. The SDK never confirms a payment or retries a request automatically. If a request times out, check its outcome before submitting it again. Payment confirmation reference
Upload Endpoint File field
Payment file payments/upload userfile
Document documents/add document_file
Bank signature bank-accounts/add sig_file
Tax file tax-files/upload tax_file

This client buffers multipart uploads in memory. Size your application memory for the combined files in each request.

Download a check proof

Check proof images return binary JPEG data. Replace 1001 with a check proof ID from your sandbox account.

JAVASCRIPTBinary response
import { writeFile } from 'node:fs/promises';

const proof = await client.request('bank-accounts/check-proofs/get-proof-image',
	{ check_proof_id: 1001 },
);
await writeFile('check-proof.jpg', proof.body);

Handle errors

HTTP failures, API error responses, invalid JSON/XML and transport failures raise an SDK exception. Inspect its response when present, including the response format and API error details. A response can report an API error even with HTTP 200. Keep credentials and payment data out of application logs.

Extend the exception handler in the quickstart to inspect the response when a request fails:

JAVASCRIPTException handling
catch (error) {
	if (!(error instanceof ApiError)) {
		throw error;
	}

	if (error.response) {
		const status = error.response.statusCode;
		// Inspect json() or xml() based on error.response.format.
	}

	// A null response means no usable API response was received.
}

Configure production

Every client defaults to the sandbox. Use your production credentials and select production explicitly when your integration is ready.

JAVASCRIPTClient configuration
const client = new Client(clientId, apiKey,
	{ environment: 'production', timeout: 30000 });

The default timeout is 30 seconds. Set timeout in milliseconds. The client validates TLS certificates and does not follow redirects. All response bodies are buffered in memory.

API reference

The request method accepts every documented endpoint. See endpoints.json in the download for the complete list, and the API reference for required fields and response schemas.

Version 1.0.1. Install from the source downloads provided here; the packages are not published to public registries. Validate your integration with your SmartPayables sandbox account before using production credentials.

Search documentation