> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hub2.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Intégration

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

1. [Gérer vos alias](#gérer-vos-alias) (mode live uniquement).
2. [Collecter un paiement instantané](#collecter-un-paiement-instantané).
3. [Envoyer un paiement instantané](#envoyer-un-paiement-instantané).

Lisez d'abord l'[introduction](https://docs.hub2.io/integration/fr/instant_payment/instant_payment_introduction.md) 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](https://docs.hub2.io/api-reference/instant-payment/list-aliases.md)

[Référence de l'API HUB2 - Créer un alias](https://docs.hub2.io/api-reference/instant-payment/create-an-alias.md)

[Référence de l'API HUB2 - Supprimer un alias](https://docs.hub2.io/api-reference/instant-payment/delete-an-alias.md)

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.

```bash Curl theme={null}
curl --location --request GET 'https://api.hub2.io/instant-payment/accounts/collection/aliases' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: live'
```

```json theme={null}
[
    {
        "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

```bash Curl theme={null}
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.

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

### Supprimer un alias

```bash Curl theme={null}
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](https://docs.hub2.io/integration/fr/payments/payments_integration.md) : 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](https://docs.hub2.io/api-reference/payments/retrieve-fees.md)

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é.

```bash Curl theme={null}
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](https://docs.hub2.io/api-reference/payments/attempt-a-payment-on-a-paymentintent-object.md)

Effectuez une tentative de paiement sur l'intention de paiement avec le mode de paiement `instant_payment`.

```bash Curl theme={null}
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](https://docs.hub2.io/integration/fr/webhooks/webhooks_overview.md) 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](https://docs.hub2.io/api-reference/payments/retrieve-a-paymentintent-status.md) 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](https://docs.hub2.io/api-reference/transfers/create-transfer.md)

Un transfert suit l'[intégration des transferts](https://docs.hub2.io/integration/fr/transfers/transfers_integration.md). 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`.

```bash Curl theme={null}
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](https://docs.hub2.io/integration/fr/webhooks/webhooks_overview.md), 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](https://docs.hub2.io/integration/fr/payments/payments_failure_causes.md) et des [causes d'échec des transferts](https://docs.hub2.io/integration/fr/transfers/transfers_failure_causes.md).

***

## 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](#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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.