ipayafrica/README.md

Integrates ipay africa payment gateway in your [node/io].js applications

# IpayAfrica
### Intro

Module for integrating [Ipay](https://www.ipayafrica.com/) a payment gateway in your application.For more information regarding integration visit the [developer portal](https://dev.ipayafrica.com) for more detailed information about request parameters and their meaning.

Both Posix and Windows platforms are supported.

### Features
These features are derived from the C2B API utilizing the REST API integration
- Ipay mobilemoney transactions
- Ipay MPESA and AIRTEL STK push payments
- Ipay search  transaction
- Ipay refund transactions

### Installation
IpayAfricar requires [Node.js](https://nodejs.org/) v6+ to run.
```bash
$ npm install ipayafrica
```
### Usage
```bash
var Ipay=require("./ipayafrica");
var ipay = new Ipay.IpayAfrica({
	hash_key:'demoCHANGED' //replace with own key/secret
});
var transact_req={
	live:0
	,oid:'123456' 
	,inv:'123456'
	,amount:'5.00'
	,tel:'0XXXXXXXXX' //customer mobile number
	,eml:'user@domain.com' 
	,vid:"demo" //replace with own vendor id (all lowercase)
	,curr:'KES' 
	,p1:'' 
	,p2:'' 
	,p3:'' 
	,p4:''
	,cbk:'https://example.com' //callback url
	,cst:1
	,crl:0
}
ipay.transact(transact_req,(err,res)=>{
	if(err){
		//process error here
	}else{
		var body=JSON.parse(res.raw_body);
		if(body.header_status==200){
			//check body.data for ipay parameters to process internaly
			//optionally you can:
			
			//1. transact mobile money
			var mobilemoney_req={
				sid:body.data.sid
				,vid:"demo" //replace with own vendor id (all lowercase)
			};
			ipay.transaction.mobilemoney(mobilemoney_req,(err,res)=>{
				if(err){
					//process error here
				}else{
					var body=JSON.parse(res.raw_body);
					if(body.header_status==200){
						//check body.data for ipay parameters to process internaly
					}else if(body.header_status==400){
						//check body.data for possible errors
					}
				}
			});
			
			//2. Send mpesa push
			var mpesa_push_req={
				phone:'254XXXXXXXXX' //safaricom phone number
				,sid:body.data.sid
				,vid:"demo" //replace with own vendor id (all lowercase)
			};
			ipay.transaction.push_mpesa(mpesa_push_req,(err,res)=>{
				if(err){
					//process error here
				}else{
					var body=JSON.parse(res.raw_body);
					if(body.header_status==200){//mpesa push successful
						//check body.data for ipay parameters to process internaly
					}else{//mpesa push fail
						//check body.data for possible errors
					}
				}
			});
			
			//3. Send airtel push
			var airtel_push_req={
				phone:'254XXXXXXXXX' //airtel phone number
				,sid:body.data.sid
				,vid:"demo" //replace with own vendor id (all lowercase)
			};
			ipay.transaction.push_airtel(airtel_push_req,(err,res)=>{
				if(err){
					//process error here
				}else{
					var body=JSON.parse(res.raw_body);
					if(body.header_status==200){//airtel push successful
						//check body.data for ipay parameters to process internaly
					}else{//airtel push fail
						//check body.data for possible errors
					}
				}
			});
			
		}else{
			//check possible headers
		}		
	}
});


```
#### Searching for a transaction
```bash
var search_req={
	oid:'123456' //order number/id
	,vid:"demo"	//replace with own vendor id (all lowercase)
};
ipay.transaction.search(search_req,(err,res)=>{
	if(err){
		//process error here
	}else{
		var body=JSON.parse(res.raw_body);
		if(body.header_status==200){//transaction found
			//check body.data for ipay parameters to process internaly
		}else if(body.header_status==400){//transaction not found
			//check body.data for possible errors
		}
	}
});
```

#### Refund for a transaction
```bash
var refund_req={
	code:'123456' //transaction code 
	,vid:"demo" //replace with own vendor id (all lowercase)
};
ipay.transaction.refund(refund_req,(err,res)=>{
	if(err){
		//process error here
	}else{
		var body=JSON.parse(res.raw_body);
		if(body.header_status==200){//refund successul
			//check body.data for ipay parameters to process internaly
		}else{//refund not successful
			//check body.data for possible errors
		}
	}
});
```

## Development

Want to contribute? Great!

## License
**Free Software, Hell Yeah!**
MIT License
Copyright (C) 2021 Francis Gathuna

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), 
to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.