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

# Introduction

> [!NOTE]
>
> * [API reference for instant payment aliases](https://docs.hub2.io/api-reference/instant-payment/list-aliases.md)
> * [API reference for payments](https://docs.hub2.io/api-reference/payments/attempt-a-payment-on-a-paymentintent-object.md)
> * [API reference for transfers](https://docs.hub2.io/api-reference/transfers/create-transfer.md)
> * [OpenAPI specification](https://api.hub2.io/docs-json)

## Overview

Instant payment is the interoperable payment system of the BCEAO. Banks and other regulated payment institutions of the West African Economic and Monetary Union (WAEMU, or UEMOA in French) are connected to it, and funds move between their customers' accounts through a single shared rail, whichever institution holds each account.

On this rail, an account is not identified by a mobile number and an operator, as in mobile money, but by an **alias**. HUB2 connects your collection and transfer accounts to the rail, which gives you two uses:

* **Collect**: a customer pays you from an account held at any participating institution. You attempt an `instant_payment` payment on a payment intent, with the customer's alias and your own collection alias.
* **Send**: you pay a beneficiary who holds an account at any participating institution. You create a transfer with the destination type `instant_payment` and the beneficiary's alias.

Instant payment is available for merchants in Côte d'Ivoire (`CI`) and Senegal (`SN`), in `XOF` only.

## Aliases

An alias is the address under which an account can be reached on the rail. Three types exist:

| Type | Description | Can identify your account | Can identify a counterparty |
| :- | :- | :-: | :-: |
| `SHID` | Identifier of 36 characters generated by the instant payment directory when the alias is registered. | Yes | Yes |
| `MCOD` | Merchant code: 2 to 10 digits. | Yes | Yes |
| `MBNO` | Mobile number in E.164 format, starting with `+` and the country code of a WAEMU country. | No | Yes |

You never send the alias type: HUB2 infers it from the shape of the value and refuses a value that matches none of the three types. HUB2 only checks the shape of an alias. Whether the alias exists is answered by the rail when the payment or the transfer is processed.

Your merchant account holds aliases on two accounts:

* the **collection** account, which receives instant payments;
* the **transfer** account, which pays them out.

When it enables instant payment for you, HUB2 also enrols these accounts on the rail and registers one primary `SHID` alias on each of them:

* An account holds one `SHID` alias. Creating an alias on an account that already has one returns that alias instead of creating a second one.
* The primary alias registered by HUB2 cannot be deleted through the API.

## Enablement

Instant payment is enabled by HUB2 for each merchant. Contact HUB2 Support to request it. Until it is enabled, every instant payment operation is refused with a `403` error (`instant_payment_not_enabled_for_merchant`).

The API key you use must also hold the permissions of the operations it performs: `Api.instant_payment_alias_read`, `Api.instant_payment_alias_create` and `Api.instant_payment_alias_delete` for aliases (see [API keys](https://docs.hub2.io/integration/en/getting_started/api_keys.md)). A key without the required permission receives a `403` error (`missing_permission`).

## Live and sandbox

| Operation | Live | Sandbox |
| :- | :-: | :-: |
| List, create and delete aliases | Yes | No, refused with `403` (`instant_payment_live_only`) |
| Collect an instant payment and get its fees | Yes | Yes, simulated |
| Send an instant payment (transfer) | Yes | Yes, simulated |

In sandbox, no request reaches the rail. The outcome of a payment or a transfer is chosen by the last 8 characters of the counterparty alias (see [Sandbox](https://docs.hub2.io/integration/en/instant_payment/instant_payment_integration.md#sandbox)). The aliases of your merchant account are still checked in sandbox, so they must be registered beforehand in live mode.

## Merchant groups

When you operate [submerchants](https://docs.hub2.io/integration/en/submerchants/submerchants_introduction.md), the instant payment aliases belong to the parent merchant (the group owner) and are managed by its submerchants:

* Call the instant payment endpoints, the payment endpoints and the transfer endpoints with the submerchant `MerchantId`. A parent merchant that calls them with its own `MerchantId` receives a `403` error (`group_owner_transaction_forbidden`), except to list its aliases.
* On a collection, the `payeeAlias` must be a collection alias of the parent merchant, because the funds are credited to the parent merchant's collection account.
* On a transfer, the account debited is the parent merchant's transfer account.

## Next step

> **[Instant payment integration guide](https://docs.hub2.io/integration/en/instant_payment/instant_payment_integration.md)**


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