Getting started

The HelloCash USSDAPI allows to smoothly integrate payment features into your businesses App providing for an easy free payment method to your customers. As the API is USSD-based no internet connection is needed allowing usage anytime and anywhere but in the most remote areas. All you need to integrate the API into your business is a HelloCash account and a little bit of App development skill.

Usage

The HelloCash USSDAPI is somewhat unusual in the sense that all interactions between your App and HelloCash are 'single-shot' 'fire-and-forget' affairs; That is, your App will send a command string to HelloCash and whatever the reply is will be shown by the phone's USSD subsystem to the user, but can NOT be intercepted by an App. For this reason the USSDAPI is modelled such that a command string send to HelloCash will contain all required information, to be gathered by the App, so that the only thing that typically remains to be done, by the person using the App, is to authorize the operation by giving a PIN.

The App should send the command string to HelloCash simply by dialing the USSD shortcode of a HelloCash partner bank. Depending on the partner bank the number to dial is

Lion International Bank *803*<command string>#
Cooperative Bank of Oromia *983*<command string>#
Somali Micro Finance Institute *838*<command string>#
Wegagen Bank *777*<command string>#
Sandbox Bank (Lucy) *912*<014><command string>#


The <command string> to send is a single string built as follows

<LEN><apikey><LEN><appid><LEN><majorversion><LEN><operation code><LEN><operation arguments>

where LEN is each time a two digit field containing the length of the next field and

  • apikey is your HelloCash USSD Api Key, or alternatively your HelloCash account number (also known as 'username').
  • appid is a designator to be defined by the App builder for the app or its version. It can be used for such things as blocking a buggy version of an App or for gathering Business Intelligence.
  • Although each operation has its own version number the whole set of operations also has a major version. This versioning can be used to signal Apps that use a major version that predates an important update of the API, like a new operation being added; In such a case it might happen (rarely) that although the App uses operations that by themseves are still supported or even the latest version the whole set is no longer consistent because it lacks the new operation. At time of writing, November 2017, this version is 11.
  • The operation codes are listed in below table; 100 for Transfer, 280 for Pay etc. Note that there might be operations that are possible through more than one operation code. These might then vary in arguments to provide or exact working or version (deprecated vs current).
  • The operation arguments are listed in below table. Multiple arguments are concatenated following the same scheme as for the commandstring itself. So {<destination>,<amount>} in the table below would translate to for example 100912341234045000. Alphanumeric arguments are supported but encoding is somewhat more complex: Each symbol is changed to 'its ascii code - 32' (32 because its he lowest printable ascii code) and the resulting sequence prefixed (as usual) with its length AND with an extra prefix 99. So a string 'e2-e4' would be encoded as '99107318137320'
NB: During development or for a quick test you could also concatenate using asterisk instead of <LEN>. In that case you should however expect the reply to take a few seconds longer because of extra messaging overhead. And alphanumeric arguments are not supported.

The available <operation code> and their <operation arguments> are given in below table. Note that some operations are only available to members of a specific type.


Operations

Description Arguments Result Remarks
Transfer 100 { <destination>,<amount> }
Available to: Regular,Business,Merchant
Transfer of funds to a regular member or new member destination – phone of recipient amount – amount to transfer 1. Request for PIN
2. Transfer		 Only allows for transfer to regular member or to a non-member. In the latter case a confirmation will be asked for before the request for PIN.
Example (using *):
Example: 		*912*4*1234567*171*11*100*0912345678*50
*912*014071234567031710211031001009123456780250
Transfer 120 { <destination>,<amount>,<description> }
Available to: Regular,Business,Merchant
Transfer of funds to a regular member or new member.Same as operation '100' but with a mandatory description destination – phone of recipient amount – amount to transfer description – description of what the transfer is for 1. Request for PIN
2. Transfer		 Only allows for transfer to regular member or to a non-member. In the latter case a confirmation will be asked for before the request for PIN.
Withdraw 140 { <destination>,<amount> }
Available to: Regular,Business,Merchant,Agent
Withdrawal of funds at agent or teller by means of a transfer to that agent or teller destination – id or phone of agent or teller
amount – amount to withdraw		 1. Request for PIN
2. Transfer
Pay reference 240 { <reference> }
Pays an outstanding reference reference – reference code to pay 1. Request for PIN
2. Transfer
Pay 180 { <merchant>,<amount> }
Available to: Regular
Make an over-the-counter payment to a merchant merchant – id or phone of merchant
amount – amount to pay		 1. Request for PIN
2. Transfer

