This section introduces you to the concepts used within the Pushpay API. For further assistance, please contact us and we'll be glad to help.
The Pushpay API is a Representational State Transfer (REST) API. It is designed to have resource-oriented URLs organised around concepts familiar to those using the Pushpay platform. This means that Pushpay uses HTTP methods (verbs) to indicate the kind of request being made (for example, GET for reading, POST for creating, PUT and PATCH for updating, and DELETE for removing/dismissing).
The Pushpay API is designed to be easy to use by people implementing clients - with responses always being in JSON, HTTP status codes used to indicate the outcome of requests, error messages returned in a consistent way, and links returned as part of entities that identify related resources.
Where possible, Pushpay provides client libraries for common languages/platforms (currently the .NET framework, with plans to support other languages shortly). Pushpay also provides rich metadata about all the supported API operations in the form of SwaggerTM, a machine-readable format that can be used for generating your own clients or exploring the surface area of the API programatically.
The Pushpay API is secured via OAuth2. This is an industry-standard mechanism for securing APIs that allows for fine-grained features to be granted to API consumer, either for itself or on behalf of a Pushpay user.
The Pushpay Platform has rich support for exposing metdata about its own API for consumption via the API. This includes available operations, models, documentation and examples.
This information is exposed via JSON using the swagger 1.2 specification. The SwaggerTM resources can be accessed via https://api.pushpay.com/swagger and do not require clients to be authenticated (publicly accessible).
SwaggerTM can be used for generating API clients to make accessing the API easier. That is, if Pushpay doesn't have a client available for your platform, it may be worth considering one of the SwaggerTM client options, including:
When something goes wrong with an API request - for example, validation failure or a server error - then the response you will get back will be an "error response", which has a specific format. This, combined with the status code, is the information you need to use to decide how to handle the problem.
API documentation and metadata (such as SwaggerTM) covers requests and expected responses when requests are successful. However, when requests fail things are a bit different.
In cases where an error response is returned, it will return a 40X or 50X status code, and the response will be JSON of the format:
{
"message": "error description", // description of message
"id": "GUID", // unique identifier for error
"resultCode": {
"code": 1234, // integer error code
"key": "Declined" // error code name
"description": "Declined due to expired card" // optional description of result code
},
"validationFailures": {
"name": ["Name is must be between 10 and 20 characters in length"],
"password": ["password must contain upper case letters", "password must be more then 10 characters"]
}
}
All parts of the error response are optional.
Resources in the API do not live in isolation - data is related to other data accessible in other parts of the API. By providing links in the representations returned from the API, Pushpay makes it easy to discover related data and access it without having to hard-code in knowledge of the URL structure of each related resource.
The responses returned from most Pushpay API calls use the content type application/hal+json. This content type
represents JSON that includes standardised representation of links between content. It also provides a mechanism for
embedding one resource's representation within another.
For specific details on hal+json please refer to the IETF draft specification http://tools.ietf.org/html/draft-kelly-json-hal-06.
In summary, however, what you will find is that all representations returned from the API include a _links property,
which is an object where each key represents a link to another resourced related to this entity.
_links takes the form of:
{
"_links":{
"self": {
"href": "https://api.pushpay.com/merchant/widgetsinc"
},
"anticipatedPayments": {
"href": "https://api.pushpay.com/merchant/widgetsinc/anticipatedpayments"
}
}
}
In this case there are 2 links:
A full link can also contain other information:
{
"_links": {
"a_link": {
"href": "....", // absolute URI
"templated": true", // if true then URI is a template
"title": "...." // optional title for this URL
}
}
}
HAL+JSON also supports returning an array of links for a relationship, for example:
{
"_links": {
"a_link": [{
"name": "link #1",
"href": "..."
}, {
"name": "link #2",
"href": "..."
}]
}
}
However, this is not currently a feature used by the Pushpay platform, so when developing clients for the API you do not need to support this feature.
For performance reasons, Pushpay will not return all the data matching queries in a single response. Instead, you must access the data a page at a time, and the Pushpay API tries to make paging through data as easy as possible.
For API operations that return a collection of items they will be in the form of:
{
"items": [
{
"name": "item 1"
},
{
"name": "item 2"
}
],
"page": 0,
"pageSize": 25,
"total": 2,
"totalPages": 1,
"_links": {
...
}
}
Page size is restricted to a default value of 25 items per page. Paging is controlled via the query string using
the page parameter, and is 0-relative (so page=0 is the first page, page=1 is the second page etc.).
The response returns both the total individual items (in the total property) and the total number of pages
(in the totalPages property).
The _links property is an object containing a set of links, where the key is the "rel" (relation) of the link.
For operations returning collections, this link collection will be populated with a set of links allowing you to navigate the result set without having to build URIs by hand using the template. Where possible, Pushpay recommends that API developers favour this approach, as it will build more robust clients.
The links are:
Here is an example of viewing a page in the middle of a result set with links to other pages:
{
"items": [
....
],
"page": 2,
"pageSize": 25,
"total": 120,
"totalPages": 5,
"_links": {
"self": {
"href": "https://api.pushpay.com/v1/merchants?country=US&page=2"
},
"next": {
"href": "https://api.pushpay.com/v1/merchants?country=US&page=3"
},
"pref": {
"href": "https://api.pushpay.com/v1/merchants?country=US&page=1"
},
"first": {
"href": "https://api.pushpay.com/v1/merchants?country=US&page=0"
},
"last": {
"href": "https://api.pushpay.com/v1/merchants?country=US&page=4"
}
}
}
The Pushpay platform is shared by large numbers of merchants and users. To ensure that no one user of the platform can have an impact on the performance of others, a technique called rate limiting is used. This prevents individual client's integration with the API from being able to send too many requests within a specific timeframe. When building integrations, you need to be aware of the rate limits in place, and write your code to gracefully handle receiving a rate-limit exceeded response.
Please see our Rate Limiting Guidance.
As a platform that predominantly manages payments, money is a first-class concept in the Pushpay API - so you need to know how to represent it.
In the API, money values (such as the 'amount' for an anticipated payment) can be represented in JSON as a string value - which is the dollar amount:
{
"key": "amount",
"value": "10.25"
}
You will notice that the value is a string. If you attempt to use a JSON float, you will receive an error back from the API. For example, the following is not acceptable:
{
"key": "amount",
"value": 10.25
}
This is because floating-point values in JSON can result in rounding errors when representng amounts in some currencies. Neither should it be used to represent exact amounts.
The API does not support using JSON numbers encoded as the smallest subdivision of the respective currency (as seen in some other payment platforms). This is done intentionally, to allow Pushpay to represent the values in a human-readable way.
The only allowable characters in the string amount are 0-9 and a decimal point separating the dollar and cent amounts (no culture-specific formatting is allowed). The decimal point and cent values are optional.
When representing a monetary amount using this format, the currency of the amount will be either 'Unspecified' (which may result in a validation error, depending on the context of the operation) or it will adopt the currency of the merchant the operation is being performed for (if creating a new anticipated payment on behalf of a merchant, then it will use the merchant's currency.)
{
"key": "amount",
"value": "10.277"
}
If you wish to specify the currency for your money amount, you can use the alternative JSON object format, which has an amount and currency property.
{
"key": "amount",
"value": {
"amount": "10.50",
"currency": "USD"
}
}
The supported values for currency at the moment are:
By far the most popular payment method used in Pushpay is credit cards.
When making payments, the main test card numbers you will use are:
When testing integrations, it's valuable to be able to:
While developing your integrations with the Pushpay API using the sandbox environment, you can do just that. This is done by using a special CVV (Card Verification Value - the three digit code on the back of your credit card) to get a specific response back from the test gateway when using test cards.
Here are the possible values*:
| CVV | Behavior |
|---|---|
| 100 | Success |
| 101 | Decline - Insufficient funds |
| 102 | Decline - Expired card |
| 103 | Decline - Communication error with gateway |
| 107 | Decline - Bank Declined transaction |
* For American Express, CVVs need to be padded with any additional digit at the end. For example, 100 becomes 1001, 101 becomes 1011 and so forth.
The other main payment method that Pushpay supports is ACH payments, utilizing bank account information.
When making these payments, the main success & failure test account numbers are as follows: All test accounts utilize the same routing number, all failures triggered are EARLY FAILURES.
Routing Number: 999999992
The XXX digits specify the number of seconds to wait before triggering the result. So an account number of 999010101 will succeed after 10 seconds.
While developing your integrations with the Pushpay API using the sandbox environment, you can test ACH payments. This is done by using a special account number to trigger certain early failure conditions.
Here are the possible values:
| Account Number | Behavior |
|---|---|
| 999XXX101 | Success |
| 999XXX100 | Bank routing number validation negative (ABA) |
| 999XXX200 | Bank routing number must be 9 digits |
| 999XXX300 | Consumer verification negative |
| 999XXX400 | Invalid login |
| 999XXX500 | Access denied |
| 999XXX900 | Object reference not set to an instance of an object |
| 999XXX910 | Request timed out |
| 999XXX990 | Delays for 90 seconds in order to induce a client side timeout, then responds normally. E.g. "bank routing number validation negative (ABA)" |
To begin using the API you should next refer to the Security section to understand how to authenticate, before checking out the list of available API Operations.