Information for developers

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!

curl -i https://input.payapi.io/v1/api/fraud/ipdata/8.8.8.8

If all went well, you should see something like this as your output:

HTTP/1.1 200 OK
X-Rate-Limit-Limit: 10000
X-Rate-Limit-Remaining: 9999
X-Rate-Limit-Reset: 86121072
Content-Type: application/json; charset=utf-8
Content-Length: 218
Connection: keep-alive
Vary: Accept-Encoding

{"ip":"8.8.8.8","countryCode":"US","countryName":"United States","regionName":"California","regionCode":"CA","postalCode":"94035","continent Code":"NA","timezone":"America/Los_Angeles","offset":"-7","isp":"Google Inc."}

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.

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.

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}

Check credit card BIN number data:

curl -XGET https://input.payapi.io/v1/api/fraud/bindata/431944 {"bin":431944,"brand":"VISA","countryCode":"IE","countryName":"Ireland","cardType":"DEBIT","cardCategory":"CLASSIC"}

See more examples in our API Documentation .

PAYAPI PROTECTED

Once you have successfully integrated PayApi into your application, website or backend, you are free to use our “PayApi Protected” logos. For your convenience, we provide you 2 different themes to fit into your look & feel: one for a white background and one for darker themes.

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.

Please make every attempt to be as descriptive as possible in your email.