Transfers (Pay-Outs)

The Transfer API (Pay-Out API) is simple to integrate, as it involves no interaction with end customers.

Transfers (Pay-Outs)

Making a transfer

HUB2 API reference - Create a transfer Performing a transfer only requires one call to the dedicated endpoint. Sample request:

curl --location --request POST 'https://api.hub2.io/transfers' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "<YOUR_INTERNAL_REFERENCE>",
  "amount": 2000,
  "currency": "XOF",
  "description": "<YOUR_DESCRIPTION>",
  "destination": {
    "type": "mobile_money",
    "country": "CI",
    "recipientName": "John Doe",
    "msisdn": "+225000000000",
    "provider": "orange"
  }
}'

import fetch from 'node-fetch';

async function postTransfer() {
    const response = await fetch('https://api.hub2.io/transfers', {
        method: 'POST',
        headers: {
            'ApiKey': '[REDACTED]',
            'MerchantId': '[REDACTED]',
            'Environment': 'sandbox',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "reference": "<YOUR_INTERNAL_REFERENCE>",
            "amount": 2000,
            "currency": "XOF",
            "description": "<YOUR_DESCRIPTION>",
            "destination": {
                "type": "mobile_money",
                "country": "CI",
                "recipientName": "John Doe",
                "msisdn": "+225000000000",
                "provider": "orange"
            }
        })
    });

    if (response.ok) {
        const result = await response.json();
        console.log(result);
    } else {
        console.log(`HTTP Status: ${response.status}`);
    }
}

postTransfer();

import json
import requests

headers = {
    'ApiKey': '[REDACTED]',
    'MerchantId': '[REDACTED]',
    'Environment': 'sandbox',
    'Content-Type': 'application/json',
}

data = {
    "reference": "<YOUR_INTERNAL_REFERENCE>",
    "amount": 2000,
    "currency": "XOF",
    "description": "<YOUR_DESCRIPTION>",
    "destination": {
        "type": "mobile_money",
        "country": "CI",
        "recipientName": "John Doe",
        "msisdn": "+225000000000",
        "provider": "orange"
    }
}

response = requests.post(
    'https://api.hub2.io/transfers',
    headers=headers,
    data=json.dumps(data)
)

if response.ok:
    print(response.json())
else:
    print(f'HTTP Status: {response.status_code}')

The API responds with 201 Created and returns the transfer, including its ID: the unique identifier HUB2 creates for each transfer request.

Save the transfer ID in your database: the next steps require it.

When contacting HUB2 support about a transfer, provide the transfer ID, not your own reference.

Restrictions

For mobile money transfers to Togo (destination.country = TG), the reference field must not contain special characters. A reference with special characters is rejected with a 400 Bad Request error (code forbidden_special_chars). Allowed characters are letters, digits, hyphens, underscores, spaces and the pipe character. As a regular expression character class: [A-Za-z0-9\-_\s|].

Retrieving transfer details

HUB2 API reference - Get transfer details To retrieve a transfer, call the dedicated endpoint with the transfer ID obtained when the transfer was created (see previous step). This endpoint returns the full details of a transfer. It is not meant for polling status changes. 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 --location --request GET 'https://api.hub2.io/transfers/tr_xxxxxxxxxxxxxxxxxx' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json'

import fetch from 'node-fetch';

async function getTransfer() {
    const response = await fetch('https://api.hub2.io/transfers/tr_xxxxxxxxxxxxxxxxxx', {
        method: 'GET',
        headers: {
            'ApiKey': '[REDACTED]',
            'MerchantId': '[REDACTED]',
            'Environment': 'sandbox',
            'Content-Type': 'application/json'
        }
    });

    if (response.ok) {
        const transfer = await response.json();
        console.log(transfer);
    } else {
        console.log(`HTTP Status: ${response.status}`);
    }
}

getTransfer();

import requests

headers = {
    'ApiKey': '[REDACTED]',
    'MerchantId': '[REDACTED]',
    'Environment': 'sandbox',
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://api.hub2.io/transfers/tr_xxxxxxxxxxxxxxxxxx',
    headers=headers
)

if response.status_code == 200:
    print(response.json())
else:
    print(f'HTTP Status: {response.status_code}')