Paybill 218
Available to: Regular
Show most recent outstanding bill
1. Request for PIN
2. Transfer		 If there is no outstanding bill or no recent outstanding bill the customer will be informed to check the Bill menu
Paybill 220
Available to: Regular
Show a (possibly empty) list of outstanding bills
1. Request to select bill from a list or, alternatively, provide a bill reference
2. Request for PIN
3. Transfer
Request Payment 240 { <destination>,<amount> }
Available to: Business,Merchant
Request payment of member for service or product destination – phone of withdrawer amount – amount to withdraw 1. Instruction to inform the withdrawer of the next step
Pay with description 320 { <merchant>,<amount>,<description> }
Make a over-the-counter payment to a merchant, along with a payment description merchant – id or phone of merchant
amount – amount to pay
description – short text string describing the item or service paid for
 1. Request for PIN
2. Transfer		 The payment description given will be shown in payment notification SMS and transfer reports
Pay with description 360 { <merchant>,<amount>,<productname> }
Make a over-the-counter payment to a merchant, along with a payment description merchant – id or phone of merchant
amount – amount to pay
productname – short name of the product to decribe. If productname=0 the default productname is used. This might either be the general default (‘description’) or the merchant specific default as set in hellocash.
 1. Request to “Enter the <productname> tp pay for”
2. Request for PIN
3. Transfer		 The payment description given will be shown in payment notification SMS and transfer reports
Deposit 300 { <destination>,<amount> }
Available to: Agent
Transfer of funds as part of deposit by a customer. destination – phone of recipient amount – amount deposited 1. Request for PIN
2. Transfer
Request Withdrawal 320 { <destination>,<amount> }
Available to: Agent
Request payment of member wanting to make a withdrawal. destination – phone of withdrawer amount – amount to withdraw 1. Instruction to inform the withdrawer of the next step
Pay Bill for Customer 340 { <reference> | <business><amount> }
Available to: Agent
Pay an invoice or to Business on behalf of a customer. reference – reference number of the invoice
business – id or phone of business
amount – amount to withdraw
 1. Request for PIN
2. Transfer
Transfer from/to own Bank account 400 { <direction><amount> }
Available to: Regular,Business,Merchant,Agent
Transfer to/from Bank account. direction –
1: from bank to HelloCash
2: from HelloCash to bank
amount – amount to transfer
 1. Request for PIN
2. Transfer		 The member should have a CBS account linked to their HC account. If they do not then an message to that effect will be shown
Link accounts 620 { <bank account><branch code><phone> }
Available to: Teller
Link bank account with HelloCash account. bank account – bank account of HelloCash customer
branch code – branch code of bank account, or '0' for none
phone – phone number of HC account
 1. Request for PIN
2. Linking of accounts
My Account 700 { <3><language> }
Available to: All
3:Change Language language –
1: Amarinya
2: Amarinya-Geez
3: Oromiffa
4: Tigrinya
5: Tigrinya-Geez
6: Af-Soomaali
7: English 		3: Message informing of language update If the language chosen is not supported then language is set to English
Airtime 800 { <1><denomination> | <2><destination><denomination> }
Available to: Regular,Business,Merchant,Agent
Airtime topup of own phone or of phone given destination – phone to top up
denomination -
1: 5 Birr
2: 10 Birr
3: 15 Birr
4: 25 Birr
5: 50 Birr
6: 100 Birr
7: 250 Birr
8: 500 Birr
 1. Request for PIN
2. Transfer (and consequently airtime topup)		 The chosen denomination might be temporarily out of stock.
Remittance 840 { <1><denomination> | <2><destination><denomination> }
Available to: Regular
Request Remittance to be send to account remittance provider -
1: Money Gram
TODO 		Message to await SMS

Get an API Key

API Keys are not yet available. Please use your account number (also known as 'username') for now.