nikapps/saman-ussd

A php package for connecting to Saman 724 USSD gateway

[obsolete] Saman USSD

Obsolete package - payment with USSD is forbidden by Iranian central bank (more info), _(*1)

, _(*2)

A php package for connecting to Saman *724# payment gateway., _(*3)

Table of contents:, _(*4)

• Installation
• Usage
• Listener
• Responses
• Customization
• Testing
• Dependencies
• Official documentation
• Contribute
• License
• Donation

Installation

Using Composer, install this package by running this command:, _(*5)

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:, _(*6)

1. Listener Class:

You can setup your listener by implementing interface Nikapps\SamanUssd\Contracts\SamanUssdListener:, _(*7)

<?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:, _(*8)

$samanUssd->setListener(new Listener());

2. Callbacks:

Also you can pass a closure for each soap call:, _(*9)

$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:, _(*10)

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:, _(*11)

public function onProductInfo(array $codes, $language)
{

    // TODO check codes

    return (new ProductInfoResponse)
        ->successful()
        ->amount(1000)
        ->description('Success!');
}

If the given codes are incorrect:, _(*12)

return (new ProductInfoResponse())
    ->failed()
    ->reason('Failed!');

If you want to set Terminal and Wage:, _(*13)

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:, _(*14)

public function onCallSale(array $codes, $amount, $phone, $sepId, $language)
{

    // Todo check sale

    return (new CallSaleResponse)
        ->successful()
        ->providerId('provider_id');
}

If something goes wrong:, _(*15)

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:, _(*16)

public function onExecuteSale($providerId)
{
    return (new ExecuteSaleResponse)
        ->successful()
        ->description('Success!'); 
}

If something goes wrong:, _(*17)

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:, _(*18)

public function onCheckStatus($providerId)
{
    // Todo check provider id

    return (new CheckStatusResponse)
        ->found()
        ->successful();
}

When provider_id is not found:, _(*19)

return (new CheckStatusResponse)
    ->notFound()
    ->failed();

When provider_id is found, but transaction was failed:, _(*20)

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:, _(*21)

$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:, _(*22)

$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:, _(*23)

$samanUssd->setWsdlQueryString('WSDL');

Testing

Unit test

Run:, _(*24)

vendor/bin/phpspec run

Api test

Run:, _(*25)

docker-compose -f docker-compose.testing.yaml up -d

vendor/bin/codecept run

Dependencies

• php >= 7.1
• piotrooo/wsdl-creator

Dev dependencies:, _(*26)

• phpspec/phpspec
• codeception/codeception

Official documentation

Download: Technical Documentation Version 1.8, _(*27)

Contribute

Wanna contribute? simply fork this project and make a pull request!, _(*28)

License

This project released under the MIT License., _(*29)

/*
 * 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.
 */

Donation

, _(*30)