Introduction

Qolo provides RESTful based payments API. It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. You can use your favorite HTTP/REST library for your programming language to use Qolo API

Accessing the Developer Portal

The base url for the Qolo Development Environment is devapi.qolopay.com

Qolo API uses Bearer Authentication to enforce authentication for all its incoming requests. Bearer Authentication (Token Authentication) is an HTTP authentication mechanism that involves security tokens generated by Qolo server. The calling server will make a login request to get the token and will pass this token on all subsequent calls as part of the Authorization Header.

API access token can be generated by sending login_id and api_key to /api/v1/auth/login route. The access token should be passed in subsequent API calls. If access token is not passed or expired access token is passed, then server will return 401 Unauthorized response. Qolo API access token has a validity of 12 hours. When the access token expires, your application must request a new access token using the same /api/v1/auth/login route as before. The lifetime of the generated access token is 12 hours.

Important considerations

API access tokens provide complete access to all data in your program. Token allows anybody who has them to access program resources So be careful where you store the access token and avoid unnecessary logging of the tokens.

Do not request an access token for every API call. Tokens are valid for 12 hours and reusable. Also making 2 API calls for every operation is very inefficient.

Error

Qolo provides RESTful based payments API. Qolo API returns HTTP response codes to indicate status of the requests. Following are the list of common http codes with descriptions.

200 OK - Response to successful to GET and PUT methods and also used for POST that does not result in creation
201 Created - Response to successful POST that results in creation
400 Bad Request - Request has errors. Mostly request field validation errors
401 Unauthorized - When No or Invaild access token provided in header
404 Not Found - Resource with ID does not exist
405 Method Not Allowed - Http method is not allowed for the API access token
415 Unsupported Media Type
429 Too Many Requests - When a request is rejected by API gateway due to rate limiting

Idempotent Requests

Qolo supports idempotency for safely retrying requests using header value called IdempotencyKey. For POST methods, creating resources (example: /api/v1/cards) on Qolo server, this header should contain a unique ID that the server stores for a period of time. We will use this header to enforce idempotency in REST API POST calls.Then you can invoke these calls any number of times without concern that the server creates resource more than once.

Versioning

The API version is explicitly declared in the URL. For example our current version v1 is represented in url (devapi.qolopay.com/api/v1/cards). At QoloPay, the API version will not be changed for non breaking changes such as adding new endpoints or adding new fields in response objects. As an API consumer please ensure that your application gracefully handles addition of fields in the response objects. For example, During JSON response handling make sure the framework does not throw any errors due to additional fields on the response object.

Webhook

API Partners can use webhooks to receive automated notifications about all the events of their programs in real time. Rather than requiring to pull information via our API, this will push information to your URL when important events occur. Webhooks are delivered via HTTPS POST to a configured URL on your server and your server should return Http status code 200 to acknowledge the receipt of the notification.