Once webhooks are configured for the transfer lifecycle, HUB2 sends a webhook for each subscribed event of the transfer. Webhooks are the recommended way to track transfer status changes. Some transfers are processed quickly, others take longer, for reasons that cannot be predicted. Fetching a transfer when its status has not changed is wasted effort.

Documentation about webhooks can be found here.

Retrieve a transfer status

This endpoint has been available since 4 February 2025.

For performance reasons, the previous endpoint is not meant for retrieving a transfer status. A dedicated endpoint serves that purpose. HUB2 API reference - Retrieve a transfer status This endpoint is also rate limited, but its limit is less restrictive than that of the previous endpoint. Sample request:

curl --location --request GET 'https://api.hub2.io/transfers/tr_xxxxxxxxxxxxxxxxxx/status' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json'

import fetch from 'node-fetch';

async function getTransfer() {
    const response = await fetch('https://api.hub2.io/transfers/tr_xxxxxxxxxxxxxxxxxx/status', {
        method: 'GET',
        headers: {
            'ApiKey': '[REDACTED]',
            'MerchantId': '[REDACTED]',
            'Environment': 'sandbox',
            'Content-Type': 'application/json'
        }
    });

    if (response.ok) {
        const transfer = await response.json();
        console.log(transfer);
    } else {
        console.log(`HTTP Status: ${response.status}`);
    }
}

getTransfer();

import requests

headers = {
    'ApiKey': '[REDACTED]',
    'MerchantId': '[REDACTED]',
    'Environment': 'sandbox',
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://api.hub2.io/transfers/tr_xxxxxxxxxxxxxxxxxx/status',
    headers=headers
)

if response.status_code == 200:
    print(response.json())
else:
    print(f'HTTP Status: {response.status_code}')

If you cannot implement webhooks, use this endpoint to fetch the status of a transfer instead.

List transfers

HUB2 API reference - List transfers To fetch a list of transfers, use the dedicated endpoint. Several query parameters (see below) filter the results. Sample request:

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

import fetch from 'node-fetch';

async function getTransfers() {
    const response = await fetch('https://api.hub2.io/transfers?from=2023-01-01T00:00:00.000&to=2023-01-01T12:00:00.000&page=1&perPage=100', {
        method: 'GET',
        headers: {
            'ApiKey': '[REDACTED]',
            'MerchantId': '[REDACTED]',
            'Environment': 'sandbox',
            'Content-Type': 'application/json'
        }
    });

    if (response.ok) {
        const transfers = await response.json();
        console.log(transfers);
    } else {
        console.log(`HTTP Status: ${response.status}`);
    }
}

getTransfers();

import requests

headers = {
    'ApiKey': '[REDACTED]',
    'MerchantId': '[REDACTED]',
    'Environment': 'sandbox',
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://api.hub2.io/transfers?from=2023-01-01T00:00:00.000&to=2023-01-01T12:00:00.000&page=1&perPage=100',
    headers=headers
)

if response.status_code == 200:
    print(response.json())
else:
    print(f'HTTP Status: {response.status_code}')

Query parameters used in this example:

from: start of the date range, here 2023-01-01T00:00:00.000.
to: end of the date range, here 2023-01-01T12:00:00.000.
page and perPage: navigation through the result pages. perPage defaults to 10 and cannot exceed 100.

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

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

Pagination

This endpoint is paginated. The Content-Range response header gives the range of the returned results, for example 0-99/999999. The value after the slash is not an exact count of the matching transfers. To retrieve every transfer matching the filter, request the next page until a page returns fewer results than perPage. Set date filters in the initial request so the number of results stays the same while you paginate (unless to is in the future).

Getting started

Transfers

Payments

Webhooks

Processing Only

Payment Links

Submerchants

Other

Integration

Transfers (Pay-Outs)

Making a transfer

Restrictions

Retrieving transfer details

Retrieve a transfer status

List transfers

​Transfers (Pay-Outs)

​Making a transfer

​Restrictions

​Retrieving transfer details

​Retrieve a transfer status

​List transfers

​Pagination

Transfers (Pay-Outs)

Making a transfer

Restrictions

Retrieving transfer details

Retrieve a transfer status

List transfers

Pagination