Transferts (Pay-Outs)

L’API Transfert (Pay-Out API) est simple à intégrer, car elle n’implique aucune interaction avec les clients finaux.

Transferts (Pay-Outs)

Faire un transfert

HUB2 API reference - Create a transfer La création d’un Transfert (Pay-Out) ne nécessite qu’un seul appel au point de terminaison dédié. Exemple de requête :

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}')

L’API répond 201 Created et renvoie le transfert, avec son ID : l’identifiant unique que HUB2 crée pour chaque demande de transfert.

Enregistrez l’ID du transfert dans votre base de données : les étapes suivantes en ont besoin.

Pour toute demande au support HUB2 concernant un transfert, indiquez l’ID du transfert, et non votre propre référence.

Restrictions

Pour les transferts mobile money vers le Togo (destination.country = TG), le champ reference ne doit contenir aucun caractère spécial. Une référence contenant des caractères spéciaux est rejetée avec une erreur 400 Bad Request (code forbidden_special_chars). Les caractères autorisés sont les lettres, les chiffres, le tiret, le tiret bas, l’espace et la barre verticale. Sous forme de classe de caractères d’expression régulière : [A-Za-z0-9\-_\s|].

Récupérer les détails d’un transfert

HUB2 API reference - Get transfer details Pour récupérer les détails d’un transfert, appelez le point de terminaison dédié avec l’ID obtenu lors de la création du transfert (voir l’étape précédente). Ce point de terminaison renvoie tous les détails d’un transfert. Il n’est pas conçu pour suivre les changements de statut. Ce point de terminaison, comme tous les points de terminaison de l’API HUB2, est soumis à une limite de requêtes : s’il est appelé trop souvent, l’API HUB2 répond HTTP 429 Too Many Requests.

La documentation sur les limites de requêtes se trouve à cette adresse.

Exemple de requête :

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}')

Une fois les webhooks configurés pour le cycle de vie des transferts, HUB2 envoie un webhook pour chaque événement souscrit du transfert. Les webhooks sont la méthode recommandée pour suivre les changements de statut d’un transfert. Certains transferts sont traités rapidement, d’autres plus lentement, pour des raisons imprévisibles. Récupérer un transfert dont le statut n’a pas changé est inutile.

La documentation sur les webhooks se trouve à cette adresse.

Récupérer le statut d’un transfert

Ce point de terminaison est disponible depuis le 4 février 2025.

Pour des raisons de performances, le point de terminaison précédent n’est pas destiné à récupérer le statut d’un transfert. Un point de terminaison dédié remplit ce rôle. HUB2 API reference - Retrieve a transfer status Ce point de terminaison est également soumis à une limite de requêtes, mais celle-ci est moins restrictive que celle du point de terminaison précédent. Exemple de requête :

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}')

Si vous ne pouvez pas mettre en place les webhooks, utilisez ce point de terminaison pour récupérer le statut d’un transfert.

Lister des transferts

HUB2 API reference - List transfers Pour récupérer une liste de transferts, utilisez le point de terminaison dédié. Plusieurs paramètres de requête (voir ci-dessous) permettent de filtrer les résultats. Exemple de requête :

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}')

Paramètres de requête utilisés dans cet exemple :

from : début de la plage de dates, ici 2023-01-01T00:00:00.000.
to : fin de la plage de dates, ici 2023-01-01T12:00:00.000.
page et perPage : navigation dans les pages de résultats. perPage vaut 10 par défaut et ne peut pas dépasser 100.

Par défaut, si aucun filtre n’est défini, ce point de terminaison renvoie les 10 transferts les plus récents, classés par date de création décroissante.

Pour un grand nombre de transferts, utilisez des requêtes paginées pour tous les récupérer.

Pagination

Ce point de terminaison est paginé. L’en-tête de réponse Content-Range indique la plage des résultats renvoyés, par exemple 0-99/999999. La valeur après la barre oblique n’est pas le nombre exact de transferts correspondants. Pour récupérer tous les transferts correspondant au filtre, demandez la page suivante jusqu’à obtenir une page contenant moins de résultats que perPage. Définissez des filtres de date dès la requête initiale, afin que le nombre de résultats reste stable pendant la pagination (sauf si to est dans le futur).

Guide de démarrage

Transferts

Paiements

Webhooks

Processing Only

Payment Links

Sous-marchands

Autre

Intégration

Transferts (Pay-Outs)

Faire un transfert

Restrictions

Récupérer les détails d’un transfert

Récupérer le statut d’un transfert

Lister des transferts

​Transferts (Pay-Outs)

​Faire un transfert

​Restrictions

​Récupérer les détails d’un transfert

​Récupérer le statut d’un transfert

​Lister des transferts

​Pagination

Transferts (Pay-Outs)

Faire un transfert

Restrictions

Récupérer les détails d’un transfert

Récupérer le statut d’un transfert

Lister des transferts

Pagination