Getting started
This page instructs you on how to get started with PayApi API endpoints and how to implement your integration. Before you begin, we assume that you have some sort of knowledge regarding RESTful APIs and programming. In order to get started, please get yourself a nice chair and install the cURL utility. If you have the cURL installed already, congratulations, you are now ready to begin familiarising yourself with the PayApi HTTP methods. Get a cup of coffee and open your terminal/command prompt. Now, in the terminal window, please execute following:
Read our latest API documentation here and get started for free!
Let’s see what just happened? First, we executed a standard cURL command with one of the PayApi endpoints as a parameter. In this request, we asked for IP address data for Google’s global DNS server (8.8.8.8). We also asked for extra information using the ‘-i’ parameter with the cURL command that shows us the server response (200 OK) and all related headers in the response.
From the response you can understand that PayApi delivers JSON data as its result. This data is easy to parse using your chosen platform’s built-in JSON methods and functions. We also learnt that for all free/public requests, the PayApi does throttling of maximum number of requests per user (see Limits below). For authorized endpoints, there are no limitations but using these requires a subscription and registration as a PayApi user.
At this point, it is good to remind you that while using and accessing the PayApi services, API, website and any related material or products, you are subject to our Terms of Service.
ENDPOINTS
For your convenience, we provide the hosts listed below for your use. Please use the correct host endpoint for your purposes. Please also notice that the endpoints are identical in terms of official functionality, however, the staging environment provides some added new features and at the same time may not be as stable and reliable (note that that SLAs are provided for the staging environment).
All testing should be done against our staging environment. Only communication using HTTPS is allowed. We do not support HTTP connections anymore.
| Name | URL | Description |
|---|---|---|
| Production | https://input.payapi.io | Production API. Use this in all your commercial integrations and for production environments. |
| Staging | https://staging-input.payapi.io | Staging/Testing API. This can be used in your development environments for testing and pre-integration work. No uptime guarantees. New features should be tested here first! |
HTTP METHODS & STATUS CODES
PayApi is a RESTful API which understands and follows the standard HTTP methods and status codes in all cases, where possible. This provides you with some upfront familiarity when working with the server and API functionality, alleviating the need to constantly be checking the API reference documentation.
| Method | Description |
|---|---|
| GET | Retrieve a single resource or all resources in a collection |
| POST | Create/add a new resource in a collection |
| PUT | Update a resource |
| DELETE | Remove a resource |
| Code | Name | Description |
|---|---|---|
| 200 | OK | Success |
| 304 | Not Modified | There was no new data to return |
| 400 | Bad Request | The request was invalid or cannot be otherwise served |
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | The request is understood, but it has been refused or access is not allowed |
| 404 | Not Found | The URI requested is invalid or the resource requested does not exist |
| 422 | Unprocessable Entity | Returned when POST action is unable to be processed |
| 429 | Too Many Requests | Returned when a request cannot be served due to heavy traffic |
| 500 | Internal Server Error | Something is broken |
| 502 | Bad Gateway | Server is down or being upgraded |
| 503 | Service Unavailable | Servers are up, but overloaded with requests. Try again later |
| 504 | Gateway timeout | Servers are up, but the request couldn’t be serviced due to some failure. Try again later |
FOR CLARIFICATION
When requesting a unique resource, which cannot be found, the API returns a 404 error. The message body can be empty or null.
When requesting a unique resource, which can be found, API returns 200 and the data is provided in the message body.
When querying a collection or set, and query returns nothing/is empty, the API returns 200 and the message body consists of empty JSON {} or empty array [].
When requesting a boolean result, the API returns 200 and the results is contained in the message body: true or false as a ‘result’ parameter.
AUTHENTICATION
The usage of the free/public services do not require any authentication. However, if you intend to use our payment service or extended fraud check, you have to authenticate yourself. The authentication requires that you have signed up as a PayApi user and know your API key and necessary details. The authentication process is described in more details in the API Documentation / Authentication section.
LIMITS
In order for us to keep our API endpoint reliable and stable, certain throttling is carried out. This means that although we want to and intend to provide free/public services, without any limitations for use, we still need to apply some limitations to keep the API from being abused or spammed.
Under normal circumstances the following limitations and throttling applies (subject to change without notification):
- FREE/PUBLIC API: Maximum of 10000 requests per day in production (50 000 in staging)
- AUTHORIZED API: No limitations at the moment
- SECUREFORM: Maximum of 10000 requests per day (50 000 in staging)
WEBSHOP: Maximum of 10000 requests per day (50 000 in staging)
API REQUEST EXAMPLES
Check if IP address is blacklisted:
curl -XGET https://input.payapi.io/v1/api/fraud/blacklist/ip/8.8.8.8 {"ip":"8.8.8.8","result":false}
curl -XGET https://input.payapi.io/v1/api/fraud/bindata/431944 {"bin":431944,"brand":"VISA","countryCode":"IE","countryName":"Ireland","cardType":"DEBIT","cardCategory":"CLASSIC"}
Any modification or changes to the representation of these images, logos and any other branding of PayApi is strictly forbidden. If you have any questions, please do not hesitate to contact us!
ISSUES
It is of utmost important that all issues, errors, bugs and deviations will be carefully documented, tracked and managed. This provides better transparency and predictability for future PayApi versions and releases. Please send any issues, error report or other support requests to support@payapi.io.