nikapps / saman-ussd
A php package for connecting to Saman 724 USSD gateway
Installs: 26 975
Dependents: 0
Suggesters: 0
Security: 0
Stars: 6
Watchers: 3
Forks: 4
Open Issues: 0
Requires
- php: >=7.1.0
- ext-dom: *
- ext-soap: *
- piotrooo/wsdl-creator: 2.0.*
Requires (Dev)
- codeception/codeception: ^2.4
- phpspec/phpspec: ^2.2
- phpunit/phpunit: 4.*
This package is not auto-updated.
Last update: 2024-10-26 18:59:54 UTC
README
Obsolete package - payment with USSD is forbidden by Iranian central bank (more info)
A php package for connecting to Saman *724# payment gateway.
Table of contents:
- Installation
- Usage
- Listener
- Responses
- Customization
- Testing
- Dependencies
- Official documentation
- Contribute
- License
- Donation
Installation
Using Composer, install this package by running this command:
composer require nikapps/saman-ussd
Usage
<?php use Nikapps\SamanUssd\SamanUssd; $samanUssd = new SamanUssd(); // Set api endpoint $samanUssd->endpoint('http://example.com/webservice.php'); // TODO: Set listener or callbacks $samanUssd->handle();
Listener
You need a listener for incoming soap calls. You have two options:
1. Listener Class:
You can setup your listener by implementing interface Nikapps\SamanUssd\Contracts\SamanUssdListener
:
<?php use Nikapps\SamanUssd\Contracts\SamanUssdListener; class Listener implements SamanUssdListener{ /** * When `GetProductInfo` is called * * @param string[] $codes * @param string $language * * @return \Nikapps\SamanUssd\Responses\ProductInfoResponse; */ public function onProductInfo(array $codes, $language) { // TODO: response } /** * When `CallSaleProvider` is called * * @param string[] $codes * @param integer $amount * @param string $phone Mobile/Call number * @param long $sepId Unique number provided by saman724 * @param string $language * * @return \Nikapps\SamanUssd\Responses\CallSaleResponse */ public function onCallSale(array $codes, $amount, $phone, $sepId, $language) { // TODO: return response } /** * When `ExecSaleProvider` is called * * @param string $providerId * * @return \Nikapps\SamanUssd\Responses\ExecuteSaleResponse */ public function onExecuteSale($providerId) { // TODO: return response } /** * When `CheckStatus` is called * * @param string $providerId * * @return \Nikapps\SamanUssd\Responses\CheckStatusResponse */ public function onCheckStatus($providerId) { // TODO: return response } }
Then set your listener:
$samanUssd->setListener(new Listener());
2. Callbacks:
Also you can pass a closure for each soap call:
$samanUssd->onProductInfo(function (array $codes, $language) { // TODO: return response }); $samanUssd->onCallSale(function (array $codes, $amount, $phone, $sepId, $language) { // TODO: return response }); $samanUssd->onExecuteSale(function ($providerId) { // TODO: return response }); $samanUssd->onCheckStatus(function ($providerId) { // TODO: return response });
Responses
For each api call, you should return its response object:
onProductInfo
When method GetProductInfo
is called on your soap server, onProductInfo
will be called on your listener and you should return an instance of Nikapps\SamanUssd\Responses\ProductInfoResponse
:
public function onProductInfo(array $codes, $language) { // TODO check codes return (new ProductInfoResponse) ->successful() ->amount(1000) ->description('Success!'); }
If the given codes are incorrect:
return (new ProductInfoResponse()) ->failed() ->reason('Failed!');
If you want to set Terminal
and Wage
:
return (new ProductInfoResponse) ->successful() ->amount(1000) ->description('Success!') ->terminal(12345) ->wage(200);
- Notice :
description
andamount
, together orreason
should be less than or equal to40
characters.
Alias methods:
correct()
alias ofsuccessful()
incorrect()
alias offailed()
error($error)
alias ofreason($reason)
onCallSale
When method CallSaleProvider
is called on your soap server, onCallSale
will be called on your listener and you should return an instance of Nikapps\SamanUssd\Responses\CallSaleResponse
:
public function onCallSale(array $codes, $amount, $phone, $sepId, $language) { // Todo check sale return (new CallSaleResponse) ->successful() ->providerId('provider_id'); }
If something goes wrong:
return (new CallSaleResponse) ->failed() ->reason('Failed!');
- Notice :
reason
should be less than or equal to40
characters.
Alias methods:
error($error)
alias ofreason($reason)
id($providerId)
alias ofproviderId($providerId)
onExecuteSale
When method ExecSaleProvider
is called on your soap server, onExecuteSale
will be called on your listener and you should return an instance of Nikapps\SamanUssd\Responses\ExecuteSaleResponse
:
public function onExecuteSale($providerId) { return (new ExecuteSaleResponse) ->successful() ->description('Success!'); }
If something goes wrong:
return (new ExecuteSaleResponse) ->failed() ->reason('Failed!');
- Notice :
description
orreason
should be less than or equal to40
characters.
Alias method:
error($error)
alias ofreason($reason)
onCheckStatus
When method CheckStatus
is called on your soap server, onCheckStatus
will be called on your listener and you should return an instance of Nikapps\SamanUssd\Responses\CheckStatusResponse
:
public function onCheckStatus($providerId) { // Todo check provider id return (new CheckStatusResponse) ->found() ->successful(); }
When provider_id
is not found:
return (new CheckStatusResponse) ->notFound() ->failed();
When provider_id
is found, but transaction was failed:
return (new CheckStatusResponse) ->found() ->failed(); }
Alias methods:
failedTransaction()
alias offailed()
successfulTransaction()
alias ofsuccessful()
failedResult()
alias ofnotFound()
successfulResult()
alias offound()
Customization
1. Set Namespace
If you want to set your custom xml namespace:
$samanUssd->setNamespace('http://my-web-site.com');
2. Set custom soap options:
If you want to set custom soap options for SoapServer or override default options:
$samanUssd->setOptions([ 'soap_version' => SOAP_1_2 ]);
3. Set custom WSDL query string
By default, if you append ?wsdl
to your endpoint uri, you can see wsdl specification. If you want to set custom query string for that:
$samanUssd->setWsdlQueryString('WSDL');
Testing
Unit test
Run:
vendor/bin/phpspec run
Api test
Run:
docker-compose -f docker-compose.testing.yaml up -d vendor/bin/codecept run
Dependencies
php >= 7.1
piotrooo/wsdl-creator
Dev dependencies:
phpspec/phpspec
codeception/codeception
Official documentation
Download: Technical Documentation Version 1.8
Contribute
Wanna contribute? simply fork this project and make a pull request!
License
This project released under the MIT License.
/*
* Copyright (C) 2015 NikApps Team.
*
* 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:
*
* 1- The above copyright notice and this permission notice shall be included
* in all copies or substantial portions of the Software.
*
* 2- 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.
*/