Intégration

La collecte d’un paiement se déroule en cinq étapes :

Créer une intention de paiement (PaymentIntent).
Effectuer une tentative de paiement.
(Optionnel) Côté client, authentifier la tentative de paiement.
HUB2 traite le paiement auprès du fournisseur.
Récupérer le statut de l’intention de paiement (PaymentIntent).

Créer une intention de paiement

L’objet PaymentIntent représente l’intention de collecter un paiement auprès d’un client. Il conserve la trace des frais et de chaque tentative de paiement tout au long du traitement. L’intention de paiement doit être créée sur le serveur du marchand avec un montant (amount), une devise (currency), la référence du client final (customerReference) et la référence de l’achat (purchaseReference). Créer une intention de paiement Exemple de requête :

curl --location --request POST 'https://api.hub2.io/payment-intents' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerReference": "Test_01",
    "purchaseReference": "Test_YYYY_MM_DD_01",
    "amount": 200,
    "currency": "XOF"
}'

import fetch from 'node-fetch';

async function postPaymentIntents() {
    const response = await fetch('https://api.hub2.io/payment-intents', {
        method: 'POST',
        headers: {
            'ApiKey': '[REDACTED]',
            'MerchantId': '[REDACTED]',
            'Environment': 'sandbox',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "customerReference": "Test_01",
            "purchaseReference": "Test_YYYY_MM_DD_01",
            "amount": 200,
            "currency": "XOF"
        })
    });

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

postPaymentIntents();

import requests
import json

url = 'https://api.hub2.io/payment-intents'

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

data = {
    "customerReference": "Test_01",
    "purchaseReference": "Test_YYYY_MM_DD_01",
    "amount": 200,
    "currency": "XOF"
}

response = requests.post(url, headers=headers, data=json.dumps(data))

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

Conservez l’id et le token renvoyés dans la réponse côté marchand : ils sont nécessaires aux étapes suivantes.

L’id est la référence unique de l’intention de paiement. Il sert lors des tentatives de paiement.
Le token est un JSON Web Token (JWT) qui authentifie les requêtes de paiement. Il expire 30 minutes après la création de l’intention de paiement : une tentative de paiement ou une authentification envoyée avec un jeton expiré est refusée avec une erreur 401 (bad_payment_intent_token).

{
    "id": "pi_tffiDaXyWQu203rIXhujW",
    "createdAt": "2022-07-18T06:35:25.932Z",
    "updatedAt": "2022-07-18T06:35:25.944Z",
    "merchantId": "[REDACTED]",
    "purchaseReference": "Test_YYYY_MM_DD_01",
    "customerReference": "Test_01",
    "amount": 200,
    "currency": "XOF",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
    "status": "payment_required",
    "payments": [],
    "mode": "sandbox"
}

Tentative de paiement sur une intention de paiement

Une fois l’intention de paiement créée, collectez les informations de paiement auprès du client final et effectuez une tentative de paiement (Payment). Pour cela, indiquez la méthode de paiement (paymentMethod) ainsi que tous les champs requis décrits dans la référence de l’API. Tenter un paiement Ce point de terminaison accepte le jeton JWT (token) à la place de votre clé API privée : la requête de paiement peut donc être envoyée directement côté client (par l’application du client), avec le token récupéré précédemment.

curl --location --request POST 'https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
    "paymentMethod": "mobile_money",
    "country": "CI",
    "provider": "orange",
    "mobileMoney": {
        "msisdn": "00000001"
    }
}'

import fetch from 'node-fetch';

async function postPaymentIntents() {
    const response = await fetch('https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
            "paymentMethod": "mobile_money",
            "country": "CI",
            "provider": "orange",
            "mobileMoney": {
                "msisdn": "00000001"
            }
        })
    });

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

postPaymentIntents();

import requests
import json

url = 'https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments'

headers = {
    'Content-Type': 'application/json',
}

data = {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
    "paymentMethod": "mobile_money",
    "country": "CI",
    "provider": "orange",
    "mobileMoney": {
        "msisdn": "00000001"
    }
}

response = requests.post(url, headers=headers, data=json.dumps(data))

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

Si la requête réussit, l’API renvoie un code HTTP 201 avec l’objet PaymentIntent complet dans le corps de la réponse. Le statut est désormais processing et le tableau payments contient la nouvelle tentative de paiement. Enregistrez l’id du paiement pour identifier cette tentative dans la liste : plusieurs tentatives de paiement peuvent être effectuées sur une seule intention de paiement.

