DEVELOPER TOOLS

Ruby SDK

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

Ruby 3.1+Version 1.0.1
Download SDK

Install the SDK

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

Uses Net::HTTP, JSON and REXML. Install dependencies with Bundler.

TERMINALInstallation
bundle install

Require lib/smartpayables.rb directly, or add gem 'smartpayables', path: '/path/to/smartpayables-ruby' to your Gemfile.

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

RUBYSandbox quickstart
require_relative '../lib/smartpayables'

client = SmartPayables::Client.new(
	ENV.fetch('SMARTPAYABLES_CLIENT_ID'),
	ENV.fetch('SMARTPAYABLES_API_KEY')
)

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

	if response.format == 'json'
		puts response.json
	else
		puts response.xml
	end
rescue SmartPayables::ApiError => error
	# Inspect error.response for API details in your application.
	warn error.message
	exit 1
end
TERMINALRun the example
bundle exec ruby examples/quickstart.rb

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 Hash, response.xml for a REXML::Document, and response.body for the raw response string. ApiError#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:

RUBYFile upload
uploaded = 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

Download a check proof

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

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

RUBYException handling
rescue SmartPayables::ApiError => error
	if error.response
		status = error.response.statusCode
		# Inspect json or xml based on error.response.format.
	end

	# A nil response means no usable API response was received.
end

Configure production

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

RUBYClient configuration
client = SmartPayables::Client.new(clientId, apiKey,
	environment: 'production', 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