SmartPayables Python 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

Python 3.10+. Uses the Python standard library. No runtime dependencies.


INSTALLATION

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

Run:

python -m pip install .

Install the extracted directory into your application environment, then import
Client and ApiError from smartpayables.


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.py. Use the included file so its relative file paths
remain correct, and run the commands from the SDK directory.

import os
import xml.etree.ElementTree as ET
from smartpayables import Client, ApiError

client = Client(
	os.environ['SMARTPAYABLES_CLIENT_ID'],
	os.environ['SMARTPAYABLES_API_KEY'],
)

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

	if response.format == 'json':
		print(response.json())
	else:
		print(ET.tostring(response.xml(), encoding='unicode'))
except ApiError as error:
	# Inspect error.response for API details in your application.
	raise SystemExit(str(error))

Run the example after setting your credentials:

python examples/quickstart.py


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 dict, response.xml() for an ElementTree Element, and
response.body for bytes. ApiError.response contains the response when
available.


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.

uploaded = client.request('payments/upload',
	{'method_id': 2},
	files={'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.

from pathlib import Path

proof = client.request('bank-accounts/check-proofs/get-proof-image',
	{'check_proof_id': 1001},
)
Path('check-proof.jpg').write_bytes(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:

except ApiError as error:
	if error.response is not None:
		status = error.response.statusCode
		# Inspect json() or xml() based on error.response.format.

	# A None 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:

client = Client(clientId, apiKey,
	environment='production', timeout=30)

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


CONNECTION SETTINGS

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