{
    "id": "pi_tffiDaXyWQu203rIXhujW",
    "createdAt": "2022-07-18T06:35:25.932Z",
    "updatedAt": "2022-07-18T06:39:21.471Z",
    "merchantId": "[REDACTED]",
    "purchaseReference": "Test_YYYY_MM_DD_01",
    "customerReference": "Test_01",
    "amount": 200,
    "currency": "XOF",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
    "status": "processing",
    "payments": [
        {
            "id": "pay_GBc53h6dHvuuq4vlcP6dY",
            "intentId": "pi_tffiDaXyWQu203rIXhujW",
            "createdAt": "2022-07-18T06:39:20.721Z",
            "updatedAt": "2022-07-18T06:39:21.471Z",
            "amount": 207,
            "currency": "XOF",
            "status": "created",
            "method": "mobile_money",
            "country": "CI",
            "provider": "orange",
            "number": "00000001",
            "fees": [
                {
                    "currency": "XOF",
                    "id": "fee_drJQNmGYKQAqT7oulY519",
                    "label": "payments.customer_fee",
                    "rate": 3,
                    "rateType": "percent",
                    "amount": 7
                }
            ]
        }
    ],
    "mode": "sandbox"
}

Récupérer le statut du paiement

Après une tentative de paiement, HUB2 contacte le fournisseur et met à jour l’objet de paiement selon sa réponse. À partir de là, le statut du paiement peut être récupéré de deux façons.

1. Enregistrer un webhook pour les événements de paiement (méthode recommandée)

Utilisez les webhooks plutôt que d’interroger régulièrement (polling) le PaymentIntent pour détecter un changement de statut. Consultez la page Intégration des webhooks pour les mettre en place. Abonnez-vous aux événements payment.* ou payment_intent.*. Avec cette méthode, le serveur du marchand est notifié dès que le Payment ou le PaymentIntent est mis à jour. Aucun mécanisme de polling n’est alors nécessaire, aucune limite de débit ne s’applique et les problèmes de latence sont évités. En cas de trafic élevé, la charge est aussi réduite, tant sur les serveurs du marchand que sur ceux de HUB2.

2. Polling du statut

Interrogez le statut du paiement avec le point de terminaison dédié. Récupérer le statut d’un paiement

Ce point de terminaison est soumis à une limite de débit (5 requêtes par tranche de 5 secondes pour un même paiement) afin de prévenir les attaques par déni de service. Au-delà, l’API renvoie HTTP 429 - Too Many Requests. Tenez-en compte lors de l’implémentation du polling.

Exemple de requête :

curl --location --request GET 'https://api.hub2.io/payments/pay_GBc53h6dHvuuq4vlcP6dY/status' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox'

import fetch from 'node-fetch';

