Intégration

Ce guide couvre les trois volets d’une intégration du paiement instantané :

Gérer vos alias (mode live uniquement).
Collecter un paiement instantané.
Envoyer un paiement instantané.

Lisez d’abord l’introduction pour les concepts et les prérequis : le paiement instantané doit être activé par HUB2 pour votre compte marchand, et votre clé API doit disposer des permissions sur les alias pour utiliser les points de terminaison d’alias.

Gérer vos alias

Référence de l’API HUB2 - Lister les alias Référence de l’API HUB2 - Créer un alias Référence de l’API HUB2 - Supprimer un alias Les trois points de terminaison d’alias ciblent l’un de vos comptes via le paramètre de chemin accountType : collection (reçoit les paiements instantanés) ou transfer (les émet). Ils ne fonctionnent qu’en mode live : en sandbox, ils sont refusés avec une erreur 403 (instant_payment_live_only).

Lister les alias d’un compte

La liste contient tous les alias que l’annuaire détient pour le compte, y compris l’alias principal enregistré par HUB2.

Curl

curl --location --request GET 'https://api.hub2.io/instant-payment/accounts/collection/aliases' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: live'

[
    {
        "aliasKey": "b9a4c2e1-7f3d-4e5a-9c8b-1d2e3f4a5b6c",
        "aliasType": "SHID",
        "accountType": "collection",
        "isPrimary": true
    }
]

aliasKey est la valeur à communiquer pour que les payeurs puissent joindre votre compte, et la valeur à envoyer comme payeeAlias lors d’une tentative de paiement.

Créer un alias

Curl

curl --location --request POST 'https://api.hub2.io/instant-payment/accounts/collection/aliases' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: live'

La requête n’a pas de corps : l’annuaire génère la clé SHID. Un compte détient un seul alias SHID : lorsque le compte en possède déjà un, l’API répond 201 et renvoie cet alias avec created à false au lieu d’en créer un second. Relancer une création est donc toujours sans risque.

{
    "aliasKey": "b9a4c2e1-7f3d-4e5a-9c8b-1d2e3f4a5b6c",
    "aliasType": "SHID",
    "accountType": "collection",
    "isPrimary": true,
    "created": false
}

Supprimer un alias

Curl

curl --location --request DELETE 'https://api.hub2.io/instant-payment/accounts/collection/aliases/b9a4c2e1-7f3d-4e5a-9c8b-1d2e3f4a5b6c' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: live'

L’API répond 204 No Content. À partir de là, les payeurs ne peuvent plus joindre votre compte avec cet alias et HUB2 ne l’accepte plus comme votre propre alias lors d’un paiement.

L’alias principal enregistré par HUB2 ne peut pas être supprimé : la requête est refusée avec une erreur 409 (instant_payment_primary_alias_protected). Contactez le support HUB2 pour le retirer.
Un alias qui n’est pas le vôtre est refusé exactement comme un alias qui n’existe pas, avec une erreur 403 (instant_payment_alias_not_owned).

Erreurs sur les alias

Statut	Code	Signification
`403`	`instant_payment_live_only`	La requête a été envoyée en mode sandbox. La gestion des alias n’est disponible qu’en mode live.
`403`	`instant_payment_not_enabled_for_merchant`	Le paiement instantané n’est pas activé pour votre compte marchand. Contactez le support HUB2.
`403`	`group_owner_transaction_forbidden`	Un marchand parent a tenté de créer ou de supprimer un alias avec son propre `MerchantId`. Utilisez le `MerchantId` du sous-marchand.
`403`	`missing_permission`	La clé API ne dispose pas de la permission requise par le point de terminaison.
`403`	`instant_payment_alias_not_owned`	L’alias n’existe pas ou n’est pas enregistré pour votre compte marchand.
`409`	`instant_payment_account_not_enrolled`	Le compte n’est pas encore enrôlé pour le paiement instantané. Contactez le support HUB2.
`409`	`instant_payment_primary_alias_protected`	L’alias est l’alias principal enregistré par HUB2 et ne peut pas être supprimé par l’API.
`409`	`instant_payment_alias_deactivated`	HUB2 a désactivé l’alias de ce compte. Seul le support HUB2 peut le rétablir.
`422`	`instant_payment_alias_refused`	L’annuaire a refusé l’opération. Rien n’a été modifié.
`422`	`instant_payment_account_missing`	Votre compte marchand n’a pas de compte live du type demandé.
`422`	`instant_payment_participant_not_served`	Le paiement instantané n’est pas disponible dans votre pays.
`502`	`instant_payment_alias_not_recorded`	L’annuaire a enregistré l’alias mais HUB2 n’a pas pu l’enregistrer. Relancez la requête.
`502`	`instant_payment_alias_deletion_not_recorded`	L’annuaire a retiré l’alias mais HUB2 n’a pas pu enregistrer le retrait. Relancez la requête.
`502`	`instant_payment_alias_divergence`	L’annuaire et HUB2 ne sont pas d’accord sur cet alias. Rien n’a été enregistré. Contactez le support HUB2.
`503`	`instant_payment_alias_rail_unavailable`	L’annuaire est indisponible. Réessayez plus tard : une nouvelle tentative ne crée jamais un second alias.

