README

#This PHP SDK project for Plisio Api Support

This is fully object-oriented php's composer package, developed to work with Plisio's cryptocurrency payment-gateway.

interface InteractionInterface
{
    /**
     * @throws Throwable on errors (If silent mode turn off)
     * @return null on errors (If silent mode turn on)
     * @return BalanceApiResponse on success
     */
    public function getBalance(string $currency): ?BalanceApiResponse;

    /**
     * @throws Throwable on errors (If silent mode turn off)
     * @return null on errors (If silent mode turn on)
     * @return OperationApiResponse on success
     */
    public function getOperationById(string $id): ?OperationApiResponse;

    /**
     * @throws Throwable on errors (If silent mode turn off)
     * @return null on errors (If silent mode turn on)
     * @return CommissionApiResponse on success
     */
    public function getCommission(CommissionQuery $query): ?CommissionApiResponse;

    /**
     * @throws Throwable on errors (If silent mode turn off)
     * @return null on errors (If silent mode turn on)
     * @return CryptocurrencyApiResponse on success
     */
    public function getCurrencyInfoByFiat(string $fiat): ?CryptocurrencyApiResponse;

    /**
     * @throws Throwable on errors (If silent mode turn off)
     * @return null on errors (If silent mode turn on)
     * @return FeePlanApiResponse on success
     */
    public function getFeePlanByPsyscid(string $psyscid): ?FeePlanApiResponse;

    /**
     * @throws Throwable on errors (If silent mode turn off)
     * @return null on errors (If silent mode turn on)
     * @return WithdrawApiResponse on success
     */
    public function withdraw(WithdrawQuery $withdrawQuery): ?WithdrawApiResponse;

    /**
     * @throws Throwable on errors (If silent mode turn off)
     * @return null on errors (If silent mode turn on)
     * @return InvoiceWhiteLabelResponse on success
     */
    public function createInvoice(InvoiceQuery $invoiceQuery): ?InvoiceWhiteLabelResponse;

    /**
     * @throws Throwable on errors (If silent mode turn off)
     * @return FeeApiResponse on success
     * @return null on errors (If silent mode turn on)
     */
    public function getFee(FeeQuery $feeQuery): ?FeeApiResponse;
}

InteractionInterface methods description:

getBalance(string $currency)

Let's see yourself cryptocurrency balance in Bitcoin (BTC), for example. Also supports 9 cryptocurrencies.

$balance = $this->interaction->getBalance(Currencies::BTC);
getOperationById(string $id)

Returns information about concrete transaction by transaction identifier, example:

$operation = $this->interaction->getOperationById('61e9384388ecfd3ea775dfb2');
getCommission(CommissionQuery $query)

Estimates cryptocurrency fee and Plisio commission, accepts CommissionQuery class, example:

$commission = $this->interaction->getCommission(new CommissionQuery(Currencies::BTC));

Also commission query class has nullable parameters:
```
 private ?string $addresses = null;
 private ?string $amounts = null;
 private ?string $type = null;
 private ?string $feePlan = null;
```
- $addresses - Wallet address or comma separated addresses when estimating fee for mass withdrawal
- $amounts - Amount or comma separated amount that will be sent in case of mass withdraw
- $type - Operation type, such as: 'cash_out' or 'mass_cash_out'
- $feePlan - The name of fee plan
getCurrencyInfoByFiat(string $fiat)

Provides current rate of exchange supported cryptocurrencies to the definite fiat currency, needs to send the request to API by the method with selected fiat currency.

Let's get the rate of Australian Dollar (AUD), for instance. By the way, if there is not selected any of fiat currency, is rate of United States Dollar (USD), by default. The response is a list of models that consist rates of exchanges:

$info = $this->interaction->getCurrencyInfoByFiat(FiatCurrencies::AUD);
getFeePlanByPsyscid(string $psyscid)

Returns the model with fee plans by selected cryptocurrency. Also, this model has additional fields pointed what your fee plan is.

Example:

