Skip to main content

​
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: 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). A key without the required permission receives a 403 error (missing_permission).

​
Live and sandbox

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). 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, 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