# Use Cases

Select the product of interest and the use case.

Follow the APIs as shown. Execute in sequential order.

Request to Pay service is used for requesting a payment from a customer (Payer). This can be used by e.g. an online web shop to request a payment for a customer. The customer is requested to approve the transaction on the customer client.

1. Customer (Payer) have selected product(s) in the merchant web shop and decided to check out. Customer select to pay with Mobile Money.
2. The provider system collects the account information for the customer e.g. mobile number and calculate the total amount of the products.
3. The provider system sends a request to pay (POST /requesttopay) operation to Wallet Platform. This request includes the amount and customer (Payer) account holder number.
4. Wallet Platform will respond with HTTP 202 Accepted to the provider system
5. Provider shall inform the customer that a payment needs to be approved, by giving information on the merchant web page. For example, the merchant could show information that payment is being processed and that customer needs to approve using the own client, e.g. USSD, mobile app.
6. Wallet Platform will process the request so that the customer can approve the payment. The request to pay will be in PENDING state until the customer have approved/Rejected the payment.
7. The Customer (Payer) will use his/her own client to review the payment. Customer can approve or reject the payment.
8. Wallet platform will transfer the funds if the customer approves the payment. Status of the payment is updated to SUCCESSFUL or FAILED.
9. If a callback URL was provided in the POST /requesttopay then a callback will be sent once the request to pay have reached a final state (SUCCESSFUL, FAILED). Note the callback will only be sent once. There is no retry.
10. GET request can be used for validating the status of the transaction. GET is used if the partner system has not requested a callback by providing a callback URL or if the callback was not received.

# Pre-Approval

Pre-approval is used to setup an auto debit towards a customer. The Partner can request a pre-approval from the customer. Once the customer has approved then the partner can debit the customer account without authorization from the customer.

The call flow for setting up a pre-approval is like the request to pay use case. The following picture describes the sequence for pre-approval.

1. The Provider sends a POST /preapproval request to Wallet platform.
2. Provider shall inform the customer that pre-approval needs to be approved.
3. Customer (Payer) will use the own client to view the pre-approval request. Customer can approve or reject the request.
4. Callback will be sent if a callback URL was provided in the POST request. The callback is sent when the request has reach a final state (Successful, Failed).
5. The Provider can use the GET request to validate the status of the pre-approval.

# Transfer

Transfer is used for transferring money from the provider account to a customer.

The below sequence gives an overview of the flow of the transfer use case.

1. The Provider sends a POST /transfer request to Wallet platform.
2. Wallet platform will directly respond to indicate that the request is received and will be processed.
3. Wallet platform will authorize the request to ensure that the transfer is allowed. The funds will be transferred from the provider account to the Payee account provided in the transfer request.
4. Callback will be sent if a callback URL was provided in the POST request. The callback is sent when the request has reach a final state (SUCCESSFUL, FAILED).
5. The Provider can use the GET request to validate the status of the transfer.

# Validate Account Holder

Validate account holder can be used to do a validation if a customer is active and able to receive funds. The use case will only validate that the customer is available and active. It does not validate that a specific amount can be received.

The sequence for the validate account holder is described below.

1. The Partner can send a GET /accountholder request to validate is a customer is active. The Partner provides the id of that customer as part of the URL
2. Wallet platform will respond with HTTP 200 if the account holder is active.

# Get Balance

Get balance request is used to check the balance on the default account connected to the API User. The following is the sequence flow for get balance use case.

1. The partner will send a GET /account/balance request
2. Wallet platform will respond with the available balance on the API user account.

# Delivery Notification

This service is intended to provide an additional notification to a customer after the completion of a successful financial transaction, by SMS or by email.

Merchants and Service Providers using PGW(Partner gateway is an application responsible for connecting API manager to different Wallet instances across all the Opcos) to interact with the Wallet Platform have the capability to send a notification to their customers after completed transaction.

Additional information is sent via SMS and is free text that may contain information that a partner wants to communicate for example, delivery notification reference number, a lottery number, a booking number, ticket id etc.

The channel used to send the notification will be determined based on what identity was used to initiate original transaction/payment.

The time window during which partner can use additional notification is configured in Partner Gateway.

# Validate Consumer Identity

The Validate Consumer Identity use case (KYC as a service) enables a partner to retrieve (limited) customer KYC information with their consent. Upon request by the service provider, the customer will authorize, authenticate and provide consent to get detailed information.

