Integrate your payment and document workflows with SmartPayables. Manage bank accounts, submit check and ACH payments, track delivery, and retrieve processing status.
HTTP APIJSON & XMLHTTPS required
Set up your integration
Obtain your API credentials, configure IP access, and test your integration in the sandbox.
Use the sandbox for integration testing. When your integration is ready, send live requests to the production endpoint.
Sandbox
TEST
Build and test your integration.
https://apisb.smartpayables.com/
Production
LIVE
Connect your live payment operations.
https://api.smartpayables.com/
i
Use a separate Client ID and API Key for each environment. Contact support if you need help obtaining access.
Integration basics
Send requests using HTTP POST with URL-encoded form fields. Use multipart form data for file uploads. Request bodies do not require JSON or XML. Responses are available in JSON and XML, with account setup described in Response Format.
You can submit bank accounts, documents, and payments for processing, and look up bank accounts, documents, payments, and general account information.
Secure connections
All API requests require HTTPS. HTTP connections are not supported.
URL encoding
URL encode form values, including API keys that contain special characters. The SDKs handle request encoding automatically. For integrations that use HTTP GET, every query value must also be URL encoded.
Every API request requires a Client ID and API Key. Credentials identify your account and must match the environment you are using.
Find your credentials
Sign in to the client portal with your primary user account.
Open API > API Access > API Credentials in the left menu.
Use the Client ID as client_id and the API Key as akey in each request.
The SDKs add both fields automatically. Store credentials in your server environment or application secret store.
Maintain access
Keep your API Key confidential. Changing the primary user account password also changes the API Key. Update your application credentials after a password change to maintain API access.
Authentication errors
Failed authentication returns an XML error because the account's response format cannot be determined. Your integration must handle XML authentication errors even when JSON is enabled.
XMLResponse example
<wmc-response status="0">
<error>Access Denied, Invalid API Key Provided</error>
</wmc-response>
Documentation/Getting Started
GETTING STARTED
Response Format
The API supports JSON and XML responses. Contact support to enable JSON for your account. Accounts that have not enabled JSON use XML.
Most response dates use Unix timestamps. Request date filters use the format specified by each endpoint. Check the endpoint parameters and examples before converting date values.
Payments can have the following statuses (status ID - status name):
1 - Pending Release
2 - Released
3 - Processing
4 - Sent Out
5 - Posted / Cashed
6 - Returned
7 - Cancelled
8 - Reissued
Documents can have the following statuses (status ID - status name):
1 - Pending Release
2 - Released
3 - Processing
4 - Sent Out
5 - Returned
6 - Rejected
Postage codes can have the following values (code - postage type):
1 - USPS First Class
2 - USPS Priority
3 - USPS Priority + Delivery Confirmation
4 - USPS Priority + Signature Confirmation
5 - FedEx Express 2 Day
6 - FedEx Express Overnight
8 - USPS Overnight
9 - USPS Certified Mail
10 - FedEx Priority Overnight
XML response
XML responses use a wmc-response root element. Its status attribute is 1 for success or 0 for an error. Upload responses may also include a fileid attribute identifying the uploaded file. Review the endpoint examples for its complete response structure.
A successful XML response has the following structure:
XMLResponse example
<wmc-response status="1">
...
</wmc-response>
Documentation/Getting Started
GETTING STARTED
Error Handling
Check the HTTP response and the API response body before treating a request as successful. A successful HTTP exchange can still contain an API validation error.
JSON errors are returned in an errors collection. Depending on the endpoint, this can be a list of messages or an object keyed by field name. XML errors appear as one or more error elements inside wmc-response, with the response status set to 0.
Correct validation errors before submitting the request again. If a connection fails or times out after submission, check the payment or file status before retrying to avoid a duplicate submission. SDK exceptions include the API response when one is available.
JSON response
JSONResponse example
{
"errors": {
"payee": "You must supply a payee"
}
}
XML response
XMLResponse example
<wmc-response status="0">
<error>You must supply a payee</error>
</wmc-response>
Documentation/Getting Started
GETTING STARTED
Webhooks
Configure webhooks to receive HTTP notifications when payment or bank account events occur.
The following events are supported:
Payment Status Change - Triggered whenever a payment status changes (e.g. Released -> Sent Out)
Payment Tracking Added - Triggered whenever a tracking number is added to a payment with supported postage types
Bank Account Status Change - Triggered for bank account status updates (currently micro-deposit returns)
Webhooks are sent as HTTP GET requests to a URL you configure, with dynamic values injected using placeholders (e.g. %ID%, %STATUS_NAME%, %TRACKING_NUMBER%).
Configure webhook URLs and review the available placeholders under API -> Webhooks -> Webhook Settings. This section is available in the client portal menu.
Each webhook type can be enabled or disabled independently, and has its own URL configuration.
All webhook activity is logged and can be viewed in:
API -> Webhooks -> Payment Webhook History
API -> Webhooks -> Payment Tracking Added Webhook History
API -> Webhooks -> Bank Account Webhook History
Webhooks are processed asynchronously via a queue and include retry handling in case of temporary failures.
Documentation/Getting Started
GETTING STARTED
IP Access Control
IP access control restricts API requests to the public IP addresses approved for your account.
Configure allowed addresses
Open API > API Access > IP Access Control Settings in the client portal.
Select Enable IP Access Control, then save with Update IP Access Control Settings.
Use the address list shown after saving to manage the public IP addresses allowed to access the API.
Include the public outbound IP addresses of the servers that send your API requests. Review this list when your hosting or network configuration changes.
Existing address history
While IP access control is disabled, SmartPayables records the IP addresses that access your account and uses them to prepopulate the address list.
Documentation/Bank Accounts
BANK ACCOUNTS
Activate
Activate a bank account using its bank account ID.
Add a bank account for check or ACH payments. Review the returned account details, then use Confirm to complete the submission.
By adding a bank account through this method, you are agreeing to the following terms: I approve this information, including the signature is correct, and take responsibility for any inaccurate information provided. I also acknowledge that fees may apply if the sub-account requires special printing.
Class: bank accounts
Method: add
POST/bank-accounts/add
Parameters
client_id*
akey*
name_on_checks - The name to be printed on checks (populating this field will enable Checks for this bank account)
address_on_checks - Address printed on checks. Separate lines with the | character
address* - The bank account holder's first address line
address2 - The bank account holder's second address line, if applicable
city* - The bank account holder's city
state* - The bank account holder's state
zip* - The bank account holder's zip code
account_number* - Bank account number
routing_number* - Bank routing number
bank_name* - Bank name
bank_address - Bank address. Separate address lines with the | character
bank_fractional_code - Bank fractional code (required for checks only)
currency - Currency code. Defaults to USD; use CAD for Canadian bank accounts (checks only)
sig2_threshold - This is used to set a threshold, where if a payment reaches this threshold, a second signature is used only then, otherwise if set a second signature is used all of the time
only_use_sig2_threshold - This is set to 1 or 0, indicating enabled or disabled, and enforces the threshold above
account_alias* - Account alias displayed in the system
email_address - Email address for individual alerts and verification links
alert_email_address - Set to 1 to send individual verification emails directly to users, or 0 to disable them
return_address - Custom return address. Separate lines with the | character
starting_check_number - Starting check number
sig_file - Signature image sent as a multipart upload. Use an image containing only the signature on a white background (only required for Checks)
sig_file2 - Optional second signature image. Without the threshold settings above, this signature is printed on every check
name_on_account - Name on bank account. This field will be automatically set to name on checks if not provided.
ach_company_id - ACH Company/Tax ID (populating this field will enable ACH for this bank account)
ach_originating_dfi - Originating DFI number (required only if enabling ACH)
ach_receiving_dfi - Receiving DFI Number (required only if enabling ACH)
purchase_order - Purchase order reference included on invoices when provided
notify_sent_email_address - Email address for payment sent notifications specific to this bank account
notify_on_payments_sent - Set to 1 to use the account-specific payment notification email, or 2 to disable it
logo_file - Logo printed at the top right of the check stub for this account. Send a clear image with a white background as a multipart upload. Accepted formats: Bitmap, JPG and PNG
Confirm a bank account added individually or confirm the accounts in an uploaded file. Specify the confirmation type and the ID returned by the original request.
Class: bank accounts
Method: confirm
POST/bank-accounts/confirm
Parameters
client_id*
akey*
item* - One or multiple unique item identifiers (for multiples, use standard form posting rules for data arrays and pass each item as item[]. Item must include bank account confirmation type. To confirm a single bank account with an id of 25, set item to 'single-25.' To confirm a bank account file with an ID of 25, set item to 'file-25.'
Note: The response varies by bank account confirmation type and by how the bank account information is confirmed. The response status is 1 if the transaction was successful.
This example confirms three bank accounts. Each item value was obtained from the bankaccount_id node returned by the respective bank-accounts/add method call:
Retrieve your bank accounts. Use action_required to limit the results to accounts that need attention, such as a missing signature or a returned account.
Class: bank accounts
Method: get-list
POST/bank-accounts/get-list
Parameters
client_id*
akey*
action_required - Set this to 1 or 0, indicating true or false
Documents uploaded and confirmed by 9:00 AM Mountain Time are eligible for same-day printing and mailing.
Documents confirmed after 9:00 AM Mountain Time are sent the next business day. Printing operates Monday through Friday, excluding holidays.
Before your first PDF upload: Send a sample to support@smartpayables.com for compatibility testing. Review the document requirements before preparing your files.
Submit a document, a bundle of copies, or a mailing list. Review the returned details, then call Confirm to release the submission for processing.
Class: documents
Method: add
POST/documents/add
Single documents
Parameters
client_id*
akey*
document_file* - File sent as a multipart upload
document_type* - set this to a value of "single"
print_type* - Print format; Use one of the following values:
black_white - print using Black & White
black_white_duplex - print using Black & White Duplex
color - print using Color
color_duplex - print using Color Duplex
document_address_type* - Use one of the following values:
address_provided_separately - Select this value to include a cover page and supply the address in the fields below
address_included_in_file - The document already contains the mailing address
mail_to - Recipient name
address - Mailing address
address2 - Second address line, if required
city - Mailing city
state - Mailing state
zip - Mailing ZIP or postal code
country - Mailing country
trans_id - an optional custom client transaction ID stored for record keeping
document_return_address_option* - Use one of the following values:
smartpayables - Select this value to use our address in the event of a return
custom - Provide a return address in the field below, separating lines with the | character
document_return_address* - custom return address to be used with new lines indicated by the | character (eg. company name|address|city, state, zip|country)
envelope_type_id - this field is used to specify an envelope type ID, which will be issued to you by our setup and support team if you have custom envelope types setup with us. You can also retrieve a list of usable IDs for your account from the Documents -> Get Envelope Types method
postage_code (one of the following numeric values)
1 - USPS First Class (Default if not specified)
2 - USPS Priority
3 - USPS Priority + Delivery Confirmation
4 - USPS Priority + Signature Confirmation
5 - FedEx Express 2 Day
6 - FedEx Express Overnight
8 - USPS Overnight
9 - USPS Certified Mail
10 - FedEx Priority Overnight
sub_account_id - Existing sub account ID to associate with the document
include_no9_envelope - Select whether to include a No. 9 return envelope, with or without postage:
include - this value indicates to include the envelope without postage
include_postage - this value indicates to include the envelope with postage
mailing_list_file* - File sent as a multipart upload, in CSV format, with the following columns/headers:
Mail To Recipient,Address,Address 2,City,State,Zip,Country,Client Transaction ID,Sub Account ID,Postage Code,Custom FedEx Account Number,Custom FedEx Alert Email
Set the Postage Code column to one of the numeric values below. For FedEx shipments billed to your own account, also provide the Custom FedEx Account Number and, optionally, Custom FedEx Alert Email
1 - USPS First Class (Default if not specified)
2 - USPS Priority
3 - USPS Priority + Delivery Confirmation
4 - USPS Priority + Signature Confirmation
5 - FedEx Express 2 Day
6 - FedEx Express Overnight
8 - USPS Overnight
9 - USPS Certified Mail
10 - FedEx Priority Overnight
document_type* - set this to a value of "mailing_list"
print_type* - Print format; Use one of the following values:
black_white - print using Black & White
black_white_duplex - print using Black & White Duplex
color - print using Color
color_duplex - print using Color Duplex
trans_id - an optional custom client transaction ID stored for record keeping
document_return_address_option* - Use one of the following values:
smartpayables - Select this value to use our address in the event of a return
custom - Provide a return address in the field below, separating lines with the | character
document_return_address* - custom return address to be used with new lines indicated by the | character (eg. company name|address|city, state, zip|country)
envelope_type_id - this field is used to specify an envelope type ID, which will be issued to you by our setup and support team if you have custom envelope types setup with us. You can also retrieve a list of usable IDs for your account from the Documents -> Get Envelope Types method
sub_account_id - Existing sub account ID to associate with the documents
Confirm one or more documents, mailing files, or document bundles using the IDs returned when they were submitted.
Class: documents
Method: confirm
POST/documents/confirm
Parameters
client_id*
akey*
item* - this must be set to single-DOCUMENT_ID_HERE where DOCUMENT_ID_HERE is the document ID returned upon add, or file-FILE_ID_HERE where FILE_ID_HERE is the file ID returned upon file upload, or bundle-BUNDLE_ID_HERE where BUNDLE_ID_HERE is the bundle ID returned upon add
Retrieve the custom envelope types available to your account. Pass the selected ID as envelope_type_id when adding a document. Contact support to configure a custom envelope type.
Reject a check proof. Include a rejection reason to describe the changes required.
Class: bank-accounts
Method: check-proofs/reject
POST/bank-accounts/check-proofs/reject
Parameters
client_id*
akey*
check_proof_id* - the ID of the check proof to reject
rejection_reason - the reason for the rejection
JSON response
JSONResponse example
{
"check_proof": {
"id": "710",
"bank_account_id": "22984",
"bank_account_alias": "Operating Account",
"checkproof_added_ts": "1563318671",
"checkproof_reviewed": true,
"checkproof_approved": false,
"checkproof_rejected": true,
"checkproof_rejection_reason": "Please align the company logo with the approved check layout."
}
}
XML response
XMLResponse example
<wmc-response status="1">
<checkproofs>
<checkproof id='1'>
<checkproof_id>1</checkproof_id>
<bank_account_id>1</bank_account_id>
<bank_account_alias>Operating Account</bank_account_alias>
<checkproof_added_ts>1542206453</checkproof_added_ts>
<checkproof_reviewed>1</checkproof_reviewed>
<checkproof_approved>0</checkproof_approved>
<checkproof_rejected>1</checkproof_rejected>
<checkproof_rejection_reason>Please align the company logo with the approved check layout.</checkproof_rejection_reason>
</checkproof>
</checkproofs>
</wmc-response>
Documentation/Payments
PAYMENTS
Add
Checks uploaded and confirmed by 9:00 AM Mountain Time are eligible for same-day printing and mailing.
Checks confirmed after 9:00 AM Mountain Time are sent the next business day. Printing operates Monday through Friday, excluding holidays.
Create a check or ACH payment. Review the returned payment details, then call Confirm with the payment ID to release it for processing.
Class: payments
Method: add
POST/payments/add
Check payments (method_id = 2)
International USPS Priority and Express services do not have the same delivery times or price rates as domestic mail. Pricing will vary per service. Delivery times for these services going international are listed below:
USPS Priority International = 6-10 days
USPS Express International = 3-5 days
Parameters
client_id*
akey*
method_id* - numeric id representing a method of payment
payee* - name of payee, 48 characters max length
amount* - amount of payment (xxx.xx). This is entered with no currency symbols; just numbers and decimals
address* - payee street address, 120 characters max length if no address2 is provided, if address2 is provided, there is a 60 character limit on this and address2 fields
address2
city* - payee city
country* - payee country
logo_file - name of client's logo file stored on the system
memo - information placed on the stub of the check or the memo line of the check depending upon client setup
notes - internal notes to pass to the system along with the payment
payee_email - payee email (optional)
payment_type - indicates the type of payment, e.g. Bill Payment, Commission, etc
postage_code (one of the following numeric values)
1 - USPS First Class
2 - USPS Priority
3 - USPS Priority + Delivery Confirmation
4 - USPS Priority + Signature Confirmation
5 - FedEx Express 2 Day
6 - FedEx Express Overnight
8 - USPS Overnight
9 - USPS Certified Mail
10 - FedEx Priority Overnight
reference* - reference
state* - payee state
taxid - SSN or tax identification number
trans_id* - Your transaction ID for identifying the payment in reports
zip* - Payee ZIP or postal code. Use five digits or ZIP+4 format for US addresses
check_num - Optional check number, up to 10 digits and non-negative. Leave blank or omit the field to generate a check number automatically
bank_account_id - Bank account ID or alias to fund the check. If omitted, the default bank account is used
mail_to_payee - if you populate this field it will replace the payee name in the address for mailing
expedite_request - Set to 1 to request processing after the 9:00 AM cutoff and before 11:00 AM. Expedited processing is not guaranteed
date_to_send - Requested send date in MM/DD/YYYY format. Requires future-dated payments to be enabled on your account. Dates that fall on a non-working day move to the next working day. Contact support to enable this feature
Parameters
To include a PDF insert with a check, provide the following parameters:
insert_include* - Set to 1 to include a PDF insert
insert_file* - PDF file sent as a multipart upload using the field name 'insert_file'
insert_print* - Select the insert print format using one of the following values
black_white - Print using Black & White
black_white_duplex - Print using Black & White Duplex
Confirm a payment or an uploaded payment file. Review the submitted details before confirming. Additional options are available for bundling checks from an uploaded file.
Class: payments
Method: confirm
POST/payments/confirm
Parameters
client_id*
akey*
item* - Use 'single-PAYMENT ID' for a payment created with payments/add, or 'file-FILE ID' for a file uploaded with payments/upload. Replace the ID with the value returned by that request.
Bundle an uploaded file
To send an uploaded check file as one package, include the following parameters in the confirmation request. These fields apply to checks only and are unnecessary when the uploaded file already supplies the bundling fields
bundle_opt_in* - Set to 1 to bundle the checks
bundle_mail_to* - recipient field used in postage
bundle_address* - address line 1 field used in postage
bundle_address_2* - address line 2 field used in postage
bundle_city* - city field used in postage
bundle_state* - state field used in postage
bundle_zip* - zip field used in postage
bundle_country* - country field used in postage
bundle_check_contents* - Use one of the following values
envelope - Select this value to have every check in this bundle enveloped
loose - Select this value to have every check in this bundle loose
bundle_postal_type - Use one of the following values when required
usps_priority - send via USPS Priority, this is the default postage type if no postage type is provided
usps_priority_sig - send via USPS Priority (signature required) - this is not available for International mailing
usps_overnight - send via USPS Overnight (express)
fedex_2day - send via FedEx Express 2 Day
fedex_overnight - send via FedEx Express Overnight
fedex_priority_overnight - send via FedEx Priority Overnight
bundle_custom_account_number - Your FedEx account number, when using your own shipping account
bundle_custom_alert_email - if opting to use your own FedEx account number, you may also send an alert email address in this field
bundle_custom_alert_email2 - if opting to use your own FedEx account number, you may also send a second alert email address in this field
bundle_custom_alert_email3 - if opting to use your own FedEx account number, you may also send a third alert email address in this field
bundle_custom_recipient_phone - Optional custom recipient phone number (printed on the shipping label)
bundle_custom_customer_reference - Optional custom customer reference (printed on the shipping label)
bundle_custom_sender_contact - Optional custom sender contact (printed on the shipping label)
bundle_custom_sender_company - Optional custom sender company (printed on the shipping label)
bundle_custom_sender_address - Optional custom sender address (printed on the shipping label)
bundle_custom_sender_city - Optional custom sender city (printed on the shipping label)
bundle_custom_sender_state - Optional custom sender state (printed on the shipping label)
bundle_custom_sender_zip - Optional custom sender zip (printed on the shipping label)
bundle_custom_sender_phone - Optional custom sender phone number (printed on the shipping label)
Retrieve estimated USPS First Class delivery date ranges for the current date and the following 45 days. Estimates account for the submission date, printing dates, office closures, and USPS mailing days.
Class: payments
Method: get-estimated-delivery-date-set
POST/payments/get-estimated-delivery-date-set
Parameters
client_id*
akey*
address - payee street address
address2
city - payee city
state* - payee state (full name or 2-letter state code)
Retrieve a paginated list of payments, including status and tracking information. Combine the available filters to locate payments by date, recipient, bank account, reference, or other criteria.
Class: payments
Method: get-payment-list
POST/payments/get-payment-list
Parameters
client_id*
akey*
page - Page number to retrieve. Defaults to 1
per_page - Number of results per page, up to a maximum of 50
address - Address to filter by (likeness search)
amount - Amount to filter by, numeric/decimal only
bank_account_id - Bank Account ID to filter by, numeric only
check_num - Check Number to filter by, numeric only
trans_id - Client Transaction ID to filter by (likeness search)
date_submitted - used to filter by an exact Date Submitted (singular, mm/dd/yyyy format)
date_submitted_from - used in combination with the to field for a Date Submitted range filter (mm/dd/yyyy format)
date_submitted_to - used in combination with the from field for a Date Submitted range filter (mm/dd/yyyy format)
date_sent - used to filter by an exact Date Sent (singular, mm/dd/yyyy format)
date_sent_from - used in combination with the to field for a Date Sent range filter (mm/dd/yyyy format)
date_sent_to - used in combination with the from field for a Date Sent range filter (mm/dd/yyyy format)
date_updated - used to filter by an exact Date Updated (singular, mm/dd/yyyy format)
date_updated_from - used in combination with the to field for a Date Updated range filter (mm/dd/yyyy format)
date_updated_to - used in combination with the from field for a Date Updated range filter (mm/dd/yyyy format)
method_id - Method ID to filter by, numeric only
1 - ACH
2 - Check
notes - Notes to filter by (likeness search)
payee - Payee to filter by (likeness search)
payment_id / id - Payment ID to filter by, numeric only
postage_code - Postage Code to filter by, numeric only
1 - USPS First Class
2 - USPS Priority
3 - USPS Priority + Delivery Confirmation
5 - FedEx Express 2 Day
6 - FedEx Express Overnight
8 - USPS Overnight
9 - USPS Certified Mail
10 - FedEx Priority Overnight
reference - Reference to filter by (likeness search)
status_id - Status ID to filter by, numeric only
1 - Pending Release
2 - Released
3 - Processing
4 - Sent Out
5 - Posted / Cashed
6 - Returned
7 - Cancelled
8 - Reissued
Combine filters to narrow the results. Use the pagination information returned in the response to retrieve additional pages.
payment_id* - either one or multiple unique identifiers (for multiples, use standard form posting rules for data arrays and pass each payment_id as payment_id[])
Checks uploaded and confirmed by 9:00 AM Mountain Time are eligible for same-day printing and mailing.
Checks confirmed after 9:00 AM Mountain Time are sent the next business day. Printing operates Monday through Friday, excluding holidays.
Upload a check or ACH payment file using your configured file mapping. Review the returned records and file ID, then call Confirm to release the payments for processing.
expedite_request - Set to 1 to request processing after the 9:00 AM cutoff and before 11:00 AM. Expedited processing is not guaranteed
International USPS Priority and Express services do not have the same delivery times or price rates as domestic mail. Pricing will vary per service. Delivery times for these services going international are listed below:
USPS Priority International = 6-10 days
USPS Express International = 3-5 days
The response depends on the payment type. These examples contain two checks. Use the returned file_id value in JSON or the fileid attribute on the XML wmc-response element to identify the file when confirming it.
Check Inserts
Choose a single PDF insert for all checks, or multiple inserts matched by filename. For multiple inserts, support must configure a payment file column to map each check to its PDF filename. Use the following parameters:
insert_include* - Set to "single" to include the same PDF with all checks, or "multiple" to match uploaded PDFs using the configured filename column
insert_file_single - PDF insert for all checks, sent as a multipart upload
insert_file_multiple - PDF inserts matched to the configured filename column. Send multipart files using indexed field names such as insert_file_multiple[0] and insert_file_multiple[1]
insert_print* - Select the insert print format using one of the following values
black_white - Print using Black & White
black_white_duplex - Print using Black & White Duplex
color - Print using Color
color_duplex - Print using Color Duplex
A payment file can contain up to 5,000 payments. Files above this limit are rejected. Divide larger batches into separate files and upload each file individually.
Upload a logo for use on outgoing checks. Use the logo_file value returned by this endpoint when assigning the logo to a payment. Contact support to configure logo mapping for batch files.
Class: payments
Method: upload-logo
POST/payments/upload-logo
Parameters
client_id*
akey*
logofile* - File sent as a multipart upload
name* - display name for your logo in the client panel, not used in the assignment to payments
is_default - this indicates whether or not this logo should be automatically assigned to any check where no logo is supplied, by default we leave this as 0 (where 1 indicates 'true' and 0 indicates 'false')
Validate and standardize an address. A successful response includes the corrected address and a description of any changes. An error response explains why the address could not be validated.
Class: payments
Method: validate-address
POST/payments/validate-address
Parameters
client_id*
akey*
name - Optional business name. This may help identify suite information during validation.
address - Street address to validate.
address2 - Additional delivery information, such as "Attention: Accounts Payable".
city - City. Required when no ZIP code is provided.
state - State name or abbreviation. Required when no ZIP code is provided.
zip - ZIP code. Required unless both city and state are provided.
Validation Errors: If the supplied address cannot be validated, the response will contain an errors array describing the reason validation failed. The possible validation errors are listed below.
Error
Description
Address not found
The supplied address could not be found and does not match a known USPS special-case scenario.
Multiple addresses match
Multiple address candidates were found that are equally likely to match the supplied address.
Example: "1 Main St" may match both "1 E Main St" and "1 W Main St".
Please enter a valid address number.
The supplied address does not contain a valid primary street number.
Example: "Main St, Santa Barbara CA 93101".
Street not found
The supplied street name could not be found within the specified city, state, or ZIP code.
Street number or box number out of range
The street was found, but the supplied primary street or box number is not valid for that street.
Internal processing error, please contact SmartPayables as soon as possible
An unexpected error occurred while processing the address, or the address matched a special-case scenario that could not be validated.
City not found
The supplied city could not be found for the specified state or ZIP code.
State not found
The supplied state or state abbreviation could not be identified.
DPV lockout, please contact SmartPayables as soon as possible
The address triggered a USPS DPV lockout condition and cannot currently be validated.
Address not found but the region has General Delivery service
The supplied address could not be found, but the specified region supports USPS General Delivery service. Mail addressed to "General Delivery" with the recipient's name may still be deliverable.
Unable to parse address.
The supplied address could not be parsed into the individual address components required for validation.
Client libraries for C#, Java, PHP, Node.js, Ruby and Python. Each SDK handles authentication, form encoding, file uploads and response parsing for the SmartPayables API.
Automatic authenticationJSON and XMLMultipart uploadsSandbox by default
Integration workflow
01
Install your SDK
Download the source package and follow the setup guide for your language.
02
Connect to the sandbox
Configure your API credentials and run the included payment list example.
03
Validate your workflow
Check returned records, handle errors and test confirmation before using production.
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.
Integrate payments, bank accounts, check proofs, documents and tax files into your C# / .NET application. This guide covers installation, sandbox requests, file uploads, response handling and production configuration.
Download and extract the package, then run these commands from the extracted smartpayables-csharp directory.
Uses the .NET HTTP, JSON and XML libraries. No third-party runtime packages.
TERMINALInstallation
dotnet build SmartPayables/SmartPayables.csproj
Add a project reference to SmartPayables/SmartPayables.csproj from your application.
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 Example/Program.cs in the download.
C#Sandbox quickstart
using SmartPayables;
using var client = new Client(
Environment.GetEnvironmentVariable("SMARTPAYABLES_CLIENT_ID") ?? "",
Environment.GetEnvironmentVariable("SMARTPAYABLES_API_KEY") ?? ""
);
try {
var response = await client.requestAsync("payments/get-payment-list",
new Dictionary<string, object?> { ["page"] = 1, ["per_page"] = 10 });
if (response.format == "json") {
Console.WriteLine(response.json().ToString());
} else {
Console.WriteLine(response.xml().ToString());
}
} catch (ApiException error) {
// Inspect error.response for API details in your application.
Console.Error.WriteLine(error.Message);
Environment.ExitCode = 1;
}
TERMINALRun the example
dotnet run --project Example
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 JsonElement, response.xml() for an XDocument, and response.body for raw bytes. ApiException.response contains the response when available. requestAsync also accepts a CancellationToken.
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:
C#File upload
var uploaded = await client.requestAsync("payments/upload",
new Dictionary<string, object?> { ["method_id"] = 2 },
new Dictionary<string, string> { ["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.
C#Binary response
var proof = await client.requestAsync("bank-accounts/check-proofs/get-proof-image",
new Dictionary<string, object?> { ["check_proof_id"] = 1001 });
await File.WriteAllBytesAsync("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:
C#Exception handling
catch (ApiException error) {
if (error.response is { } failed) {
var status = failed.statusCode;
// Inspect failed.json() or failed.xml() based on failed.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.
C#Client configuration
using var client = new Client(clientId, apiKey,
environment: "production", timeout: TimeSpan.FromSeconds(30));
The default timeout is 30 seconds. Set timeout as a TimeSpan. 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.
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.
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);
}
}
}
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:
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.
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.
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.
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:
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.
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.
Integrate payments, bank accounts, check proofs, documents and tax files into your Node.js application. This guide covers installation, sandbox requests, file uploads, response handling and production configuration.
Download and extract the package, then run these commands from the extracted smartpayables-nodejs directory.
Uses native fetch and fast-xml-parser. Designed for server-side JavaScript with ES modules.
TERMINALInstallation
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.
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.mjs in the download.
JAVASCRIPTSandbox quickstart
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;
}
TERMINALRun the example
node examples/quickstart.mjs
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 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.
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:
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.
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:
JAVASCRIPTException handling
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.
}
Configure production
Every client defaults to the sandbox. Use your production credentials and select production explicitly when your integration is ready.
The default timeout is 30 seconds. Set timeout in milliseconds. 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.
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.
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:
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.
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.
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.
Integrate payments, bank accounts, check proofs, documents and tax files into your Python application. This guide covers installation, sandbox requests, file uploads, response handling and production configuration.
Download and extract the package, then run these commands from the extracted smartpayables-python directory.
Uses the Python standard library. No runtime dependencies.
TERMINALInstallation
python -m pip install .
Install the extracted directory into your application environment, then import Client and ApiError from smartpayables.
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.py in the download.
PYTHONSandbox quickstart
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))
TERMINALRun the example
python examples/quickstart.py
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 dict, response.xml() for an ElementTree Element, and response.body for bytes. 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:
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.
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:
PYTHONException handling
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.
Configure production
Every client defaults to the sandbox. Use your production credentials and select production explicitly when your integration is ready.
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.