Download the PHP package nikapps/saman-ussd without Composer

[obsolete] Saman USSD

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

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 and amount, together or reason should be less than or equal to 40 characters.

Alias methods:

• correct() alias of successful()
• incorrect() alias of failed()
• error($error) alias of reason($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 to 40 characters.

Alias methods:

• error($error) alias of reason($reason)
• id($providerId) alias of providerId($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 or reason should be less than or equal to 40 characters.

Alias method:

• error($error) alias of reason($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 of failed()
• successfulTransaction() alias of successful()
• failedResult() alias of notFound()
• successfulResult() alias of found()

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.

Donation