This describes the resources that make up the official Adpos Pay REST API.
All API access is over HTTPS, and accessed from https://api.adpos.io. All data is sent and received as JSON.
curl -i --location --request GET 'https://api.adpos.io/account' -H 'Authorization: Bearer 9|DBNErldm08pvptCEJGf66NujDMsUIGZ4CSA4FHUg8jTdXf9N0qsYAdyEw38MEhPGE6dlyITdHxWgj7cD'
HTTP/2 200
server: nginx
content-type: application/json
cache-control: no-cache, private
date: Mon, 22 Jun 2020 05:01:54 GMT
{"data":{"name":"admin","email":"user@adpos.io","timezone":"Asia\/Shanghai","transfer_amount":"50000.00","reach_amount":"49950.00","authorizations":"30.78","balance":40639.80,"cards_balance":"6393.50","available_recharge_balance":34119.47,"available_to_apply_card_count":0,"applied_card_count":97}}
Blank fields are included as null instead of being omitted.
All timestamps return in ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZ
In order to make requests against Data API, client needs to perform authentication. We use Bearer Tokens method of authentication (https://oauth.net/2/bearer-tokens/). In order to obtain auth token, client submits credentials (Only user with Administrator ROLE allowed) to /auth/access-token endpoint.
Credentials are provided by Adpos Pay as part of Data API signup process.
Requests that require authentication will return 500 "Unauthenticated."
example:
curl 'https://api.adpos.io/account' -H 'Authorization: Bearer '
Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can
be passed as an HTTP query string parameter:
curl -i "https://api.adpos.io/cards?page=1&per_page=15"
For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a
Content-Type of 'application/json' or as form:
curl 'https://api.adpos.io/auth/access-token' \
-d '{"email": "user@adpos.io", "password": ""}' \
-H 'Content-Type: application/json'
There are three possible types of client errors on API calls that receive request bodies:
Sending invalid JSON will result in a 400 Bad Request response.
Content-Length: 35
{"message":"Problems parsing JSON"}
HTTP/1.1 400 Bad Request
Content-Length: 40
{"message":"Unauthenticated.","status_code":500}
HTTP/1.1 422 Unprocessable Entity
Content-Length: 149
{
"message": "The given data was invalid.",
"errors": {
"email": [
"The email field is required."
],
"password": [
"The password field is required."
]
},
"status_code": 422
}
All error objects have resource and field properties so that your client can tell what the problem is. There's also an error code to let you know what is wrong with the field.
Requests that return multiple items will be paginated to 15 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 500 with the ?per_page parameter. per_page parameter max value is 500. Note that for technical reasons not all endpoints respect the ?per_page parameter, see cards for example.
curl 'https://api.adpos.io/cards?page=2&per_page=20'
Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.
The meta will include total, count, per_page, current_page, total_pages and links of pagination.
"meta": {
"pagination": {
"total": 97,
"count": 15,
"per_page": 15,
"current_page": 1,
"total_pages": 7,
"links": {
"next": "https://api.adpos.io/cards?page=2"
}
}
}
There's limit on request rate which client may generate. When client exceeds this limit, API responds with 429 "Too Many Requests" response. Suggested strategy for handling such responses is retrying with exponential backoff. Also, there are some common limits on query parameters shared across number of endpoints.