SmartPayables Node.js SDK
Version 1.0.1

This package contains the API client, a sandbox example and a list of
supported endpoints. Test your integration in the sandbox before using
production credentials.


REQUIREMENTS

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


INSTALLATION

Extract the ZIP and open a terminal in the smartpayables-nodejs directory.
Install from this package; the SDK is not published to public package
registries.

Run:

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.


SANDBOX SETUP

Set these environment variables for the process running your application:

SMARTPAYABLES_CLIENT_ID
    Your sandbox Client ID.

SMARTPAYABLES_API_KEY
    Your sandbox API Key.

Use credentials for the sandbox account, and make sure the public IP address
of your application server is allowed on that account. The client sends
client_id and akey with each request.

The example below retrieves the first 10 payments. It is included in
examples/quickstart.mjs. Use the included file so its relative file paths
remain correct, and run the commands from the SDK directory.

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

Run the example after setting your credentials:

node examples/quickstart.mjs


RESPONSE FORMATS

Response format is configured on your SmartPayables account. Contact support
to enable JSON. XML is also supported. Authentication errors can return XML
even when JSON is enabled, so check the response format before reading the
body.

The SDK detects the format of each response. Sending 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.


PARAMETERS AND FILE UPLOADS

Pass the endpoint path without a leading slash, followed by the API
parameters. All requests use POST. Refer to the API documentation for required
fields.

Send amounts as decimal strings, such as "1250.00". Null values are omitted,
and boolean values are sent as 1 or 0. Use indexed keys such as item[0],
item[1] or insert_file_multiple[0] for repeated values or files.

This example uploads a payment CSV using your account's configured mapping.
Replace payments.csv with the path to your file. The client builds the
multipart request.

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. The SDK does not
confirm payments or retry requests automatically. If a request times out,
check its status before submitting it again.


CHECK PROOF DOWNLOADS

Check proof images are returned as JPEG data. Replace 1001 with a check proof
ID from your sandbox account.

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


ERROR HANDLING

The SDK raises an exception for HTTP errors, API errors, invalid JSON or XML,
and connection failures. An HTTP 200 response can still contain an API error.

Check the response attached to the exception for the HTTP status, format and
API error details. If no usable response was received, the response property
is empty. Do not write credentials or payment details to application logs.

Extend the exception handling in the sandbox example to inspect the response:

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


PRODUCTION CONFIGURATION

The client uses the sandbox by default. After testing, use production
credentials and select the production environment:

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

Sandbox:    https://apisb.smartpayables.com/
Production: https://api.smartpayables.com/


CONNECTION SETTINGS

The default timeout is 30 seconds. Set timeout using milliseconds. TLS
certificates are validated, and redirects are not followed.

The optional base URL override accepts HTTPS URLs. HTTP is allowed only for
loopback addresses used in local tests.

Response bodies are held in memory. Multipart uploads are also held in memory;
allow enough application memory for the combined file sizes.


API REFERENCE AND SUPPORT

See endpoints.json for the supported endpoint paths and the SmartPayables API
documentation for parameters and response details.

Support: support@smartpayables.com
