API Operation
HUB2 APIs
The Pay-in & Pay-out APIs developed by Hub2 are different in the way they operate.
Pay-out API
The Pay-out API is used to transfer funds to a third party: the transaction is a debit.
The funds are automatically sent to the recipient without any interaction on their part.
The transfer account must be funded before transfers can be made using the Hub2 API. Before proceeding with the transfer, Hub2 checks whether the merchant has the necessary funds and reserves them until the provider confirms the actual transfer of the funds to the recipient.
Pay-in API
The Pay-in API is used to collect funds from a third party (end customer): the transaction is of the credit type.
Customer interaction is required here, since the customer must, depending on the case :
- confirm the transaction with their provider when they receive a PUSH message or execute a USSD code
- first generate an authentication code with the provider, to be provided at the time of payment.
Once the transaction has been authenticated, the amount of the transaction is credited to the merchant’s collection account.
Accounts
As mentioned above, pay-ins (payments) and pay-outs (transfers) use distinct accounts to operate. All successful pay-ins are credited to the collection account and all successful pay-outs are deducted from the transfer account.
Important : Since transactions may exist in a live
or sandbox
environment, collection and transfer accounts also exist in both environments. As a consequence, a transaction that is created in a sandbox
environment will only affect the sandbox
account and thus, the sandbox
balance. Same for the live
environment.
When a new merchant is created on the Hub2 platform, and since Hub2 simulates the provider’s behavior in the sandbox
environment, the sandbox
transfer account is credited with 100,000 XOF to help the integration process.
Asynchronicity
All transactions created on the Hub2 API, with the exception of transactions created on the synchronous circuit, are processed asynchronously.
Once accepted, the parameters of a transaction request are recorded in a stack of transactions to be processed and are then handled by the other components of the Hub2 infrastructure.
This mode of operation has a number of advantages, not least of which is the ability to respond very quickly to the sender of the HTTP request, thereby reducing the time spent waiting on the merchant platform side, and thus reducing its load.
Circuits
Asynchronous circuit
All transactions initiated in this circuit are processed asynchronously by the Hub2 API. This is the default mode of operation for providers, who do not respond directly to transaction requests but place them in a queue for processing. Transactions are then updated once they have been processed.
The time taken for a provider to process a transaction may vary from one provider to another.
Updating the status of a transaction to a final state at Hub2 therefore depends on the transaction status update at the provider.
Once a transaction has been assigned a final status, it can be updated at Hub2 in one of two ways:
- either by an Instant Payment Notification sent by the provider
- or by regularly querying the status of the transaction by Hub2 at the provider
Synchronous circuit
The asynchronous operating mode of Hub2 is not available with the synchronous circuit. The sender of the HTTP request (the merchant) must wait for a response from Hub2, which will depend on both the provider contacted and the responsiveness of the end customer. This circuit is only available for pay-ins (payments).
Some providers offer the option, either by default or as an additional circuit, of operating synchronously. In this mode of operation, the transaction request is processed immediately when it is called, without being placed in a stack of transactions to be processed later.
The final status of a transaction is obtained directly when the provider responds, although there may be a non-negligible delay between Hub2 sending the request and the provider responding.
The providers for which the synchronous circuit is available are :
- Wave (all countries)
This circuit can only be activated on request to Hub2 Support. Please contact Hub2 Support for more information.