cic-docs/spec/007_eMoney_integration.md

Incoming Sarafu

When users exchange CIC <> National Currency we have to manually send them Mpesa or CIC. We would like to automate this.

Solution

Configure - using our own system AfricasTalking API to automatically send Sarafu / Mpesa based on rules:

Variables

• blockchain_CIC_Supply = the total supply of the CIC on the blockchain
• blockchain_CIC_reserve = the total reserve (xDAI) of the CIC on the blockchain
• trr = the connector weight on blockchain converter between supply and reserve
• total_CIC_sent = the total amount of CIC that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing
• total_CIC_Reserve_Sent = the total amount of Reserve that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing
• total_CIC_recieved = the total amount of CIC that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing
• total_CIC_Reserve_recieved = the total amount of Reserve that has been sent to users from our Float account - this needs to be updated for each conversion and when clearing
• CIC_supply_b: blockchain_CIC_Supply - total_CIC_sent + total_CIC_recieved = this simulates/tracks the changes to the blockchain
• CIC_reserve_b: blockchain_CIC_reserve - total_CIC_Reserve_Sent + total_CIC_Reserve_recieved = this simulates/tracks the changes to the blockchain
• CIC_excahnge_amount = the amount of CIC they user has sent to exhange
• Mpesa_excahnge_amount = the amount of MPesa the user has sent to exhange
• Rate: USD -> KSH
• Rate: KSH -> USD
• The account to which CIC are sent should be a Agent account
• The cash-out rules for a chama (minimum and time limit)
• Alert balance levels
• Fees: Sarafu to Mpesa FeeCC2M = 2%
• Fees: Sarafu to Mpesa FeeM2CC = 2%

Incoming Sarafu Rules - MPESA out

• white list The chama (group accounts only but eventually anyone) must only be able to cash out - using the exchange option to an Agent account
• amount The max cash out is the minimum of (30,000 Sarafu, half their balance, their total amount of outward trade volume to other users (standard transactions)
• time They can only cash out once per month
• mpesa given The amount of Mpesa given should be calculated as follows:

The Reserve (xDAI) pulled out

reserveOut_xDAI = CIC_reserve_b * (Math.pow(1 + (-1 * CIC_excahnge_amount) / CIC_supply_b, 1 / trr) - 1) --> this should be calculated as it is done on contract

• Mpesa_out = reserveOut_xDAI USD => KSH rate
• Mpesa_given = Mpesa_out - Mpesa_out*S22M (fee) this is the amount of Mpesa sent to the user
• Update CIC variables on database:
  • total_CIC_recieved+= CIC_excahnge_amount
  • total_CIC_Reserve_Sent+= reserveOut_xDAI

Outgoing Sarafu Rules - MPESA In

• white list Only users sending via paybill receive Sarafu. Non users receive a invitation to join Sarafu sms (alert to admins there was a donation).
• amount The max sarafu out is 20,000 Sarafu per user, KYC_limit max, supply_max
• time No limit
• CIC given The amount of CIC given should be calculated as follows:
• reserveIn_xDAI = Mpesa_excahnge_amount KSH => USD rate

The amount cashed in = cash_in_amount

CIC_Created = CIC_supply_b * (Math.pow(1 + reserveIn_xDAI / CIC_reserve_b, trr) - 1) --> this should be calculated as it is done on contract

• CIC_given = CIC_Created - CIC_created*FeeM2CC ()
• Simulate as if done on blockchain .... new_cic_supply_b = cic_supply_b + CIC_given
• Simulate as if done on blockchain .... new_total_reserve_b = total_reserve_b + cash_in_amount
• Update CIC variables on database:
  • total_CIC_sent+= CIC_excahnge_amount
  • total_CIC_Reserve_recieved+= reserveIn_xDAI

Security

• Balance alerts: On both Mpesa and CIC balances: The paybill from which Sarafu is sent needs to send a sms and email alert when low
• Failure alerts: If the API session fails an sms and email alert should be sent
• Reject on not enough Mpesa balance: If there is not enough Mpesa (on incoming Sarafu) the transaction should be rejected and an email sent to admin along with a SMS to admin and user (Sarafu should not be taken from user). (message should be visible also on mgmt platform txn view and user view and admin view).
• Reject on not enough Sarafu balance: If there is not enough Sarafu (on incoming Mpesa) the transaction should be rejected and an email sent to admin along with a SMS to admin and user (Mpesa should not be taken from user). (message should be visible also on mgmt platform txn view and user view and admin view).