Collecter un paiement instantané

Une collecte suit l’intégration des paiements : vous créez une intention de paiement, effectuez une tentative de paiement dessus, puis suivez son statut. Seule la tentative de paiement diffère pour le paiement instantané. L’intention de paiement doit être en XOF.

Obtenir les frais

Référence de l’API HUB2 - Récupérer les frais Pour afficher les frais avant que le client ne paie, appelez le point de terminaison des frais de l’intention de paiement avec paymentMethod=instant_payment et le country. Le paramètre provider n’est pas requis pour le paiement instantané, qui n’a qu’un seul opérateur. S’il est envoyé, il est ignoré.

Curl

curl --location --request GET 'https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payment-fees?paymentMethod=instant_payment&country=CI' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: live'

Effectuer la tentative de paiement

Référence de l’API HUB2 - Tentative de paiement Effectuez une tentative de paiement sur l’intention de paiement avec le mode de paiement instant_payment.

Curl

curl --location --request POST 'https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "<PAYMENT_INTENT_TOKEN>",
    "paymentMethod": "instant_payment",
    "country": "CI",
    "instantPayment": {
        "payerAlias": "+2250700000001",
        "payeeAlias": "b9a4c2e1-7f3d-4e5a-9c8b-1d2e3f4a5b6c"
    }
}'

Champ	Requis	Description
`paymentMethod`	Oui	`instant_payment`.
`country`	Oui	`CI` ou `SN`. Il sélectionne le participant national qui traite la transaction et doit correspondre au pays de votre propre alias.
`instantPayment.payerAlias`	Oui	L’alias du compte du client : une clé `SHID`, un code marchand ou un numéro de mobile au format E.164. 64 caractères au maximum.
`instantPayment.payeeAlias`	Oui	L’un de vos alias de collecte actifs (`SHID` ou `MCOD`) : le compte qui reçoit les fonds. 64 caractères au maximum.

Il n’y a ni champ provider ni objet mobileMoney. Les deux alias sont indiqués à chaque requête et ne sont jamais tronqués ni normalisés : envoyez-les exactement tels qu’ils sont enregistrés. HUB2 vérifie tout ce qu’il peut avant que la requête n’atteigne le rail, car un paiement envoyé sur le rail ne peut pas être rappelé :

le pays est servi et le paiement instantané est activé pour votre compte marchand ;
payeeAlias est bien formé et fait partie de vos alias de collecte actifs. Un alias enregistré pour un autre marchand, ou pour personne, est refusé de la même manière (403, instant_payment_alias_not_owned) ;
payerAlias est bien formé. HUB2 ne vérifie pas qu’il existe : le rail y répond, et un alias de payeur inexistant fait échouer le paiement.

Suivre le paiement

Le paiement est créé au statut created, reste ensuite pending pendant que le rail le traite, et l’intention de paiement est processing. Le résultat provient du rail et fait passer le paiement à successful ou failed, avec un objet failure qui contient la cause de l’échec. Utilisez les webhooks pour suivre le résultat, comme pour tout autre mode de paiement. Si vous ne pouvez pas, interrogez le statut de l’intention de paiement uniquement tant que le statut est processing. Lorsque HUB2 ne peut pas savoir si le rail a reçu une requête, le paiement reste pending au lieu d’être mis en échec. Ne créez pas de second paiement pour le même achat dans ce cas : attendez le webhook ou lisez le statut.

