curl --location --request GET 'https://api.hub2.io/refunds?fromDate=2026-01-01T00:00:00.000Z&toDate=2026-01-31T23:59:59.999Z&page=1&perPage=10' \
--header 'ApiKey: <YOUR_API_KEY>' \
--header 'MerchantId: <YOUR_MERCHANT_ID>' \
--header 'Environment: sandbox'
async function listRefunds(): Promise<void> {
const query = new URLSearchParams({
fromDate: '2026-01-01T00:00:00.000Z',
toDate: '2026-01-31T23:59:59.999Z',
page: '1',
perPage: '10',
});
const response = await fetch(`https://api.hub2.io/refunds?${query}`, {
method: 'GET',
headers: {
'ApiKey': '<YOUR_API_KEY>',
'MerchantId': '<YOUR_MERCHANT_ID>',
'Environment': 'sandbox',
},
});
if (response.ok) {
console.log(await response.json());
} else {
console.log(`HTTP status: ${response.status}`);
}
}
listRefunds();
import requests
headers = {
'ApiKey': '<YOUR_API_KEY>',
'MerchantId': '<YOUR_MERCHANT_ID>',
'Environment': 'sandbox',
}
params = {
'fromDate': '2026-01-01T00:00:00.000Z',
'toDate': '2026-01-31T23:59:59.999Z',
'page': 1,
'perPage': 10,
}
response = requests.get('https://api.hub2.io/refunds', headers=headers, params=params)
if response.status_code == 200:
print(response.json())
else:
print(f'HTTP status: {response.status_code}')
{
"data": [
{
"id": 2,
"status": "pending",
"transactionId": "tr_Kq3mZpL8vTnW2xYbC4dEf",
"amount": 1500,
"currency": "XOF",
"reason": "refund",
"paymentMethod": "mobile_money",
"fallbackUsed": false,
"createdAt": "2026-01-15T12:30:00.000Z",
"updatedAt": "2026-01-15T12:30:00.000Z"
},
{
"id": 1,
"status": "successful",
"transactionId": "tr_R7xkvVd5gRfBCWQCYrWEt",
"amount": 2000,
"currency": "XOF",
"reason": "refund",
"paymentMethod": "mobile_money",
"fallbackUsed": false,
"createdAt": "2026-01-15T12:00:00.000Z",
"updatedAt": "2026-01-15T12:30:00.000Z"
}
],
"totalItems": 2,
"currentPage": 1,
"countPerPage": 10
}
Refunds
Retrieve refunds collection
List your transfer refunds, with filters and pagination.
GET
/
refunds
curl --location --request GET 'https://api.hub2.io/refunds?fromDate=2026-01-01T00:00:00.000Z&toDate=2026-01-31T23:59:59.999Z&page=1&perPage=10' \
--header 'ApiKey: <YOUR_API_KEY>' \
--header 'MerchantId: <YOUR_MERCHANT_ID>' \
--header 'Environment: sandbox'
async function listRefunds(): Promise<void> {
const query = new URLSearchParams({
fromDate: '2026-01-01T00:00:00.000Z',
toDate: '2026-01-31T23:59:59.999Z',
page: '1',
perPage: '10',
});
const response = await fetch(`https://api.hub2.io/refunds?${query}`, {
method: 'GET',
headers: {
'ApiKey': '<YOUR_API_KEY>',
'MerchantId': '<YOUR_MERCHANT_ID>',
'Environment': 'sandbox',
},
});
if (response.ok) {
console.log(await response.json());
} else {
console.log(`HTTP status: ${response.status}`);
}
}
listRefunds();
import requests
headers = {
'ApiKey': '<YOUR_API_KEY>',
'MerchantId': '<YOUR_MERCHANT_ID>',
'Environment': 'sandbox',
}
params = {
'fromDate': '2026-01-01T00:00:00.000Z',
'toDate': '2026-01-31T23:59:59.999Z',
'page': 1,
'perPage': 10,
}
response = requests.get('https://api.hub2.io/refunds', headers=headers, params=params)
if response.status_code == 200:
print(response.json())
else:
print(f'HTTP status: {response.status_code}')
{
"data": [
{
"id": 2,
"status": "pending",
"transactionId": "tr_Kq3mZpL8vTnW2xYbC4dEf",
"amount": 1500,
"currency": "XOF",
"reason": "refund",
"paymentMethod": "mobile_money",
"fallbackUsed": false,
"createdAt": "2026-01-15T12:30:00.000Z",
"updatedAt": "2026-01-15T12:30:00.000Z"
},
{
"id": 1,
"status": "successful",
"transactionId": "tr_R7xkvVd5gRfBCWQCYrWEt",
"amount": 2000,
"currency": "XOF",
"reason": "refund",
"paymentMethod": "mobile_money",
"fallbackUsed": false,
"createdAt": "2026-01-15T12:00:00.000Z",
"updatedAt": "2026-01-15T12:30:00.000Z"
}
],
"totalItems": 2,
"currentPage": 1,
"countPerPage": 10
}
Returns a paginated list of your transfer refunds, newest first.
Headers
string
required
Your API key.
string
required
Your merchant ID.
string
required
The environment to use:
sandbox or live.Query parameters
number
Return only the refund with this ID.
string
Return refunds created on or after this date, in ISO 8601 format (e.g.,
2026-01-01T00:00:00.000Z). Applied only when toDate is also set.string
Return refunds created on or before this date, in ISO 8601 format (e.g.,
2026-01-31T23:59:59.999Z). Applied only when fromDate is also set.string
Return only refunds with this status. Possible values:
created, pending, pending_manual, successful, failed.number
default:"1"
The page number, starting at 1.
number
default:"10"
The number of refunds per page (at most
100). limit is accepted as an alias.Response
array
The refunds of the requested page.
Show Refund object
Show Refund object
number
The ID of the refund.
string
The status of the refund. Possible values:
created, pending, pending_manual, successful, failed.string
The ID of the refunded transfer.
number
The refunded amount. It equals the amount of the original transfer.
string
The currency of the refund, as an ISO 4217 code (e.g.,
XOF).string
The reason for the refund.
string
The payment method used for the refund. Possible values:
mobile_money, bank_transfer.boolean
Whether a fallback payment method was used for this refund.
string
The creation date of the refund, in ISO 8601 format.
string
The date of the last update of the refund, in ISO 8601 format.
object
Present only when the latest status change failed. Contains
code (for example insufficient_funds, service_unavailable, not_found, unknown_reason) and message, a human-readable explanation.number
The total number of refunds matching the filters.
number
The current page number.
number
The number of refunds per page.
Errors
| Status | Cause |
|---|---|
400 | A query parameter is invalid, or the merchant account was not found (merchant_not_found). |
401 | The credentials are invalid. |
403 | Access is refused, for example because your API key lacks the Api.refund_read permission (missing_permission) or the merchant account is closed (merchant_closed). The code field of the error gives the reason. |
429 | More than 10 requests per 5 seconds. |
curl --location --request GET 'https://api.hub2.io/refunds?fromDate=2026-01-01T00:00:00.000Z&toDate=2026-01-31T23:59:59.999Z&page=1&perPage=10' \
--header 'ApiKey: <YOUR_API_KEY>' \
--header 'MerchantId: <YOUR_MERCHANT_ID>' \
--header 'Environment: sandbox'
async function listRefunds(): Promise<void> {
const query = new URLSearchParams({
fromDate: '2026-01-01T00:00:00.000Z',
toDate: '2026-01-31T23:59:59.999Z',
page: '1',
perPage: '10',
});
const response = await fetch(`https://api.hub2.io/refunds?${query}`, {
method: 'GET',
headers: {
'ApiKey': '<YOUR_API_KEY>',
'MerchantId': '<YOUR_MERCHANT_ID>',
'Environment': 'sandbox',
},
});
if (response.ok) {
console.log(await response.json());
} else {
console.log(`HTTP status: ${response.status}`);
}
}
listRefunds();
import requests
headers = {
'ApiKey': '<YOUR_API_KEY>',
'MerchantId': '<YOUR_MERCHANT_ID>',
'Environment': 'sandbox',
}
params = {
'fromDate': '2026-01-01T00:00:00.000Z',
'toDate': '2026-01-31T23:59:59.999Z',
'page': 1,
'perPage': 10,
}
response = requests.get('https://api.hub2.io/refunds', headers=headers, params=params)
if response.status_code == 200:
print(response.json())
else:
print(f'HTTP status: {response.status_code}')
{
"data": [
{
"id": 2,
"status": "pending",
"transactionId": "tr_Kq3mZpL8vTnW2xYbC4dEf",
"amount": 1500,
"currency": "XOF",
"reason": "refund",
"paymentMethod": "mobile_money",
"fallbackUsed": false,
"createdAt": "2026-01-15T12:30:00.000Z",
"updatedAt": "2026-01-15T12:30:00.000Z"
},
{
"id": 1,
"status": "successful",
"transactionId": "tr_R7xkvVd5gRfBCWQCYrWEt",
"amount": 2000,
"currency": "XOF",
"reason": "refund",
"paymentMethod": "mobile_money",
"fallbackUsed": false,
"createdAt": "2026-01-15T12:00:00.000Z",
"updatedAt": "2026-01-15T12:30:00.000Z"
}
],
"totalItems": 2,
"currentPage": 1,
"countPerPage": 10
}