The Partner will receive a short-lived token to fetch detailed information of the customer from the wallet platform

The basic information that can be retrieved by default is Profile: Name , Gender, Date of birth, locale etc.

API: GetBasicUserinfo can be used to either validate for example, Consumer's age or name.

The use case will return limited information about the Consumer that can be used to pre-populate fields, validate the Consumer's age or use it for remittance or sanctions screening purposes.

# Get consumer information with consent

This use case (Authentication as a Service) is used to validate/authenticate customer information, by way of a service provider sending a request to the wallet platform, with or without customer consent. The consumer will authenticate via authorization service, and if required, the consumer will be required to provide consent. The scope is to validate or retrieve customer information.

This use case will also enable a partner to obtain consent, or digitally accept terms and conditions. This can be seen as a “digital signature” (where a partner requires this).

A partner may also be able to fetch limited user info without requiring customer consent. This will also enable partners to record and review that a customer has accepted the terms of a contract (amongst other use cases).

This will be used as a base when any token based “as a service” is required.

API: bc-authorize.

It provides the Partner with the ability to fetch detailed information about a Consumer, after the Consumer has given the Partner consent for the retrieval of said information:

Token based API authorization

Token based API authorization is required to support consent management for different services. The Partner will request consent from the consumer for certain financial and non-financial transactions, and this will remain valid until the account holder revokes the consent.

The functionalities that can be enhanced by using consent will be

1.Transfer

2.Payment

3.Merchant payment

4.Transfer to any bank account

For partners this will enable them to view the status of the transactions for which consent was give using the related parameters.For account holders, they can revoke the consent from any service at their will. Business benefit of consent can be Improved customer experience. Consent can be configured for a specific time and there will be no need to get consent for each transaction.Providing better control on what services are being allowed by the account holder for consent etc.

# Transfer with consumer consent

Gives the partner the ability to transfer money on behalf of a consumer, after the consumer has given the partner consent to do so.

# Merchant payment with consumer consent

Gives the Merchant System (partner) the possibility to perform a merchant payment on behalf of a consumer to any receiver. This will only be possible after the Consumer has given the Merchant System (partner) a consent for doing so.

# Payment with consumer consent

Gives the Merchant System (partner) the possibility to perform a payment on behalf of a consumer to any receiver. This will only be possible after the Consumer has given the Merchant System (partner) a consent for doing so.

Payment with consent will be similar to Merchant Payment. For more details, Please refer above section- "Merchant Payment with Consumer Consent".

# Bank transfer with consumer consent

Gives the Merchant System (partner) the possibility to perform a Bank Transfer on behalf of a consumer to any receiver. This will only be possible after the Consumer has given the Merchant System (partner) a consent for doing so.

Bank transfer with consent will be similar to Transfer with Consent. For more details, Please refer above section- "Transfer with Consumer Consent".

#Request to Withdraw - CASHOUT

Request to Withdraw service is used for requesting a payment from a customer. This can be used for example, an e-commerce website requesting a payment from a customer. The customer is requested to approve the transaction on the customer client.

The below sequence describes how the requesttowithdraw service is used.

1. Agent (Partner) selects to request a withdrawal from a Consumer, specifies the MSISDN and the amount to withdraw.

2. The Partner system collects the account information for the Consumer such as mobile number and the amount to withdraw.

3. The Partner System sends a request to withdraw, POST /v1_0/requesttowithdraw (deprecated) or POST /v2_0/requesttowithdraw, to Wallet Platform. This request includes the amount and Consumer (Payer) account holder number.

4. Partner Gateway checks if the Agent (partner) is authorized to perform the request to withdraw operation.

5. Partner Gateway checks if the Agent (partner) has a valid access token and not expired token. If access token has expired, Partner system needs to create a new access token

6. Since request to withdraw operation is asynchronous, Partner Gateway creates the transaction and responds with HTTP 202 Accepted.

7. Partner Gateway sends initiatetransfer request on behalf of the Agent towards the Wallet Platform.

8. Wallet Platform checks if the Partner Gateway has authorization to perform the initiatetransfer request on behalf of the Agent.

9. Partner system informs the Consumer that a withdrawal (cash-out) needs to be approved.

10. Wallet Platform will process the request so that the consumer can approve the payment. The request to withdraw will be in PENDING state until the consumer have approved/rejected the withdrawal.

11. The Consumer (Payer) uses own client to review the request to withdraw. Consumer can approve or reject the request to withdraw.