Erreurs de paiement

Statut	Code ou message	Signification
`400`	`Instant payment details are required when payment method is set to "instant_payment".`	L’objet `instantPayment` est absent.
`400`	`payeeAlias is not a valid instant payment alias.` ou `payerAlias is not a valid instant payment alias.`	La valeur ne correspond à aucun type d’alias. Le message nomme le champ en cause.
`400`	`payeeAlias must be a SHID or MCOD alias: a merchant account cannot hold a mobile-number alias.`	Votre propre alias ne peut pas être un numéro de mobile.
`400`	`payeeAlias is not enrolled on the participant serving this country.`	Le `country` ne correspond pas au pays de votre alias.
`400`	`Instant payment is not available in this country. Supported: CI, SN.`	Le `country` n’est pas servi.
`403`	`instant_payment_not_enabled_for_merchant`	Le paiement instantané n’est pas activé pour votre compte marchand.
`403`	`instant_payment_alias_not_owned`	`payeeAlias` n’est pas un alias de collecte actif de votre compte marchand.

Envoyer un paiement instantané

Référence de l’API HUB2 - Créer un transfert Un transfert suit l’intégration des transferts. Pour le paiement instantané, définissez le type de destination à instant_payment et envoyez l’alias du bénéficiaire. La devise doit être XOF.

Curl

curl --location --request POST 'https://api.hub2.io/transfers' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: live' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "<YOUR_INTERNAL_REFERENCE>",
  "amount": 2000,
  "currency": "XOF",
  "description": "<YOUR_DESCRIPTION>",
  "destination": {
    "type": "instant_payment",
    "country": "CI",
    "recipientName": "John Doe",
    "payeeAlias": "+2250700000001"
  }
}'

Champ	Requis	Description
`destination.type`	Oui	`instant_payment`.
`destination.country`	Oui	`CI` ou `SN`.
`destination.payeeAlias`	Oui	L’alias du bénéficiaire : une clé `SHID`, un code marchand ou un numéro de mobile au format E.164. 64 caractères au maximum.
`destination.recipientName`	Non	Le nom du bénéficiaire.

La requête ne contient pas d’alias de payeur. Le compte débité est toujours votre propre compte de transfert, et HUB2 sélectionne l’alias à utiliser parmi ceux enregistrés sur ce compte, en commençant par l’alias principal. La réponse renvoie dans l’objet destination le payerAlias utilisé et le payeeAlias que vous avez envoyé, ainsi que provider à pispi. Si votre compte de transfert n’a aucun alias actif, le transfert est refusé avec une erreur 400. Comme pour un paiement, HUB2 ne vérifie que la forme de l’alias du bénéficiaire : un alias de bénéficiaire inexistant fait échouer le transfert. Un transfert passe par les statuts habituels (created, pending, puis successful ou failed). Suivez-le avec les webhooks, comme pour les autres destinations. Lorsque HUB2 ne peut pas savoir si le rail a reçu la requête, le transfert reste pending : ne créez pas de second transfert pour le même bénéficiaire, attendez le webhook ou lisez le statut.

Erreurs de transfert

Statut	Code ou message	Signification
`400`	`destination.payeeAlias is not a valid instant payment alias.`	L’alias du bénéficiaire ne correspond à aucun type d’alias.
`400`	`Instant payment is not available in this country. Supported: CI, SN.`	Le `destination.country` n’est pas servi.
`400`	`No active instant payment alias is registered for this merchant's transfer account.`	Votre compte de transfert n’a aucun alias actif. Contactez le support HUB2.
`403`	`instant_payment_not_enabled_for_merchant`	Le paiement instantané n’est pas activé pour votre compte marchand.

Causes d’échec

Lorsqu’un paiement ou un transfert échoue, le champ failure.code indique la cause. Les causes d’échec du rail sont traduites ainsi :

