Skip to main content

About the Hubpay Connect API

Discover how to gain access, authenticate, and effectively utilise the Hubpay Connect API.

Base URL​

https://api.hubpay.ae

Each request uses one of the two URLs provided, depending on whether you are operating within your live (production) environment or your test (sandbox) environment.

Authentication​

To access the services provided by the Hubpay Connect API, users are required to include API keys for authentication. These unique keys are provided to you upon in the onboarding process of your account.

To gain access to the API, it's essential to include an Authorization header with each of your requests. Ensure that you explicitly specify the use of an API key for authentication, labeled as "ApiKey", similar to the HTTP basic access authentication method.

The following is an example of how to include an API key in your request:

curl -i -X GET \
  'https://api.hubpay.ae/api/v2/webhooks' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

Whitelisting​

To ensure the security of your account, Hubpay requires you to whitelist the IP addresses from which you will be making requests. This is a security measure to prevent unauthorized access to your account. You can whitelist your IP addresses by contacting our support team.

Idempotency​

To prevent the occurrence of duplicate requests, the Hubpay Connect API supports idempotency. This means that if you make a request with the same idempotency key, the API will return the same response as the original request. In most cases, the idempotency key will be the externalId.

This is useful in cases where you are unsure whether a request was successful or not, and you want to ensure that the request is not processed more than once.

Rate Limiting​

To ensure a stable and reliable environment, Hubpay has put in place a rate limiting policy. This policy limits the number of requests you can make within a certain period. If the limit is exceeded, a 429 Too Many Requests response will be returned

This measure helps us maintain a high-quality service for all our users.

Pagination​

The Hubpay Connect API manages large datasets by dividing the response into pages. When you make a request that returns a large number of items, the response will be paginated. Each page will contain a certain number of items. You can optionally specify the number of items per page using the size parameter in your request, which defaults to 10 if not provided. You can also specify which page number you want to access using the page parameter, which defaults to 0 (the first page) if not provided.

The response will include the following fields:

  • content: An array of the items on the current page.
  • number: The current page number.
  • size: The number of items per page.
  • totalElements: The total number of items across all pages.
  • last: A boolean indicating whether this is the last page.
  • totalPages: The total number of pages.
  • first: A boolean indicating whether this is the first page.
  • sort: An object containing the sorting parameters used.
  • numberOfElements: The number of items on the current page.
  • empty: A boolean indicating whether the current page is empty.

For example, to access the third page of a dataset and limit the number of items per page to 5, you would include ?page=2&size=5 in your request URL. If you don't provide these parameters, the API will return the first page with a default size of 10 items.

Filtering​

In Hubpay Connect API, a search parameter is available to use in numerous requests. This parameter is designed to assist in filtering the response items based on a specific field.

Sorting​

The sort parameter is available for use in certain requests. This parameter allows you to order the items in the response based on a specific field.

Response Statuses​

The Hubpay Connect API uses standard HTTP status codes to indicate the success or failure of a request (2xx, 4xx & 5xx).

Errors​

In the event of an error, the response will include a Problem Details object with the following fields:

  • type: A URI if available, that identifies the problem type. This can be used to provide more information about the problem.
  • title: A short, human-readable summary of the problem.
  • status: The HTTP status code for this occurrence of the problem.
  • detail: A human-readable explanation specific to this occurrence of the problem.
  • instance: A URI that identifies the specific occurrence of the problem.

Webhooks​

The Hubpay Connect API provides a webhook system that allows you to receive real-time notifications about events that occur in your account. If a webhook delivery does not succeed for any reason, we will attempt to resend it using an exponential backoff strategy over a period of up to 7 days. We consider a delivery successful when we receive a 200 status code in response.