​
Transferts (Pay-Outs)

L’API Transfert (Pay-Out API) est assez simple à implémenter, puisqu’il n’y a aucune interaction avec les clients finaux.

​
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"
  }
}'
Cette requête retourne un ID de transfert, qui est l’identifiant unique du transfert. Un identifiant unique est créé sur la plateforme HUB2 pour chaque requête de transfert.
L’ID de transfert doit être enregistré dans la base de données du marchand pour les étapes suivantes.
Pour tout ticket adressé à l’équipe de support de HUB2 concernant un transfert, c’est l’ID du transfert qui sera demandé, et non la référence du marchand.

​
Restrictions

Lors de la création d’un transfert, des vérifications sont faites sur le champ reference : aucun caractère spécial n’est permis. L’utilisation de caractères spéciaux ici produira une erreur 400 Bad Request. Les caractères autorisés sont les lettres, les chiffres, les tirets, les caractères de soulignement, les points ou les espaces. Voici la liste sous forme d’expression régulière : A-Za-z0-9\-_. .

​
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, il faut appeler le point de terminaison dédié. Note : Ce point d’accès nécessite un ID de transfert, obtenu lors de la création du transfert. (voir étape précédente). Ce point de terminaison a été conçu pour obtenir tous les détails d’un transfert, plutôt que pour vérifier les changements de statut d’un transfert. Ce point de terminaison, comme tous les points de terminaison de l’API HUB2, est limité en nombre de requêtes acceptées. Cela signifie que si ce point de terminaison est appelé trop de fois par un ID marchand, l’API HUB2 répondra avec HTTP 429 Too Many Requests à cet ID marchand.
La documentation sur les limites de flux 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' \
Une fois qu’un Transfert a été effectué et que des webhooks ont été configurés pour recevoir des notifications sur le cycle de vie du Transfert, ces derniers seront envoyés par HUB2 pour chaque événement ayant des webhooks associés. Cette méthode est la méthode recommandée pour pouvoir prendre en compte les changements de statut d’un Transfert. Certains Transferts sont traités rapidement, tandis que d’autres moins, pour des raisons diverses et non-prévisibles. Il est inutile de venir récupérer les détails d’un Transfert pour récupérer le statut d’un Transfert si aucun changement n’a eu lieu. C’est en cela que le paramétrage de webhook est recommandé.
La documentation sur les webhooks se trouve à cette adresse.

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

Cette fonctionnalité a été ajoutée le 4 Février 2025.
Alors que le endpoint vu précédemment n’était pas destiné à récupérer le statut d’un transfert pour des raisons de performances, un nouveau endpoint dédié à cette fonctionnalité a été ajouté. HUB2 API reference - Retrieve a transfer status Ce endpoint est également limité à l’utilisation mais sa limite est plus faible que celui ci-dessus. 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' \
Si des difficultés sont rencontrées lors de l’implémentation des webhooks, ce endpoint peut être utilisé pour récupérer le statut d’un transfert à la place.

​
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) peuvent être appliqués pour 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' \
Veuillez noter les paramètres suivants :
  • Paramètre from : Date de début de la plage à récupérer, la valeur ici est 2023-01-01T00:00:00.000Z
  • Paramètre to : Date de fin de la plage à récupérer, la valeur ici est 2023-01-01T12:00:00.000Z
  • Paramètres page et perPage : Ces paramètres controllent la navigation dans les pages de résultats.
Par défaut, si aucun filtre n’est défini, les 100 derniers Transferts sont renvoyés par ce point de terminaison, classés par created_at, en ordre décroissant.
Pour un grand nombre de Transferts, des requêtes paginées seront obligatoires pour récupérer toutes les transactions de l’API HUB2.

​
Pagination

La pagination est disponible sur ce point de terminaison. Les en-têtes de réponse fournissent l’en-tête Content-Range pour informer du nombre total de résultats, et la valeur de l’en-tête est au format 0-99/2453. Dans ce cas particulier, cet en-tête indique que l’API a renvoyé les 100 premiers résultats sur un total de 2453 - il y a donc 25 pages de 100 résultats à extraire pour récupérer tous les transferts correspondant au filtre initial. Un bon conseil est de définir des filtres de date dans la requête initiale, de sorte que le nombre de résultats reste le même lorsque la pagination est en cours (sauf lorsque le paramètre to est défini à une date dans le futur).