async function getPaymentStatus() {
    const response = await fetch('https://api.hub2.io/payments/pay_GBc53h6dHvuuq4vlcP6dY/status', {
        method: 'GET',
        headers: {
            'ApiKey': '[REDACTED]',
            'MerchantId': '[REDACTED]',
            'Environment': 'sandbox'
        }
    });

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

getPaymentStatus();

import requests

url = 'https://api.hub2.io/payments/pay_GBc53h6dHvuuq4vlcP6dY/status'

headers = {
    'ApiKey': '[REDACTED]',
    'MerchantId': '[REDACTED]',
    'Environment': 'sandbox',
}

response = requests.get(url, headers=headers)

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

Cette requête renvoie le statut d’un paiement. Un autre point de terminaison renvoie le statut d’une intention de paiement. Récupérer le statut d’une intention de paiement

Important

N’interrogez le statut que tant que PaymentIntent.status vaut processing ou action_required. Interroger en continu une intention de paiement au statut payment_required, successful, failed ou canceled entraîne la limitation, voire le bannissement temporaire, de l’adresse IP source.

Dans la plupart des cas, le statut suivant du PaymentIntent est action_required. Ce statut indique que le client final doit effectuer une action manuelle pour authentifier ou valider le paiement.

Gérer l’action du client

L’objet Payment contient un objet nextAction qui décrit l’action attendue du client final.

{
    "id": "pi_tffiDaXyWQu203rIXhujW",
    "...": "...",
    "amount": 200,
    "currency": "XOF",
    "status": "action_required",
    "payments": [
        {
            "id": "pay_GBc53h6dHvuuq4vlcP6dY",
            "intentId": "pi_tffiDaXyWQu203rIXhujW",
            "amount": 207,
            "currency": "XOF",
            "status": "pending",
            "method": "mobile_money",
            "country": "CI",
            "provider": "orange",
            "number": "00000001",
            "fees": ["..."],
            "nextAction": {
                "type": "otp",
                "message": "Mode Sandbox : Entrez un numéro à 4 chiffres pour authentifier le paiement."
            }
        }
    ],
    "nextAction": {
        "type": "otp",
        "message": "Mode Sandbox : Entrez un numéro à 4 chiffres pour authentifier le paiement."
    }
}

Important

La partie utile est la suivante :

"nextAction": { "type": "otp", "message": "Mode Sandbox : Entrez un numéro à 4 chiffres pour authentifier le paiement." }

Affichez nextAction.message au client final pour lui indiquer comment valider le paiement. Le type d’action est l’un des suivants :

redirection : fournit les informations nécessaires pour rediriger le client vers une page externe.
ussd : indique la procédure USSD à suivre pour valider le paiement.
otp : indique au client comment générer un code à usage unique (OTP). Le client saisit l’OTP dans un champ, que vous envoyez au point de terminaison dédié. Certains fournisseurs acceptent l’OTP directement dans la requête de tentative de paiement (voir le champ otp de l’objet mobileMoney).

Paiement par virement (bank collection)

La fonctionnalité de paiement par virement permet à un marchand de proposer à ses clients une option de paiement par virement bancaire. Le client reçoit une référence unique pour effectuer le virement.

Prérequis

Ce moyen de paiement nécessite un enregistrement KYB (Know Your Business) préalable. Effectuer une déclaration KYB

Processus de paiement

Le marchand crée une intention de paiement (PaymentIntent) comme décrit plus haut.
Pour la tentative de paiement, le marchand indique bank_transfer comme méthode de paiement et fournit l’objet bankTransfer :
- kybName (obligatoire) : le nom déclaré lors de l’enregistrement KYB.
- expirationDelay (facultatif) : nombre de secondes avant l’expiration du paiement. Minimum 3600, valeur par défaut 1296000 (15 jours).
HUB2 génère une référence unique pour le virement.
Le client reçoit cette référence et effectue le virement.
Le statut du paiement est mis à jour une fois le virement reçu. Si aucun virement n’est reçu avant la fin du délai d’expiration, le paiement échoue avec le motif expired.

Tenter un paiement

curl --location --request POST 'https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
    "paymentMethod": "bank_transfer",
    "country": "CI",
    "provider": "Bank",
    "bankTransfer": {
        "kybName": "Name declared in KYB",
        "expirationDelay": 3600
    }
}'

import fetch from 'node-fetch';

async function postPaymentIntents() {
    const response = await fetch('https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
            "paymentMethod": "bank_transfer",
            "country": "CI",
            "provider": "Bank",
            "bankTransfer": {
                "kybName": "Name declared in KYB",
                "expirationDelay": 3600
            }
        })
    });

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

postPaymentIntents();

import requests
import json

url = 'https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments'

headers = {
    'Content-Type': 'application/json',
}

data = {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
    "paymentMethod": "bank_transfer",
    "country": "CI",
    "provider": "Bank",
    "bankTransfer": {
        "kybName": "Name declared in KYB",
        "expirationDelay": 3600
    }
}

response = requests.post(url, headers=headers, data=json.dumps(data))

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

Réponse de l’API

En cas de succès, l’API renvoie un objet PaymentIntent contenant les détails du paiement par virement, y compris la référence unique générée pour le virement.

Important : communiquez la référence au client final pour qu’il puisse effectuer le virement. Le statut du paiement est mis à jour une fois le virement reçu et traité.

Guide de démarrage

Transferts

Paiements

Webhooks

Processing Only

Payment Links

Sous-marchands

Autre

Créer une intention de paiement

Tentative de paiement sur une intention de paiement

Récupérer le statut du paiement

1. Enregistrer un webhook pour les événements de paiement (méthode recommandée)

2. Polling du statut

Important

Gérer l’action du client

Important

Paiement par virement (bank collection)

Prérequis

Processus de paiement

Réponse de l’API

​Créer une intention de paiement

​Tentative de paiement sur une intention de paiement

​Récupérer le statut du paiement

​1. Enregistrer un webhook pour les événements de paiement (méthode recommandée)

​2. Polling du statut

Important

​Gérer l’action du client

Important

​Paiement par virement (bank collection)

​Prérequis

​Processus de paiement

​Réponse de l’API

Créer une intention de paiement

Tentative de paiement sur une intention de paiement

Récupérer le statut du paiement

1. Enregistrer un webhook pour les événements de paiement (méthode recommandée)

2. Polling du statut

Gérer l’action du client

Paiement par virement (bank collection)

Prérequis

Processus de paiement

Réponse de l’API