Intégration

Intégration API

Les liens de paiement utilisent l’API HUB2. Les points de terminaison disponibles sont listés dans la documentation suivante :

API Payment Links

Authentification

Votre intégration utilise les mêmes clés API HUB2 pour l’authentification. La clé doit disposer des permissions suivantes :

Api.payment_intent_create : créer et fermer des liens de paiement
Api.payment_intent_read : consulter et lister les liens de paiement

Configuration des permissions

Points de terminaison de l’API

Lien de paiement

POST /payment-links : créer un lien de paiement en définissant les moyens de paiement et les opérateurs acceptés. L’intention de paiement et le paiement sont créés au fil du parcours du client sur la page de paiement. Exemple :

curl --location 'https://api.hub2.io/payment-links' \
--header 'Environment: sandbox' \
--header 'MerchantId: [REDACTED]' \
--header 'Content-Type: application/json' \
--header 'ApiKey: [REDACTED]' \
--data '{
    "purchaseReference": "<YOUR_PURCHASE_REFERENCE>",
    "description": "Payment for order 1234567890",
    "amount": 500,
    "currency": "XOF",
    "type": "single_use",
    "expirationDate": "<FUTURE_ISO_8601_DATE>",
    "paymentMethods": [
        "mobile_money"
    ],
    "country": "CI",
    "providers": [
        "Orange",
        "Wave",
        "MTN",
        "Moov"
    ],
    "successUrl": "https://merchant.example.com/success",
    "failureUrl": "https://merchant.example.com/failure"
}'

type vaut single_use par défaut (un seul paiement réussi). Utilisez multi_use pour accepter plusieurs paiements, éventuellement plafonnés par maximumPayments.
Si expirationDate est absent ou déjà passé, le lien expire 15 minutes après sa création.
successUrl et failureUrl doivent utiliser le schéma https.

PATCH /payment-links/{id}/close : fermer un lien de paiement avant son expiration
GET /payment-links : lister les liens de paiement créés
GET /payment-links/{id} : consulter un lien de paiement et ses tentatives de paiement

Limites de flux par point de terminaison :

POST /payment-links : 100 requêtes par 10 secondes
GET /payment-links/{id} : 1 requête par seconde
GET /payment-links : 1 requête par 5 secondes
PATCH /payment-links/{id}/close : 1 requête par seconde

Au-delà de ces limites, l’API répond HTTP 429 Too Many Requests.

Paiements par carte

Un lien propose le paiement par carte lorsque paymentMethods contient credit_card. Les paiements par carte passent toujours par le fournisseur de cartes configuré pour votre compte marchand : providers ne liste donc jamais de fournisseur de cartes. Les paiements par carte doivent être activés sur votre compte : consultez Paiements par carte dans le guide de configuration. Pour un lien accessible uniquement par carte, omettez providers. Un tableau vide est refusé avec une erreur 400 :

curl --location 'https://api.hub2.io/payment-links' \
--header 'Environment: sandbox' \
--header 'MerchantId: <YOUR_MERCHANT_ID>' \
--header 'Content-Type: application/json' \
--header 'ApiKey: <YOUR_API_KEY>' \
--data '{
    "purchaseReference": "<YOUR_PURCHASE_REFERENCE>",
    "description": "Paiement de la commande 1234567890",
    "amount": 1000,
    "currency": "XOF",
    "type": "single_use",
    "expirationDate": "<FUTURE_ISO_8601_DATE>",
    "paymentMethods": ["credit_card"],
    "country": "CI",
    "successUrl": "https://merchant.example.com/success",
    "failureUrl": "https://merchant.example.com/failure"
}'

Pour proposer le mobile money et la carte sur le même lien, indiquez les deux moyens de paiement et envoyez providers pour le mobile money :

curl --location 'https://api.hub2.io/payment-links' \
--header 'Environment: sandbox' \
--header 'MerchantId: <YOUR_MERCHANT_ID>' \
--header 'Content-Type: application/json' \
--header 'ApiKey: <YOUR_API_KEY>' \
--data '{
    "purchaseReference": "<YOUR_PURCHASE_REFERENCE>",
    "description": "Paiement de la commande 1234567890",
    "amount": 1000,
    "currency": "XOF",
    "type": "single_use",
    "expirationDate": "<FUTURE_ISO_8601_DATE>",
    "paymentMethods": ["mobile_money", "credit_card"],
    "country": "CI",
    "providers": ["orange", "mtn"],
    "successUrl": "https://merchant.example.com/success",
    "failureUrl": "https://merchant.example.com/failure"
}'

Sur la page de paiement, le client voit les opérateurs mobile money, suivis d’une option de paiement par carte. Sur un lien accessible uniquement par carte, seule l’option carte est affichée. Lorsque le client choisit la carte, le champ du numéro de téléphone est masqué et le client est redirigé vers une page de paiement par carte hébergée par le fournisseur de cartes. Ensuite, le client arrive toujours d’abord sur la page de résultat HUB2 ; son bouton l’emmène alors vers votre successUrl ou votre failureUrl si vous les avez définies. Une requête de création qui ne peut pas être acceptée renvoie une erreur 400 dont le corps contient status, code, message et request_id. Utilisez code pour savoir comment réagir :

Code	Signification	Que faire
`credit_card_provider_not_configured`	Aucun fournisseur de cartes n’est configuré sur votre compte.	Contactez le support HUB2 pour activer les paiements par carte.
`credit_card_provider_unavailable`	Le fournisseur de cartes de votre compte n’est pas activé dans le `country` du lien.	Créez le lien pour un pays où le paiement par carte est disponible, ou contactez le support HUB2.
`credit_card_fees_not_supported`	Votre compte répercute les frais de paiement sur le client, ce que les paiements par carte ne prennent pas en charge.	Contactez le support HUB2, ou proposez uniquement `mobile_money`.
`wrong_provider`	Le mobile money est demandé et aucun des `providers` listés ne le propose dans le `country`.	Listez au moins un opérateur activé pour le mobile money dans ce pays.
`payment_method_not_supported`	Le lien ne propose ni `mobile_money` ni `credit_card`.	Ajoutez `mobile_money` ou `credit_card` à `paymentMethods`.

Une requête qui inclut mobile_money sans providers est également refusée avec une erreur 400. Seul un lien accessible uniquement par carte peut les omettre.

Webhooks

Les paiements effectués via un lien déclenchent les webhooks habituels payment.* et payment_intent.*. Les liens de paiement disposent aussi de leurs propres événements : payment_links.created, payment_links.paid, payment_links.completed, payment_links.expired et payment_links.closed. Si vous avez déjà configuré des webhooks pour les paiements, aucune étape supplémentaire n’est requise. Sinon, consultez :

Guide de démarrage

Transferts

Paiements

Paiement instantané

Webhooks

Processing Only

Payment Links

Abonnements

Sous-marchands

Autres produits

Intégration API

API Payment Links

Authentification

Configuration des permissions

Points de terminaison de l’API

Lien de paiement

Paiements par carte

Webhooks

Guide d'intégration des webhooks

​Intégration API

API Payment Links

​Authentification

Configuration des permissions

​Points de terminaison de l’API

​Lien de paiement

​Paiements par carte

​Webhooks

Guide d'intégration des webhooks

Intégration API

Authentification

Points de terminaison de l’API

Lien de paiement

Paiements par carte

Webhooks