12. Wallet platform transfers the funds if the consumer approves the payment. Status of the payment is updated to SUCCESSFUL or FAILED.

13. If a callback URL was provided in the request to pay then the callback PUT or POST (depending on version used in the request) will be sent once the request to pay have reached a final state (SUCCESSFUL, FAILED). Note the callback will only be sent once. There is no retry.

Alternatively the request GET /requesttowithdraw/{referenceId} can be used for validating the status of the transaction. The request should be used if the partner system has not requested a callback (no callback URL was provided), or if the callback was not received

14. Consumer receives the result. Notification will be sent towards consumer and

#Deposit - CASHIN

Transfer is used for transferring money from the provider account to a customer.

The below sequence gives an overview of the flow of the transfer use case.

1. Agent (Partner) selects to perform a deposit (cash-in) to a Consumer, specifies the MSISDN and the amount to deposit.

2. The Partner system collects the account information for the Consumer such as mobile number and the amount to deposit.

3. Partner system sends a POST /v1_0/deposit (deprecated) or POST /v2_0/deposit

4. Partner Gateway checks if the Agent (partner) is authorized to perform the deposit operation.

5. Partner Gateway checks if the Agent’s access token and not expired token. If access token has expired, Partner system needs to create a new access token

6. Since deposit operation is asynchronous, Partner Gateway creates the transaction and responds with HTTP 202 Accepted.

7. Partner Gateway sends a cashin request on behalf of the Agent towards the Wallet Platform.

8. Wallet Platform checks if the Partner Gateway has authorization to perform the cashin request on behalf of the Merchant.

9. Wallet Platform will process the request and transfer the funds. Status of the transfer is updated to SUCCESSFUL or FAILED.

10. If a callback URL was provided in the transfer request then the callback PUT or POST (depending on version used to create the transaction) will be sent once the request to pay have reached a final state (SUCCESSFUL, FAILED). Note the callback will only be sent once. There is no retry.

Alternatively the request GET /deposit/{referenceid} can be used for validating the status of the transaction. The request should be used if the partner system has not requested a callback (no callback URL was provided), or if the callback was not received

11. Agent receives the result. Notification will be sent towards consumer and agent over the configured notification channel.

#REFUND

Refund is used for transferring money from the provider account to a customer incase a refund needs to be processed.

The below sequence gives an overview of the flow of the refund use case.

1. Agent (Partner) selects to perform a deposit (cash-in) to a Consumer, specifies the MSISDN and the amount to deposit.

2. The Partner system collects the account information for the Consumer such as mobile number and the amount to deposit.

3. Partner system sends a POST /v1_0/deposit (deprecated) or POST /v2_0/deposit

4. Partner Gateway checks if the Agent (partner) is authorized to perform the deposit operation.

5. Partner Gateway checks if the Agent’s access token and not expired token. If access token has expired, Partner system needs to create a new access token

6. Since deposit operation is asynchronous, Partner Gateway creates the transaction and responds with HTTP 202 Accepted.

7. Partner Gateway sends a cashin request on behalf of the Agent towards the Wallet Platform.

8. Wallet Platform checks if the Partner Gateway has authorization to perform the cashin request on behalf of the Merchant.

9. Wallet Platform will process the request and transfer the funds. Status of the transfer is updated to SUCCESSFUL or FAILED.

10. If a callback URL was provided in the transfer request then the callback PUT or POST (depending on version used to create the transaction) will be sent once the request to pay have reached a final state (SUCCESSFUL, FAILED). Note the callback will only be sent once. There is no retry.

Alternatively the request GET /deposit/{referenceid} can be used for validating the status of the transaction. The request should be used if the partner system has not requested a callback (no callback URL was provided), or if the callback was not received

11. Agent receives the result. Notification will be sent towards consumer and agent over the configured notification channel.

#Create Invoice

A merchant may use this to create an invoice that can be paid by an intended payer via any channel at a later stage.

The below sequence gives an overview of the flow of the Invoice Creation API.

1. The Merchant System sends a created invoice request POST /v2_0/invoice, that contains invoice details as according to the interface specification.

2. Partner Gateway checks if the Merchant (partner) is authorized to perform the operation.

3. Partner Gateway checks if the Merchant’s access token and not expired token. If access token has expired, Merchant system needs to create a new access token.

4. Since operations are asynchronous, the Partner Gateway creates the transaction and responds with HTTP 202 Accepted.

5. Partner Gateway sends the request on behalf of the Merchant towards the Wallet Platform.

