DEVELOPER TOOLS

PHP SDK

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

PHP 5.6+Version 1.0.1
Download SDK

Install the SDK

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

Requires cURL, JSON and SimpleXML. Direct inclusion works without Composer.

TERMINALInstallation
php -m
php -l src/SmartPayables.php

Require src/SmartPayables.php in your application, as shown below. A composer.json file is also included for applications using Composer path repositories. Configure curl.cainfo if your PHP installation needs a CA certificate bundle.

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

PHPSandbox quickstart
<?php
require __DIR__ . '/../src/SmartPayables.php';

$client = new \SmartPayables\Client(
	getenv('SMARTPAYABLES_CLIENT_ID'),
	getenv('SMARTPAYABLES_API_KEY')
);

try {
	$response = $client->request('payments/get-payment-list', array(
		'page' => 1,
		'per_page' => 10
	));

	if ($response->format === 'json') {
		print_r($response->json());
	} else {
		echo $response->xml()->asXML();
	}
} catch (\SmartPayables\ApiException $error) {
	// Inspect $error->response for API details in your application.
	fwrite(STDERR, $error->getMessage() . PHP_EOL);
	exit(1);
}
TERMINALRun the example
php examples/quickstart.php

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 an associative array, $response->xml() for a SimpleXMLElement, and $response->body for the raw response string. 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:

PHPFile upload
$uploaded = $client->request('payments/upload',
	array('method_id' => 2),
	array('userfile' => __DIR__ . '/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

Download a check proof

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

PHPBinary response
$proof = $client->request('bank-accounts/check-proofs/get-proof-image',
	array('check_proof_id' => 1001)
);
file_put_contents(__DIR__ . '/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:

PHPException handling
catch (\SmartPayables\ApiException $error) {
	if ($error->response !== null) {
		$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.

PHPClient configuration
$client = new \SmartPayables\Client($clientId, $apiKey,
	'production', array('timeout' => 30));

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