Cause sur un paiement	Cause sur un transfert	Signification
`customer_insufficient_funds`	`insufficient_funds`	Le compte débité ne dispose pas de fonds suffisants.
`customer_account_locked`	`forbidden_by_provider`	Le compte ne peut pas accepter le mouvement (bloqué ou clôturé).
`bad_parameters`	`bad_parameters`	L’instruction est erronée : un alias ou un compte ne correspond à rien de valide.
`forbidden_by_provider`	`forbidden_by_provider`	Le rail ou une réglementation a refusé la transaction.
`invalid_amount`	`invalid_amount`	Le montant est refusé.
`duplicate_request`	`duplicate_request`	Le rail détient déjà une transaction avec cet identifiant.
`canceled_by_customer`	`canceled`	La transaction a été retirée par l’une des parties.
`canceled`	`canceled`	La transaction a été annulée.
`fraud_suspicion`	`fraud_suspicion`	Une suspicion de fraude a été détectée.
`service_unavailable`	`service_unavailable`	Un participant ou le rail est indisponible. Une nouvelle tentative peut aboutir.
`unknown_reason`	`unknown_reason`	Le rail n’a donné aucun motif, ou un motif que HUB2 ne traduit pas encore.

Consultez aussi les listes complètes des causes d’échec des paiements et des causes d’échec des transferts.

Sandbox

En mode sandbox, aucune requête n’atteint le rail : HUB2 simule le résultat à partir des 8 derniers caractères de l’alias de la contrepartie, c’est-à-dire le payerAlias d’un paiement et le payeeAlias d’un transfert. L’alias doit tout de même être bien formé, par exemple +22500000001, et le pays doit être CI ou SN. Vos propres alias restent vérifiés en sandbox : le payeeAlias d’un paiement doit être un alias de collecte de votre compte marchand, et un transfert nécessite un alias sur votre compte de transfert. Les alias ne peuvent pas être créés en sandbox : listez-les donc au préalable en mode live (voir Gérer vos alias) et réutilisez-les en sandbox.

Paiements

8 derniers caractères du `payerAlias`	Statut	Cause d’échec
`00000001`	successful
`00000002`	successful (avec délai)
`00000003`	pending (ne se termine jamais)
`00000101`	failed	`customer_insufficient_funds`
`00000102`	failed	`bad_parameters`
`00000103`	failed	`customer_account_locked`
`00000104`	failed	`canceled_by_customer`
`00000105`	failed	`fraud_suspicion`
`00000500`	failed	`service_unavailable`

Toute autre valeur fait échouer le paiement avec bad_parameters.

Transferts

8 derniers caractères du `payeeAlias`	Statut	Cause d’échec
`00000001`	successful
`00000002`	successful (avec délai)
`00000003`	pending (ne se termine jamais)
`00000101`	failed	`insufficient_funds`
`00000102`	failed	`bad_parameters`
`00000103`	failed	`forbidden_by_provider`
`00000104`	failed	`canceled`
`00000105`	failed	`fraud_suspicion`
`00000500`	failed	`service_unavailable`

Toute autre valeur fait échouer le transfert avec invalid_destination.

Guide de démarrage

Transferts

Paiements

Paiement instantané

Webhooks

Processing Only

Payment Links

Abonnements

Sous-marchands

Autres produits

Gérer vos alias

Lister les alias d’un compte

Créer un alias

Supprimer un alias

Erreurs sur les alias

Collecter un paiement instantané

Obtenir les frais

Effectuer la tentative de paiement

Suivre le paiement

Erreurs de paiement

Envoyer un paiement instantané

Erreurs de transfert

Causes d’échec

Sandbox

Paiements

Transferts

​Gérer vos alias

​Lister les alias d’un compte

​Créer un alias

​Supprimer un alias

​Erreurs sur les alias

​Collecter un paiement instantané

​Obtenir les frais

​Effectuer la tentative de paiement

​Suivre le paiement

​Erreurs de paiement

​Envoyer un paiement instantané

​Erreurs de transfert

​Causes d’échec

​Sandbox

​Paiements

​Transferts

Gérer vos alias

Lister les alias d’un compte

Créer un alias

Supprimer un alias

Erreurs sur les alias

Collecter un paiement instantané

Obtenir les frais

Effectuer la tentative de paiement

Suivre le paiement

Erreurs de paiement

Envoyer un paiement instantané

Erreurs de transfert

Causes d’échec

Sandbox

Paiements

Transferts