​

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.

• 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

​

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.

​

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.

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é.

​

Récupérer le statut d’un transfert

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.

​

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).