Intégration

Intégration de l’API

Le mode Processing Only utilise des points de terminaison HUB2 dédiés, distincts du modèle d’agrégation standard. La principale différence est que les transactions sont traitées via vos propres comptes opérateurs, et non via les comptes agrégés de HUB2. Les points de terminaison disponibles sont documentés ici :

API Delegation

Authentification

Votre intégration utilise les mêmes clés API HUB2, mais la clé doit disposer des permissions suivantes :

Api.delegated_payment_create
Api.delegated_transfer_create

Configuration des permissions

Flux de transaction

1. Requête de transaction

Lorsque vous initiez une transaction, HUB2 :

Valide la requête : vérifie la clé API et le format de la requête.
Route la requête vers l’opérateur : l’envoie vers votre compte opérateur configuré.
Traite la transaction : l’exécute avec vos identifiants opérateur.
Renvoie la réponse : dans le même format quel que soit l’opérateur.

2. Traitement par l’opérateur

La transaction elle-même est traitée directement par votre opérateur :

Points de terminaison

Le mode Processing Only utilise des points de terminaison de création dédiés. Les points de terminaison de lecture sont les mêmes que pour le circuit standard.

Paiements

POST /delegated/payments : crée un paiement avec votre compte opérateur. Contrairement à un paiement standard, il n’est pas nécessaire de créer d’abord une intention de paiement : cette requête unique crée l’intention de paiement et effectue la tentative de paiement. Exemple :

curl --location 'https://api.hub2.io/delegated/payments' \
--header 'Environment: sandbox' \
--header 'MerchantId: [REDACTED]' \
--header 'Content-Type: application/json' \
--header 'ApiKey: [REDACTED]' \
--data '{
    "customerReference": "<YOUR_INTERNAL_CUSTOMER_REFERENCE>",
    "purchaseReference": "<YOUR_INTERNAL_REFERENCE>",
    "amount": 120,
    "currency": "XOF",
    "paymentMethod": "mobile_money",
    "country": "CI",
    "provider": "orange",
    "mobileMoney": {
        "msisdn": "00000001",
        "onCancelRedirectionUrl": "https://example.com/payment/canceled",
        "onFinishRedirectionUrl": "https://example.com/payment/finished",
        "workflow": "redirection"
    }
}'

POST /delegated/payments/sync : crée un paiement avec votre compte opérateur en mode synchrone (voir le circuit synchrone).
GET /payments : liste les paiements (même point de terminaison que pour les paiements standards). Renseignez isDelegated=true pour ne renvoyer que les paiements Processing Only. Avec isDelegated, from est obligatoire et la plage doit être inférieure à un an, sinon l’API renvoie une erreur 400.
GET /payments/{id}/status : renvoie le statut d’un paiement (même point de terminaison que pour les paiements standards).

Guide d'intégration des paiements

Transferts

POST /delegated/transfers : crée un transfert avec votre compte opérateur. Seul le point de terminaison diffère d’une requête de transfert standard. Exemple :

curl --location --request POST 'https://api.hub2.io/delegated/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/delegated/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/delegated/transfers',
    headers=headers,
    data=json.dumps(data)
)

if response.ok:
    print(response.json())
else:
    print(f'HTTP Status: {response.status_code}')

POST /delegated/transfers/irt : crée un transfert IRT avec votre compte opérateur.
GET /transfers : liste les transferts (même point de terminaison que pour les transferts standards). Renseignez isDelegated=true pour ne renvoyer que les transferts Processing Only. Avec isDelegated, from est obligatoire et la plage doit être inférieure à un an, sinon l’API renvoie une erreur 400.
GET /transfers/{id}/status : renvoie le statut d’un transfert (même point de terminaison que pour les transferts standards).

Un transfert délégué vers un MSISDN restreint renvoie 201 avec un transfert au statut failed, dont le motif d’échec est recipient_unavailable.

Guide d'intégration des transferts

Webhooks

Le mode Processing Only utilise les mêmes webhooks que le circuit standard. Si des webhooks sont déjà configurés pour les paiements et les transferts, aucune étape supplémentaire n’est nécessaire. Sinon, consultez :

Guide de démarrage

Transferts

Paiements

Paiement instantané

Webhooks

Processing Only

Payment Links

Abonnements

Sous-marchands

Autres produits

Intégration de l’API

API Delegation

Authentification

Configuration des permissions

Flux de transaction

1. Requête de transaction

2. Traitement par l’opérateur

Points de terminaison

Paiements

Guide d'intégration des paiements

Transferts

Guide d'intégration des transferts

Webhooks

Guide d'intégration des webhooks

​Intégration de l’API

API Delegation

​Authentification

Configuration des permissions

​Flux de transaction

​1. Requête de transaction

​2. Traitement par l’opérateur

​Points de terminaison

​Paiements

Guide d'intégration des paiements

​Transferts

Guide d'intégration des transferts

​Webhooks

Guide d'intégration des webhooks

Intégration de l’API

Authentification

Flux de transaction

1. Requête de transaction

2. Traitement par l’opérateur

Points de terminaison

Paiements

Transferts

Webhooks