6. Wallet Platform checks if the Partner Gateway has authorization to perform the request on behalf of the Merchant.

7. Wallet Platform processes the request. Status of the transaction is updated to SUCCESSFUL or FAILED.

8. If a callback URL was provided in the request, then the callback is sent once the transaction have reached a final state (SUCCESSFUL, FAILED).

9. Alternatively the request GET /v2_0/invoice/{referenceid} can be used for validating the status of the transaction. The request should be used if the partner system has not requested a callback (no callback URL was provided), or if the callback was not received, Get Transaction Status.

10. Merchant receives the result. Notification will be sent towards consumer and merchant over the configured notification channel.

#Cancel Invoice

A merchant may use this to cancel an invoice that can be paid by an intended payer via any channel at a later stage.

The below sequence gives an overview of the flow of the Invoice Cancel API

1. The Merchant System sends a cancel invoice request DELETE /v2_0/invoice/{ReferenceId}, that contains invoice details as according to the interface specification.

2. Partner Gateway checks if the Merchant (partner) is authorized to perform the operation.

3. Partner Gateway checks if the Merchant’s access token and not expired token. If access token has expired, Merchant system needs to create a new access token.

4. Since operations are asynchronous, the Partner Gateway creates the transaction and responds with HTTP 202 Accepted.

5. Partner Gateway sends the request on behalf of the Merchant towards the Wallet Platform.

6. Wallet Platform checks if the Partner Gateway has authorization to perform the request on behalf of the Merchant.

7. Wallet Platform processes the request. Status of the transaction is updated to SUCCESSFUL or FAILED.

8. If a callback URL was provided in the request, then the callback is sent once the transaction have reached a final state (SUCCESSFUL, FAILED).

9. Alternatively the request GET /v2_0/invoice/{referenceid} can be used for validating the status of the transaction. The request should be used if the partner system has not requested a callback (no callback URL was provided), or if the callback was not received.

#Create Voucher or Cash Voucher

Create voucher is used for transferring funds from the Merchant (Partner) account to an unregistered person. This unregistered user or recipient may use the voucher token and secret or OTP to redeem the money at another agent. The agent may also help an unregistered sender to transfer money to another unregistered recipient by sending a cash voucher. To do so, the agent needs to get details about the unregistered sender and get cash from the sender so that the agent can provide those details in the request and then transfer the fund from the agent’s mobile money account to the system voucher account until the receiver redeems the voucher.

The below sequence gives an overview of the flow of the Create Voucher or Cash Voucher

1. The Merchant System sends a create voucher request POST /v2_0/voucher, that contains recipient details and optional sender details.

2. Partner Gateway checks if the Merchant (partner) is authorized to perform the operation.

3. Partner Gateway checks if the Merchant’s access token and not expired token. If access token has expired, Merchant system needs to create a new access token.

4. Since operations are asynchronous, the Partner Gateway creates the transaction and responds with HTTP 202 Accepted.

5. Partner Gateway sends the request on behalf of the Merchant towards the Wallet Platform.

6. Wallet Platform checks if the Partner Gateway has authorization to perform the request on behalf of the Merchant.

7. Wallet Platform processes the request. Status of the transaction is updated to SUCCESSFUL or FAILED.

8. If a callback URL was provided in the request, then the callback is sent once the transaction have reached a final state (SUCCESSFUL, FAILED).

9. Alternatively the request GET /v2_0/voucher/{referenceid} can be used for validating the status of the transaction. The request should be used if the partner system has not requested a callback (no callback URL was provided), or if the callback was not received.

10. Merchant receives the result. Notification will be sent towards consumer and merchant over the configured notification channel.

#Redeem or Cancel Voucher

Redeem voucher is used by the merchant when an unregistered user wants to redeem a voucher, that is, get the cash that was sent as part of the create voucher use case. Cancel Voucher is used by the sender of a cash voucher to get money back in case the sender changes his mind.

The below sequence gives an overview of the flow of the Redeem or Cancel Voucher

1. The Merchant System sends redeem/cancel voucher request depending on the use case, POST /v2_0/voucher/{voucherToken}/redeem or DELETE /v2_0/voucher/{voucherToken}, that contains the necessary details. Depending on the target system configuration, an one time password (OTP) might be needed to successfully cancel or redeem a voucher, refer to Section 4.29 for details on how to generate OTP prior to redeeming or cancelling the voucher.

2. Partner Gateway checks if the Merchant (partner) is authorized to perform the operation.

