Cycle de vie

Le schéma ci-dessous montre comment l’API HUB2 traite un remboursement.

Remboursements

L’API des remboursements permet aux marchands de demander le remboursement d’un transfert réussi. Un remboursement a l’un des statuts suivants : created, pending, pending_manual (le remboursement nécessite une action manuelle avant d’aboutir), successful ou failed.

Remboursements

Créer un remboursement

Référence API HUB2 - Créer un remboursement La création d’un remboursement ne nécessite qu’un seul appel au point de terminaison dédié, avec l’ID du transfert à rembourser dans le champ id. Exemple de requête :

curl --location --request POST 'https://api.hub2.io/refunds/refund' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": "tr_000000000000000000011"
}'

import fetch from 'node-fetch';

async function createRefund() {
    const response = await fetch('https://api.hub2.io/refunds/refund', {
        method: 'POST',
        headers: {
            'ApiKey': '[REDACTED]',
            'MerchantId': '[REDACTED]',
            'Environment': 'sandbox',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "id": "tr_000000000000000000011"
        })
    });

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

createRefund();

import json
import requests

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

data = {
    "id": "tr_000000000000000000011"
}

response = requests.post(
    'https://api.hub2.io/refunds/refund',
    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 l’ID du remboursement (id). Le remboursement est traité de manière asynchrone, et des webhooks vous notifient de ses changements de statut.

Pour toute demande au support HUB2 concernant un remboursement, indiquez l’ID du remboursement, et non l’ID du transfert.

Restrictions

Seuls les transferts réussis peuvent être remboursés. Sinon, l’API répond 409 Conflict.
Un transfert ne peut être remboursé qu’une seule fois. Une seconde demande reçoit la réponse 409 Conflict.
Le montant du remboursement est toujours le montant total du transfert d’origine.

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, appelez le point de terminaison dédié avec l’ID obtenu lors de la création du remboursement (voir l’étape précédente). Ce point de terminaison renvoie tous les détails d’un remboursement, y compris son statut actuel. 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/refunds/123' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json'

import fetch from 'node-fetch';

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

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

getRefund();

import requests

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

response = requests.get(
    'https://api.hub2.io/refunds/123',
    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 remboursements, HUB2 envoie un webhook pour chaque événement souscrit du remboursement. Les webhooks sont la méthode recommandée pour suivre les changements de statut d’un remboursement. Certains remboursements sont traités rapidement, d’autres plus lentement, pour des raisons imprévisibles. Récupérer un remboursement dont le statut n’a pas changé est inutile.

La documentation sur les webhooks se trouve à cette adresse.

Lister les remboursements

Référence API HUB2 - Lister les remboursements Pour récupérer une liste de remboursements, 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/refunds?fromDate=2023-01-01T00:00:00.000Z&toDate=2023-01-01T12:00:00.000Z&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 getRefunds() {
    const response = await fetch('https://api.hub2.io/refunds?fromDate=2023-01-01T00:00:00.000Z&toDate=2023-01-01T12:00:00.000Z&page=1&perPage=100', {
        method: 'GET',
        headers: {
            'ApiKey': '[REDACTED]',
            'MerchantId': '[REDACTED]',
            'Environment': 'sandbox',
            'Content-Type': 'application/json'
        }
    });

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

getRefunds();

import requests

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

response = requests.get(
    'https://api.hub2.io/refunds?fromDate=2023-01-01T00:00:00.000Z&toDate=2023-01-01T12:00:00.000Z&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 :

fromDate : début de la plage de dates de création, ici 2023-01-01T00:00:00.000Z.
toDate : fin de la plage de dates de création, ici 2023-01-01T12:00:00.000Z. Le filtre de dates ne s’applique que si fromDate et toDate sont tous deux renseignés.
page et perPage : navigation dans les pages de résultats. perPage vaut 10 par défaut et ne peut pas dépasser 100.

Le paramètre de requête status permet de filtrer les remboursements par statut.

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

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

Pagination

Ce point de terminaison est paginé. Contrairement à la liste des transferts, les informations de pagination sont renvoyées dans le corps de la réponse, et non dans un en-tête Content-Range :

{
  "data": [ ... ],
  "totalItems": 2453,
  "currentPage": 1,
  "countPerPage": 100
}

Dans cet exemple, l’API a renvoyé les 100 premiers résultats sur 2453 : il faut donc récupérer 25 pages de 100 résultats pour obtenir tous les remboursements correspondant au filtre. 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 toDate est dans le futur).

Guide de démarrage

Transferts

Paiements

Webhooks

Processing Only

Payment Links

Sous-marchands

Autre

Remboursements

Cycle de vie

Remboursements

Créer un remboursement

Restrictions

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

Lister les remboursements

​Cycle de vie

​Remboursements

​Créer un remboursement

​Restrictions

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

​Lister les remboursements

​Pagination

Cycle de vie

Remboursements

Créer un remboursement

Restrictions

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

Lister les remboursements

Pagination