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
Using Composer, install this package by running this command:
composer require nikapps/saman-ussd
<?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();You need a listener for incoming soap calls. You have two options:
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());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
});For each api call, you should return its response object:
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 :
descriptionandamount, together orreasonshould be less than or equal to40characters.
correct()alias ofsuccessful()incorrect()alias offailed()error($error)alias ofreason($reason)
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 :
reasonshould be less than or equal to40characters.
error($error)alias ofreason($reason)id($providerId)alias ofproviderId($providerId)
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 :
descriptionorreasonshould be less than or equal to40characters.
error($error)alias ofreason($reason)
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();
}failedTransaction()alias offailed()successfulTransaction()alias ofsuccessful()failedResult()alias ofnotFound()successfulResult()alias offound()
If you want to set your custom xml namespace:
$samanUssd->setNamespace('http://my-web-site.com');If you want to set custom soap options for SoapServer or override default options:
$samanUssd->setOptions([
'soap_version' => SOAP_1_2
]);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');Run:
vendor/bin/phpspec run
Run:
docker-compose -f docker-compose.testing.yaml up -d
vendor/bin/codecept runphp >= 7.1piotrooo/wsdl-creator
Dev dependencies:
phpspec/phpspeccodeception/codeception
Download: Technical Documentation Version 1.8
Wanna contribute? simply fork this project and make a pull request!
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.
*/
