Cycle de vie

Pour vous aider à démarrer avec l’API des remboursements, cette illustration montre comment les remboursements sont traités par l’API HUB2.

Remboursements

L’API des remboursements permet aux marchands d’initier des remboursements pour les transferts précédemment réussis.

Créer un remboursement

Référence API HUB2 - Créer un remboursement Créer un remboursement nécessite un appel à l’endpoint dédié avec l’ID du transfert que vous souhaitez rembourser. Exemple de requête :
curl --location --request POST 'https://api.hub2.io/refunds' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": "tr_000000000000000000011",
  "zendeskTicketId": "zd_123456"
}'
Cette requête initiera un remboursement pour le transfert spécifié. Le remboursement sera traité de manière asynchrone et vous recevrez des notifications webhook concernant les changements de statut.
Pour tout ticket auprès de l’équipe support HUB2 concernant un remboursement, l’ID du remboursement sera demandé, pas l’ID du transfert.

Restrictions

  • Seuls les transferts réussis peuvent être remboursés
  • Un transfert ne peut être remboursé qu’une seule fois
  • Le montant du remboursement sera le montant total du transfert original

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

Référence API HUB2 - Obtenir les détails d’un remboursement Pour récupérer un remboursement, effectuez un appel à l’endpoint dédié. Note : Cet endpoint nécessite un ID de remboursement, obtenu lors de la création d’un remboursement (voir étape précédente). Cet endpoint a été conçu pour obtenir les détails complets d’un remboursement, y compris son statut actuel et les informations de traitement. Cet endpoint, comme tous les endpoints de l’API HUB2, est soumis à une limitation de taux. Cela signifie que si cet endpoint est appelé trop souvent par un ID marchand, l’API HUB2 répondra avec HTTP 429 Too Many Requests à cet ID marchand.
La documentation sur les limites de taux peut être trouvée ici.
Exemple de requête :
curl --location --request GET 'https://api.hub2.io/refunds/123' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json' \
Une fois qu’un remboursement a été créé et que les webhooks ont été configurés pour recevoir des notifications sur le cycle de vie du remboursement, HUB2 enverra des webhooks pour chaque événement associé aux webhooks configurés. C’est la méthode recommandée pour prendre en compte les changements de statut d’un remboursement. Certains remboursements sont traités rapidement, tandis que d’autres le sont moins, pour diverses raisons imprévisibles. Il n’y a aucun intérêt à récupérer les détails d’un remboursement pour récupérer le statut d’un remboursement si aucun changement n’a eu lieu. C’est pourquoi la configuration des webhooks est recommandée.
La documentation sur les webhooks peut être trouvée ici.

Lister les remboursements

Référence API HUB2 - Lister les remboursements Pour récupérer une liste de remboursements, utilisez l’endpoint dédié. Plusieurs paramètres de requête (voir ci-dessous) peuvent être appliqués pour filtrer nos résultats. Exemple de requête :
curl --location --request GET 'https://api.hub2.io/refunds?fromDate=2023-01-01T00:00:00.000&toDate=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 fromDate : identifie la date de début de la plage de récupération des remboursements, la valeur ici est 2023-01-01T00:00:00.000Z
  • Paramètre toDate : identifie la date de fin de la plage de récupération des remboursements, la valeur ici est 2023-01-01T12:00:00.000Z
  • Paramètres page et perPage : Pour contrôler la navigation à travers les pages de résultats.
Par défaut, lorsqu’aucun filtre n’est défini, les 100 derniers remboursements sont retournés par cet endpoint, ordonnés par created_at, ordre décroissant.
Pour un grand nombre de remboursements, les requêtes paginées seront obligatoires pour récupérer tous les remboursements de l’API HUB2.

Pagination

La pagination est disponible sur cet endpoint. 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 retourné les 100 premiers résultats sur un total de 2453 - il y a donc 25 pages de 100 résultats à récupérer pour récupérer tous les remboursements 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 pendant que la pagination fonctionne (sauf quand toDate est défini à une date dans le futur).