Python SDK for Plisio API

Current project is a Python SDK for Plisio API. To use it, you should be registered on Plisio The account can be created here) You will receive a personal secret key, that is used for all calls to API.

Install

To download Plisio SDK, either fork this GitHub repo or simply use PyPI via pip:

$ pip install plisio

Usage

Initialize the connection

To be able to send the requests, create an instance of class PlisioClient.

import plisio
...

client = plisio.PlisioClient(api_key='your_secret_key')

Balance

Plisio supports 9 cryptocurrencies(https://plisio.net/documentation/appendices/supported-cryptocurrencies). To view, for example the Ethereum (ETH) balance: Send the request by client and process the response with the help of an appropriate model.

# Sending request and getting processed response
balance = client.get_balance(plisio.CryptoCurrency.ETH)

Currencies

To view current exchange rate for the supported cryptocurrencies to the definite fiat currency, send a request to API by the method get_currency with the selected fiat currency.

Example: getting the rate of Australian Dollar (AUD). If no fiat currency is selected, the rate of United States Dollar (USD) is used by default. The response is a list of models that consist rates of exchanges.

currencies = client.get_currencies(plisio.FiatCurrency.AUD)

Creating a new invoice

The request has to receive the following required parameters:

• currency - the name of cryptocurrency;
• order_name - merchant internal order name;
• order_number - merchant internal order number.

Additional parameters:

• amount - any cryptocurrency float value. If a fiat currency is to be converted, skip this field and use the next two fields instead;
• source_currency - the name of the fiat currency;
• source_amount - any float value;
• allowed_psys_cids - comma-separated list of cryptocurrencies that are allowed for a payment. Also, you will be able to select one of them. Example: 'BTC,ETH,TZEC';
• description - merchant invoice description;
• callback_url - 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 the URL that can be set under profile in API settings, in the 'Status URL' field; Add ?json=true to this url to get data in JSON and validate it client.validate_callback
• email - an auto-fill invoice email. You will be asked to enter an email to which a notification will be sent;
• language - en_US (supports English only);
• plugin - Plisio's internal field to determine integration plugin;
• version - Plisio's internal field to determine integration plugin version.
• redirect_to_invoice - Instead of JSON response user will be redirected to the Plisio's invoice page (is not working for a white-label shop).
• expire_min - Interval in minutes when invoice will be expired.

The response is a model that can fill differently depending on whether you have While Label or not. In the first case, only two fields are returned: txn_id is a Plisio's intertnal ID and invoice_url is an invoice URL. And in the second case, extra fields are added to them:

• amount - invoice amount in the selected cryptocurrency;
• pending_amount - the remaining amount to be paid in the selected cryptocurrency;
• wallet_hash - invoice hash;
• psys_cid - cryptocurrencies ID;
• currency - cryptocurrencies code;
• source_currency - fiat currency;
• source_rate - exchange rate from the psys_cid to the source_currency at the moment of transfer;
• expected_confirmations - the number of expected confirmations to mark the invoice as completed;
• qr_code - QR code image in base64 format;
• verify_hash - hash to verify the POST data signed with your API_KEY;
• invoice_commission - Plisio commission;
• invoice_sum - shop pays commission: invoice amount - invoice_commission, client pays commission: invoice amount;
• invoice_total_sum - shop pays commission: invoice amount, client pays commission: invoice_commission + invoice_sum.

Create a few Python examples, where use:

• required fields only;
• all the fields besides the amount;
• all the fields besides the source_currency and the source_amount.

# Example: using required fields only
first_invoice = plisio.invoice(plisio.CryptoCurrency.BTC, 'order1', 20230903182401, 0.00001)

# Example: using cryptocurrency
second_invoice = plisio.invoice(
    plisio.CryptoCurrency.TRX,
    'order2',
    20230903182402,
    amount=100,
    email='test@plisio.net'
)

# Example: using fiat currency
third_invoice = plisio.invoice(
    plisio.CryptoCurrency.TRX,
    'order3',
    20230903182403,
    source_currency=plisio.FiatCurrency.USD,
    source_rate=10.2,
    allowed_currencies=[plisio.CryptoCurrency.TRX,plisio.CryptoCurrency.USDT_TRX]
)

Validate callback data

To validate invoice's callback data use next code:

PlisioClient.

import plisio
...

client = plisio.PlisioClient(api_key='your_secret_key')
isValid = client.validate_callback(request.body)

If you have some issues with it - verify that you've added json=true to yours callback_url

Commission

To estimate the cryptocurrency fee and Plisio commission, call method get_commission. It takes one required parameter (crypto_currency, the name of the cryptocurrency) and five additional parameters:

• addresses - wallet address or comma separated addresses when estimating fee for mass withdrawal;
• amounts - amount or comma separated amount that will be send in case of mass withdraw;
• type_ - operation type, such as:
  • cash_out;
  • mass_cash_out;
• fee_plan - the name of fee plan;
• custom_fee_rate - custom fee plan value.

Method returns the model Commission, which has fields:

• commission - Plisio commission value;
• fee - cryptocurrency fee value;
• max_amount - maximum allowed amount to withdrawal;
• plan - Plisio's cryptocurrency fee estimation plan, the PlanName enum;
• use_wallet - pay fee from wallet;
• use_wallet_balance - balance of wallet that will be used to pay fee;
• plans - the model FeePlan;
• custom - the model Custom;
• errors - the number of errors;
• custom_fee_rate - custom fee plan value.

Example: a request using Ethereum (ETH):

commission = plisio.get_commission(
    plisio.CryptoCurrency.ETH
)

Custom

There are 5 fields:

• min_ - minimal custom fee plan value;
• max_ - maximum custom fee plan value;
• default - estimated fee parameter to confirm the transaction in the "conf_target" blocks;
• borders - rate of the supported plan;
• unit - fee unit.

Withdrawal

To withdraw, call the withdraw method and apply the following parameters:

• crypto_currency - 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;
• fee_plan - a name of the one of fee plans;
• fee_rate (expected param, unavailable) - custom feeRate. conf_target (blocks) for BTC like cryptocurrencies or gasPrice in GWAI for ETH based cryptocurrencies;
• type_ - operation type, likes in get_commission method (it's an optional parameter).

After that you are getting model Withdraw with fields:

• type_ - operation type, given in the request;
• status - specifies whether the operation was completed or not (completed, error);
• currency - name of the cryptocurrency;
• source_currency - name of the fiat currency (only USD available);
• source_rate - exchange rate from the currency to the source_currency at the moment of transfer;
• fee - transaction fee stated in the transfer;
• wallet_hash - destination hash (if type_ is the cash_out);
• sendmany - dictionary of hashes and values (if type is the mass_cash_out);
• params - a model WithdrawParams;
• created_at_utc - timestamp in the UTC timezone; it may need to be divided by 1000;
• amount - transfer amount in cryptocurrency
• tx_url - link to the cryptocurrency block explorer;
• tx_id - link of transaction ids;
• id - internal Plisio operation ID.

withdraw = plisio.withdraw(
    crypto_currency = plisio.CryptoCurrency.LTC,
    to = 'wallet_address',
    amount = float(0.01),
    type_ = plisio.OperationType.cash_out
)

Fee estimation

To estimate fee, apply to get_fee the following parameters:

• crypto_currency - name of the cryptocurrency;
• addresses - wallet address or comma separated addresses when estimating fee for a mass withdrawal;
• amounts - amount or comma separated amount that will be sent in case of a mass withdraw;
• fee_plan - a name of the one of fee plans (it is not required).

The response model has three fields:

• fee - transaction fee;
• currency - name of the cryptocurrency;
• plan - name of fee plan.

fee = plisio.get_fee(
    plisio.CryptoCurrency.ETH,
    'wallet_address',
    'amount',
    'normal',
)

Fee plan

Returns the model with fee plans by selected cryptocurrency. Also this model has additional fields according to the fee plan.

fee = plisio.get_fee_plan(
    plisio.CryptoCurrency.ETH
)

Operations

To view transactions, call:

1. get_operation to view a specific transaction by id;
2. get_operations to view all transactions.

In the first case, it returns a model Operation for the required operation's id. In the second case - model Operations, which consists of operations list, links for current, first and last pages and metadata about all your operations. The second case has several optional variables:

• page - page number;
• limit - number of elements on the page;
• shop_id - filter operation by shop;
• type_ - transaction type;
• status - transaction status;
• currency - name of the cryptocurrency;
• search - text search by the transaction id (txid), invoice's order number or customer email from invoice.

Operation

The Operation model has the next fields:

• user_id - Profile ID;
• shop_id - Shop ID;
• type_ - model OperationType consisted 4 types: cash_in, cash_out, mass_cash_out, invoice;
• status - model OperationStatus, described with 6 statuses: pending, completed, error, new, expired, mismatch, cancelled;
• pending_sum - unconfirmed amount (mempool);
• currency - name of the cryptocurrency;
• source_currency - fiat currency;
• source_rate - exchange rate from the "cryptocurrency"; to the "source_currency" at the moment of transfer;
• fee - transaction fee stated in the transfer;
• wallet_hash - destination hash or invoice hash;
• sendmany - pairs of hashes and values;
• params - model WithdrawParams;
• expire_at_utc - timestamp in UTC timezone; it may need to be divided by 1000;
• created_at_utc - timestamp in the UTC timezone; it may need to be divided by 1000;
• amount - amount received/transferred by an operation;
• sum_:
  • invoice: params.amount + Plisio commission (if the customer pays the commission) or params.amount (if the merchant pays the commission);
  • cash-out: transfer amount + network fee;
  • cash-in: received amount.
• commission - Plisio commission;
• tx_url - link to the cryptocurrency block explorer;
• tx_id - list of transaction ids;
• id_ - internal Plisio operation ID;
• actual_sum - real incoming amount;
• actual_commission - Plisio commission taken;
• actual_fee - network fee (move invoice to wallet);
• actual_invoice_sum - actual_sum - actual_commission_sum - actual_fee;
• tx - list of transactions details;
• status_code - code of status.

WithdrawParams

There are 4 params:

• source_currency - name of the cryptocurrency;
• source_rate - exchange rate from the "cryptocurrency"; to the "source_currency" at the moment of transfer;
• usd_rate - exchange rate from the "cryptocurrency"; to the USD at the moment of transfer;
• fee - transaction fee stated in the transfer.

Async usage

All these methods have their async analogues in PlisioAioClient. They can be easily integrated into your async functions.

import plisio
...

client = plisio.PlisioAioClient('your_secret_key')

currencies = await client.get_currencies(plisio.FiatCurrency.AUD)