3. Partner Gateway checks if the Merchant’s access token and not expired token. If access token has expired, Merchant system needs to create a new access token.

4. Since operations are asynchronous, the Partner Gateway creates the transaction and responds with HTTP 202 Accepted.

5. Partner Gateway sends the request on behalf of the Merchant towards the Wallet Platform.

6. Wallet Platform checks if the Partner Gateway has authorization to perform the request on behalf of the Merchant.

7. Wallet Platform processes the request. Status of the transaction is updated to SUCCESSFUL or FAILED.

8. If a callback URL was provided in the request, then the callback is sent once the transaction have reached a final state (SUCCESSFUL, FAILED).

9. Alternatively the request GET /v2_0/voucher/{referenceid} can be used for validating the status of the transaction. The request should be used if the partner system has not requested a callback (no callback URL was provided), or if the callback was not received.

10. Merchant receives the result. Notification will be sent towards consumer and merchant over the configured notification channel.

#Generate Voucher OTP

This may be used, in case the target system demands it, to generate a one-time password (OTP) that is needed to redeem a voucher or to redeem/cancel a cash voucher.

The below sequence gives an overview of the flow of OTP Generation of Voucher

1. The Merchant System initiates a generate voucher OTP request using GET /voucher/{vouchertoken}/OTP with a body parameter that indicates the use case (redeem or cancel cash voucher).

2. Partner Gateway checks if the Merchant’s access token and not expired token. If access token has expired, Merchant system needs to create a new access token.

3. Wallet platform responds with a status indicating that an OTP has been generated.

4. Merchant system receives the result. Notification containing the OTP is sent towards the appropriate notification receiver, depend on use case, over the configured notification channel.

#Create preApproval

Making it possible to request for pre-approval which will enable future debit request, without having to ask for approval for each debit request.

The below sequence gives an overview of the flow of Creating a PreApproval

1. The Merchant System sends a pre-approval request POST /v2_0/preapproval, that contains pre-approval details as according to the interface specification.

2. Partner Gateway checks if the Merchant (partner) is authorized to perform the operation.

3. Partner Gateway checks if the Merchant’s access token and not expired token. If access token has expired, Merchant system needs to create a new access token.

4. Since operations are asynchronous, the Partner Gateway creates the transaction and responds with HTTP 202 Accepted.

5. Partner Gateway sends the request on behalf of the Merchant towards the Wallet Platform.

6. Wallet Platform checks if the Partner Gateway has authorization to perform the pre-approval request on behalf of the Merchant. Wallet platform responds back with a pending status as the pre-approval request is asynchronous.

7. Wallet Platform processes the pre-approval request. If pre-approval created successfully, it sends the request to the consumer for approval or decline. Consumer approves or declines the pre-approval and Partner Gateway polls EWP for the pre-approval status and inform the merchant, via callback, when the status of the pre-approval has been updated to SUCCESSFUL/APPROVED or FAILED/REJECTED.

#Service Provider Payment

Making it possible to perform payments via the partner gateway. This may be used to pay for external bills or to perform air-time top-ups.

The below sequence gives an overview of the flow of Creating a Payment Request to SP

1. The Merchant System sends a payment request POST /v2_0/payment, that contains payment details as according to the interface specification.

2. Partner Gateway checks if the Merchant (partner) is authorized to perform the operation.

3. Partner Gateway checks if the Merchant’s access token and not expired token. If access token has expired, Merchant system needs to create a new access token.

4. Since operations are asynchronous, the Partner Gateway creates the transaction and responds with HTTP 202 Accepted.

5. Partner Gateway sends the request on behalf of the Merchant towards the Wallet Platform.

6. Wallet Platform checks if the Partner Gateway has authorization to perform the payment request on behalf of the Merchant. Wallet platform responds back with a pending status as the payment request is asynchronous.

7. Wallet Platform will process the payment request and send the request to the service provider system for confirmation. Service provider responds back with the status of the payment. Status of the transaction is updated to PENDING.

8. If a callback URL was provided in the payment request then the callback is sent once the transaction have reached a final state (SUCCESSFUL, FAILED).

9. Alternatively the request GET /v2_0/payment/{X-Reference-Id} can be used for validating the status of the transaction. The request should be used if the partner system has not requested a callback (no callback URL was provided), or if the callback was not received, see Partner Gateway Get Balance.

10. Merchant receives the result. Notification will be sent towards consumer and merchant over the configured notification channel.