$feePlan = $this->interaction->getFeePlanByPsyscid(Currencies::BTC);
withdraw(WithdrawQuery $withdrawQuery) If you want to withdraw, you should call withdraw method that accepts WithdrawQueryClass:
```
 private string $psyscid;
 private string $to;
 private string $amount;
 private int $feeRate;
 private string $feePlan;

 private ?string $type = null;
```
- $psyscid — a name of cryptocurrency;
- $to — hash or multiple comma separated hashes pooled for the mass_cash_out;
- $amount — any comma separated float values for the mass_cash_out in the order that hashes are in to parameter;
- $feePlan — a name of the one of fee plans;
- $feeRate — custom feeRate. conf_target (blocks) for BTC like cryptocurrencies or gasPrice in GWAI for ETH based cryptocurrencies;
- $type — operation type (it's an optional parameter).
Example:
```
$withdraw = $this->interaction->withdraw(
        new WithdrawQuery(
            Currencies::BTC,
            '2N3cD7vQxBqmHFVFrgK2o7HonHnVoFxxDVB',
            '0.00031',
            FeePlans::NORMAL,
            1
        )
    );
```
createInvoice(InvoiceQuery $invoiceQuery)

Let us coming go to the creation of invoices, first you need to build InvoiceQuery class:
```
private string $currency;
private string $orderName;
private string $orderNumber;

private ?string $amount = null;
private ?string $sourceCurrency = null;
private ?string $sourceAmount = null;
private ?string $allowedPsyscids = null;
private ?string $description = null;
private ?string $callBackUrl = null;
private ?string $email = null;
private ?string $language = null;
private ?string $plugin = null;
private ?string $version = null;
private ?bool $redirectToInvoice = null;
private ?string $expireMin = null;
```
The query needs to receive the next required parameters:
- $currency — the name of cryptocurrency;
- $orderName — merchant internal order name;
- $orderNumber — merchant internal order number.
Beside these params, there are additional such as:
- $amount — any cryptocurrency float value. If you want to convert a fiat currency, you should skip current field and use the next two fields instead it;
- $sourceCurrency — the name of the fiat currency;
- $sourceAmount — any float value;
- $allowedPsyscids — comma-separated list of cryptocurrencies that allowed for payment. Also, you will be able to select one of them. Example: 'BTC,ETH,TZEC';
- $description — merchant invoice description;
- $callbackUrl — merchant full URL to get invoice updates. The POST request will be sent to this URL. If this parameter isn’t set, a callback will be sent to URL that can be set under profile in API settings, that has got 'Status URL' field;
- $email — an autofill invoice email. You will be asked to insert their email where a notification will be sent;
- $language — en_US (now supports English only);
- $plugin — Plisio’s internal field to determine integration plugin;
- $version — Plisio’s internal field to determine integration plugin version.
Example:
```
$invoice = $this->interaction->createInvoice(
        (new InvoiceQuery(Currencies::BTC, 'some order', '234sdfsd'))
            ->setAmount('0.01')
    );
```
getFee(FeeQuery $feeQuery)

To estimate fee you should create FeeQuery class with parameters:
```
private string $psyscid;
private string $addresses;
private string $amounts;

private ?string $feePlan = null;
```
- $psyscid — a name of cryptocurrency;
- $addresses — wallet address or comma separated addresses when estimating fee for mass withdrawal;
- $amounts — amount or comma separated amount that will be sent in case of mass withdraw;
- $feePlan — a name of the one of fee plans (it is not required).
Example:
```
$fee = $this->interaction->getFee(
        new FeeQuery(
            Currencies::BTC,
            'tb1qfqtvgh97umdum8zwyah4ztzkwz8j7qyyalgwa4',
            '0.0003'
        )
    );
```

Entrypoint oh php's sdk is represented with singleton-class PlisioPhpSdk, example:

$container = \PlisioPhpSdk\PlisioPhpSdk::get();
/** @var \PlisioPhpSdk\Http\InteractionInterface $interaction */
$interaction = $container->get(\PlisioPhpSdk\Http\InteractionInterface::class);

Also, this sdk's provides suitable configuration possibility, you can create conf.yaml file like below:

plisio-php-sdk:
  common:
    dev:
      api-key:
      base-uri:
      user: 
      password: 
    prod:
      api-key:
      base-uri:
  current-env: dev
  silent: false

To configure sdk's you need to create conf.yaml file in your's project-root directory and launch console command from vendor's directory:

php cli/console.php plisio-php-sdk:load-conf "path to conf.yaml file"

Sdk's has two working modes from the box (This functionality only concerns interaction with the api):

Silent mode (Does not throw exception, return null in some cases), all exception writing out in .log file
Non-silent mode (Throws exceptions), also all exceptions are logged

The sdk is logged in the plisio-php-sdk.log log file, for convenience, you can create a symbolic link from your root directory to this file. In the quality of the demonstration, all the functionality of the sdk (working with the test resource) is duplicated by console commands:

plisio-php-sdk:load-conf

plisio-php-sdk:test-balance

plisio-php-sdk:test-commission

plisio-php-sdk:test-create-invoice

plisio-php-sdk:test-currency-info

plisio-php-sdk:test-fee

plisio-php-sdk:test-fee-plan

plisio-php-sdk:test-operation

plisio-php-sdk:test-withdraw

plisio / plisio-api-php

Maintainers

Details

README