​
Lifecycle

To help getting started with the Refunds API, this illustration shows off how refunds are handled by HUB2 API.

​
API Reference

The Refunds API allows merchants to initiate refunds for previously successful transfers.

​
Creating a refund

HUB2 API reference - Create a refund Creating a refund requires one call to the dedicated endpoint with the transfer ID that you want to refund. Sample request : 
curl --location --request POST 'https://api.hub2.io/refunds' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": "tr_000000000000000000011",
  "zendeskTicketId": "zd_123456"
}'
This request will initiate a refund for the specified transfer. The refund will be processed asynchronously and you will receive webhooks notifications about the status changes.
For any ticket to HUB2 support team concerning a refund, the refund ID will be asked, not the transfer ID.

​
Restrictions

  • Only successful transfers can be refunded
  • A transfer can only be refunded once
  • The refund amount will be the full amount of the original transfer

​
Retrieving refund details

HUB2 API reference - Get refund details To retrieve a refund, perform a call to the dedicated endpoint. Note : This endpoint requires a refund ID, obtained when creating a refund (see previous step). This endpoint was designed to get the full details of a refund, including its current status and processing information. This endpoint, like every endpoint on HUB2 API, is rate limited. That means that if this endpoint is called too many times by a merchant ID, the HUB2 API will respond with HTTP 429 Too Many Requests to that merchant ID.
Documentation about rate limits can be found here.
Sample request : 
curl --location --request GET 'https://api.hub2.io/refunds/123' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json' \
Once a Refund has been created and webhooks have been configured to receive notifications about the Refund’s lifecycle, HUB2 will send webhooks for each event associated with configured webhooks. This is the recommended method for taking into account changes in the status of a Refund. Some Refunds are processed quickly, while others less so, for a variety of unforeseeable reasons. There is no point in retrieving the details of a Refund to retrieve the status of a Refund if no change has taken place. This is why setting up webhooks is recommended.
Documentation about webhooks can be found here.

​
List refunds

HUB2 API reference - List refunds To fetch a list of refunds, use the dedicated endpoint. Several query parameters (see below) can be applied to filter our results. Sample request : 
curl --location --request GET 'https://api.hub2.io/refunds?fromDate=2023-01-01T00:00:00.000&toDate=2023-01-01T12:00:00.000&page=1&perPage=100' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json' \
Please note the following parameters:
  • Parameter fromDate : identifies the starting date of the refunds retrieval range, the value here is 2023-01-01T00:00:00.000Z
  • Parameter toDate : identifies the ending date of the refunds retrieval range, the value here is 2023-01-01T12:00:00.000Z
  • Parameters page and perPage : To control navigation through the result pages.
By default, when no filter is defined, the 100 last refunds are returned by this endpoint, ordered by created_at, descending.
For a big number of refunds, paginated requests will be mandatory to retrieve all refunds from the HUB2 API.

​
Pagination

Pagination is available on that endpoint. The response headers provide the Content-Range header to inform of the total number of results, and the header value is in the format 0-99/2453. In this particular case, this header indicates that the API returned the first 100 results out of a total of 2453 - so there are 25 pages of 100 results to fetch to retrieve all refunds corresponding to the initial filter. A good advice is to set date filters in the initial request, so the number of results remains the same while pagination is running (except when toDate is set to a date in the future).