react-native-opanet-http-over-ussd

1. Enable Mobile Applications (Android) to securely send Http Request real-time without internet access.
2. Receive mobile payments real-time without a centralized payment gateway, making payments faster, more secure and convenient, with lower transaction charges.

Poor internet service in rural areas (emerging markets) makes IOS & Android Apps not reliable. USSD Menus provides a solution however, USSD menus are unable to leverage the rich user experience that Smart phones offer.

Opanet Android SDKs enable developers to leverage the connectivity of USSD and the rich user experience of Smart phones.

1. Installation

npm install react-native-opanet-http-over-ussd

2. Link native-module

Add the following to settings.gradle (Android folder)

include ':app',':react-native-opanet-http-over-ussd'

Add the following to build.gradle (android/app folder)

implementation("androidx.localbroadcastmanager:localbroadcastmanager:1.0.0")
implementation fileTree(dir: "../../node_modules/react-native-opanet-http-over-ussd/android/build/outputs/aar", include: ["*.aar"])

Add the OpanetHttpOverUssdPackage to PackageList in MainApplication (android/app/src/main folder)

// ... Java ...
import com.opanethttpoverussd.OpanetHttpOverUssdPackage;
//
Listpackages = new PackageList(this).getPackages();
packages.add(new OpanetHttpOverUssdPackage());

// ... Kotlin ...
import com.opanethttpoverussd.OpanetHttpOverUssdPackage
//
PackageList(this).packages.apply {
add(OpanetHttpOverUssdPackage())
}

3. Configure AndroidManifest

Add the following permissions to AndroidManifest (android/app/src/main folder)

<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.CALL_PHONE" />
<uses-permission android:name="android.permission.ACTION_MANAGE_OVERLAY_PERMISSION" />

Add the following to AndroidManifest (android/app/src/main folder) under application

<service
android:name="com.opanethttpoverussd.USSDService"
android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE"
android:exported="false">
<intent-filter>
<action android:name="android.accessibilityservice.AccessibilityService" ></action>
</intent-filter>
<meta-data
android:name="android.accessibilityservice"
android:resource="@xml/ussd_service" />
</service>
<service
android:name="com.opanethttpoverussd.OverlayShowingService"
android:exported="false" ></service>
<service
android:name="com.opanethttpoverussd.SplashLoadingService"
android:exported="false" ></service>
<activity
android:name="com.opanethttpoverussd.DialerActivity"
android:launchMode="standard">
</activity>

4. Http Usage

import { http, Pay, PendingCallbacks } from 'react-native-opanet-http-over-ussd';

// ...

http(
"*000#",
{
type:"POST",
url:"https://yourdomain/api",
data:{ myData:"This is my data"},
headers: { "custome-header":"somevalue" }
},
x=>{console.log(x)},
x=>{console.log(x.message)}
);

opanet.send(ussdCode, httpRequest, successHandler, failureHandler) Send HttpRequest.

ussdCode Type: STRING. Ussd code provided by ussd-gateway. HttpRequest Type: OBJECT. HttpRequest Object.

successHandler Type: Function(response). A function to execute when a request is successful. Response is JSON failureHandler Type: Function(response). A function to execute when a request fails.

Limitations

Support only "application/json" content type.
Timeout is 120 seconds
Throughput is 100 bytes/second

5. Mobile Payment Usage

import { http, Pay, PendingCallbacks } from 'react-native-opanet-http-over-ussd';

// ...

<Pay
ussdCode="*000#"
recipient="233241****89"
amount="1.00"
reference="PO012031"
thirdPartyTransactionId="1234567890"
onPaymentSuccess={(x) =>{console.log(x.transactionId)}}
onPaymentFailure={(x)=>{console.log(x.message)}}
onCallbackSuccess={(x)=>{console.log(x.transactionId);}} 
onCallbackFailure={(x)=>{console.log(x.message)}}
/>

Receive payment. A bill prompt is sent to mobile subscriber to enter PIN. Payment notification is sent to your callback Url.

ussdCode Type: STRING. Ussd code provided by ussd-gateway. recipient Type: STRING. Mobile number to receive payment. Payment is made real-time to recipient.

amount Type: FLOAT. Amount to receive.

reference Type: STRING. Reference.

thirdPartyTransactionId Type: STRING. unique id you assign to transaction.

onPaymentSuccess Type: Function(response). A function to execute when a payment is successful.

onPaymentFailure Type: Function(response). A function to execute when a payment fails.

onCallbackSuccess Type: Function(response). A function to execute when your callback Url returns a response.

onCallbackFailure Type: Function(response). A function to execute when your callback Url fails.

Configure callbackUrl(Your endpoint to receive payment notification)

sign-up on Opanet and create a project. The create project form requires you to enter a url to receive payment notification.

Sample payment notification

{
type:"POST",    
url:"https://yourdomain/api",
headers: { 
    opanet_appId:"provided when you created a project",
    opanet_appKey:"provided when you created a project",
    Content-Type:"application/Json"
     },
data:{
    sender:"233548****10", 
    recipient:"233241****89", 
    amount:1.00, 
    reference:"123456789", 
    transactionId:"40958665648"
    }
}

Sample notification response

{
    error:"00", 
    message:"successfull"
}

Pending Callbacks

import { http, Pay, PendingCallbacks } from 'react-native-opanet-http-over-ussd';

// ...

<PendingCallbacks
ussdCode="*000#"
/>

Payment notifications that failed to reach your callback Url. This occurs when your Url is down. Mobile subscriber can click to resend notification.

ussdCode Type: STRING. Ussd code provided by ussd-gateway.

License

MIT