Refunds

Lifecycle

The diagram below shows how the HUB2 API processes a refund.

Refunds

The Refunds API lets merchants request the refund of a successful transfer.

A refund has one of the following statuses: created, pending, pending_manual (the refund requires a manual action before it completes), successful or failed.

• Refunds
  • Creating a refund
    • Restrictions
  • Retrieving refund details
  • List refunds
    • Pagination

---

Creating a refund

HUB2 API reference - Create a refund

Creating a refund requires a single call to the dedicated endpoint, with the ID of the transfer to refund in the id field.

Sample request:

Curl

curl --location --request POST 'https://api.hub2.io/refunds/refund' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": "tr_000000000000000000011"
}'

The API responds with 201 Created and returns the refund ID (id). The refund is processed asynchronously, and webhooks notify you of its status changes.

When contacting HUB2 support about a refund, provide the refund ID, not the transfer ID.

Restrictions

• Only successful transfers can be refunded. Otherwise, the API responds with 409 Conflict.
• A transfer can only be refunded once. A second request responds with 409 Conflict.
• The refund amount is always the full amount of the original transfer.

---

Retrieving refund details

HUB2 API reference - Get refund details

To retrieve a refund, call the dedicated endpoint with the refund ID obtained when the refund was created (see previous step).

This endpoint returns the full details of a refund, including its current status. This endpoint, like every HUB2 API endpoint, is rate limited: when it is called too often, the HUB2 API responds with HTTP 429 Too Many Requests.

Documentation about rate limits can be found here.

Sample request:

Curl

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 webhooks are configured for the refund lifecycle, HUB2 sends a webhook for each subscribed event of the refund.

Webhooks are the recommended way to track refund status changes. Some refunds are processed quickly, others take longer, for reasons that cannot be predicted. Fetching a refund when its status has not changed is wasted effort.

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) filter the results.

Sample request:

Curl

curl --location --request GET 'https://api.hub2.io/refunds?fromDate=2023-01-01T00:00:00.000Z&toDate=2023-01-01T12:00:00.000Z&page=1&perPage=100' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json'

Query parameters used in this example:

• fromDate: start of the creation date range, here 2023-01-01T00:00:00.000Z.
• toDate: end of the creation date range, here 2023-01-01T12:00:00.000Z. The date filter only applies when both fromDate and toDate are set.
• page and perPage: navigation through the result pages. perPage defaults to 10 and cannot exceed 100.

The status query parameter filters refunds by status.

By default, when no filter is set, this endpoint returns the 10 most recent refunds, ordered by creation date, descending.

For a large number of refunds, use paginated requests to retrieve all of them.

Pagination

This endpoint is paginated. Unlike the transfers list, the pagination details are returned in the response body, not in a Content-Range header:

{
  "data": [ ... ],
  "totalItems": 2453,
  "currentPage": 1,
  "countPerPage": 100
}

In this example, the API returned the first 100 results out of 2453, so 25 pages of 100 results must be fetched to retrieve every refund matching the filter.

Set date filters in the initial request so the number of results stays the same while you paginate (unless toDate is in the future).