DEVELOPER TOOLS

Java SDK

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

Java 11+Version 1.0.1
Download SDK

Install the SDK

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

Uses Java HttpClient and Gson for JSON. Build with Maven and a JDK.

TERMINALInstallation
mvn package dependency:copy-dependencies

Run mvn install to install com.smartpayables:smartpayables-sdk:1.0.1 into your local Maven repository, then add it as a dependency. On Windows, use semicolons instead of colons between classpath entries in the example commands.

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.java in the download.

JAVASandbox quickstart
import com.smartpayables.Client;
import java.util.Map;

public class Quickstart {
	public static void main(String[] args) {
		Client client = new Client(
			System.getenv("SMARTPAYABLES_CLIENT_ID"),
			System.getenv("SMARTPAYABLES_API_KEY")
		);

		try {
			Client.Response response = client.request(
				"payments/get-payment-list", Map.of("page", 1, "per_page", 10)
			);

			if (response.format.equals("json")) {
				System.out.println(response.json());
			} else {
				System.out.println(response.text());
			}
		} catch (Client.ApiException error) {
			// Inspect error.response for API details in your application.
			System.err.println(error.getMessage());
			System.exit(1);
		}
	}
}
TERMINALRun the example
javac -cp "target/classes:target/dependency/*" examples/Quickstart.java
java -cp "target/classes:target/dependency/*:examples" Quickstart

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 Gson JsonElement, response.xml() for a DOM Document, and response.body for raw bytes. Client.ApiException.response contains the response when available.

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:

JAVAFile upload
Client.Response uploaded = client.request("payments/upload",
	Map.of("method_id", 2),
	Map.of("userfile", java.nio.file.Path.of("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.

JAVABinary response
Client.Response proof = client.request(
	"bank-accounts/check-proofs/get-proof-image",
	Map.of("check_proof_id", 1001));
java.nio.file.Files.write(java.nio.file.Path.of("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:

JAVAException handling
catch (Client.ApiException error) {
	if (error.response != null) {
		int 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.

JAVAClient configuration
Client client = new Client(clientId, apiKey, "production",
	java.time.Duration.ofSeconds(30), null);

The default timeout is 30 seconds. Set timeout as a Duration. 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