Take a REST! At PaySimple we look forward to making your life easier, providing a cloud solution to empower businesses to collect payments and manage receivables. PaySimple API allows your solution to use the functionality within PaySimple. The API is designed to be intuitive and easy to integrate. It is based on a REST (Representational State Transfer) architecture inheriting all the simplicity the Web has to offer as a platform for distributed computing.
The PaySimple API utilizes JSON (JavaScript Object Notation) to exchange data. The structure of the “Name: Value” pairs is easily readable for developers and allows for quick parsing within different programming languages. The client submits a standard JSON representation with the HTTP request. The server returns a wrapped JSON response that will include descriptive metadata along with the requested object response.
This guide is designed to provide the methods and routes to get started using the functionality available through the API, such as processing one-time payments, scheduling recurring payments, and creating and managing invoices. The Overview explains some key information regarding API communications, filtering and sorting. The Security section provides detail for authentication. The technical documentation is divided into three sections: the URI Testing Tool, the URI Reference and the Schema Reference.
The URI Testing Tool is a powerful programming tool designed to give you a quick and easy way to interact with the PaySimple API to test available routes and see an API wrapped response in JSON. This tool should help you understand the HTTP communications that will be sent from and received by your application. As long as your application supports HTTP communications, you should be able to use the documented routes in the URI Reference to interface with PaySimple API.
The URI Testing Tool can be found in the left navigation menu. By entering the method and route along with an applicable JSON request, the URI tool provides the JSON payload that you can expect from the PaySimple API. You may also log into the PaySimple Sandbox Website using your Username and Password to see the result of your action in PaySimple’s standard user interface.
The URI Reference section provides an overview of the PaySimple system objects and how they are interrelated. When you select a specific object, you can view the available actions on each object along with the applicable methods and URIs. Sample JSON requests and responses are also included in the detailed section for the URIs.
The New section is unique as it doesn’t refer to one specific object but details routes to obtain copies of empty system objects, for example a new customer or payment. These “New” objects are API request objects, as detailed in the Schema Reference section. This JSON response can be used as a template for creating an object of the requested type.
The Schemas are metadata representations for each system object in easy to read JSON format. Please note there are Request objects and Response objects. A Request object shows only the information that is needed to create an object, and the Response will also include the system‐managed attributes and immutable object fields. Also note that not all attributes in the Request object are required.
A schema shows object attributes, including which are required, optional and system managed. It also details any other applicable data constraints, such as minLength and/or maxLength. Ideally, this information should serve as a reference for the required information to create an object and design a user interface to validate any data constraints.
PaySimple assumes the API developer has knowledge on the following topics:
Please see our Helpful Links in the Support Section.
With the RESTful architecture, API calls take the format of a HTTP request. Available functions are detailed in the Reference section (add link) for system objects.
The HTTP request must include Content Type = application/json and Authentication header information. Any POST or PUT request will require a JSON string representing the object to create or edit.
There are a couple exceptions where a body is not required with PUT requests. This is noted in the Reference section with the specific route.
All HTTP responses will be a wrapped JSON response with the following format:
The “Meta:” section of the Wrapped JSON response will provide the HTTP response code as a numeric and text representation. If the response has information about paging or errors, then the respective object will contain additional information; otherwise, the object will be null.
Common HTTP responses from PaySimple API are:
| Response Code | What it means |
|---|---|
| 200 - OK | Successful Request |
| 201 - Created | New Object was successfully created |
| 203 – Non-Authoritative Information | The response is showing information for a deleted object. |
| 204 – No Content | Successfully processed request with no response body |
| 400 – Bad Request | Error for Invalid Input - ErrorCode and ErrorMessage are provided to detail required information or reason for error. |
| 401 – Unauthorized | Error getting an API token. Check your authentication credentials and resubmit. Note: JSON response will not be returned only the HTTP header. |
| 403 – Forbidden | Permission is denied to perform this action. |
| 404 – Not Found | Error for requested information not found. It may not exist or may have been deleted. |
| 405 – Method Not Allowed | The requested method is not allowed or supported for the specified object. |
| 500 – Internal Server Error | System Error - Attempt to retry or contact API Support |
PaySimple API response will include an “Errors:” section to provide more detailed information regarding the error.
The “ErrorCode:” will give a general reason for the error. The “ErrorMessages:” section is an array of message objects where each object includes “Field:” and “Message:”. The “Field:” may not be populated; however, the “Message:” will provide a string intended for you to display to your client. The "Field:" will be populated only if the InvalidInput error applies to specific field.
PaySimple API is designed to provide a comprehendible description in the “Message:” when an error occurs. Please contact API Support if you encounter an error that may require further explanation or research.
Here’s an example of an error response:
PagingDetails will be included in every wrapped response. If it's not applicable to the response, PagingDetails will be null. If paging information was requested or applies to the data collection, the “PagingDetails:” section contains some specific fields to simplify displaying the data collection.
Some requests, such as retrieving a list of all customers (GET /v4/customer) or all payments (GET /v4/payment), may return a large collection of data. The default number of records returned for any route that responds with a collection is 200 records. To manage the amount of information, PaySimple API allows you to specify the page number and page size in the HTTP request as parameters to return a subset of the collection. Pagination utilizes a 1-based numbering system, so the first page is 1 rather than 0. For example, the following request for customers will provide the first 10 customers in the collection.
GET /v4/customer?page=1&pagesize=10
To get the second page including 11-20 customers, the request would change slightly:
GET /v4/customer?page=2&pagesize=10
The Paging Details appears in the Meta section of the wrapped JSON response (link to wrapped response schema) and looks like:
Some collections can be narrowed by date using startdate and enddate parameters with the HTTP request. To do this, you can add the startDate=”YYYY-MM-DD” and/or endDate=”YYYY-MM-DD” to your query string.
The followign example would give you all of the payments that fall between the two dates. Should you wish to see everything after the startDate, or everything before the endDate, simply remove the opposite parameter.
GET /v4/payments?startDate=”2012-05-01”&endDate=”2012-05-10”
The next example would return all payments after the defined start date.
GET /v4/payments?startDate=”2012-05-01”
The date parameters can be combined with other filtering and sorting features.
PaySimple API provides a Lite filter, a query-string parameter that is ideal for creating lists. Adding the Lite set to true in the parameter string results in an API response of compact objects, providing the most common object attributes used to create a list. Of course, you can set Lite equal to false to receive the object with all attributes. The system currently defaults to Lite=false if not provided in the query string; however, we recommend include this explicitly in your API request to ensure consistent functionality. Here’s how to structure your request to return lite objects:
GET /v4/customer?lite=true
Here’s a sample of the result set:
This feature can be used in conjunction with the following routes:
The Lite parameter can be combined with other filtering and sorting features.
Certain collections of data may be filtered by the object's status. These collections are Payments, PaymentSchedules including Recurring Payments and Payment Plans, and Invoices. Here's an example of how to filter only 'Settled' payments:
GET /v4/payment?status=settled
You can select these objects by the current status and may indicate multiple statuses separated by commas. Here's an example API request:
GET /v4/payment?status=authorized,posted
The Status filter can be used on the following endpoints:
The following status values are applicable filters:
|
| |||||||||||||||||
|
The Status filter can be combined with other filtering and sorting features.
PaySimple provides the ability to sort large collections on the following API method calls for Customers and Payments:
To create a sorted list, the parameters 'sortby' and 'direction' should be included. These parameters may be combined with the paging parameters.
The following values may be used to sort:
|
| |||||||||||||||||||||
| ||||||||||||||||||||||
To get a list of customers sorted by last name in descending order, you would use the following API request.
Example:
GET /v4/customer?sortby=LastName&direction=DESC
Since this will likely return a large collection of data, you may also include the paging details to get a section of the collection.
Example:
GET /v4/customer?sortby=LastName&direction=DESC&pagesize=10&page=1
If no sorting parameters are provided, the Customer collection will automatically sort by Customer Id ascending. The Payment collection will default to descending sort based on Payment Id, so the most recently created payment is on the top of the list. Advanced sorting is not currently available on Invoices; however, Invoices will default to sort in descending order by Invoice ID.
Filtered or limited data sets are not currently available.
PaySimple API uses the ISO 8601 representation of dates. When entering a date into PaySimple, please employ the following format: YYYY-MM-DD
PaySimple creates a date / time stamp where the letter T is a delimiter indicating where the Time begins. Dates returned in an object will be expressed in the following format: 2012-05-01T13:00:00Z
Please note where a date references a future event and time is not a factor, such as Next Payment Date or Start Date on a recurring payment, the timestamp will be set to the default 06:00:00. Please be aware that any date entered without quotes is treated as a null value.
Please feel free to use the following account numbers in your PaySimple Sandbox test account. Once you migrate to a live production account, please only use valid accounts.
Here's a list of credit card accounts to attempt the various types. Please remember to review Payment Type route to confirm your account's approved types. To test declined credit card payments, please enter an incorrect CVV code. When collecting a Payment, the Credit Card SubType will default to 'Moto'.
| Credit Card Type | Account Number | Expiration Date | CVV Code |
|---|---|---|---|
| Visa | 4111111111111111 | 12/2014 | 999 |
| Master | 5454545454545454 | 12/2014 | 998 |
| Discover | 6011000995504101 | 12/2014 | 996 |
| American Express | 371449635398456 | 12/2015 | 9997 |
For ACH Payments, please use the following accounts. When collecting a payment the ACH SubType will default to 'Web'. Please review the Payment Type route to see approved ACH subtypes.
| Routing Number | Account Number | Bank Name | Expected Result |
|---|---|---|---|
| 131111114 | 751111111 | PaySimple Bank | Fail for Known Bad List |
| 307075259 | 751111111 | Simply Bank | Successful |
| 325272034 | 751111111 | Pay Simply Bank | Successful |
