Skip to main content

Official Python SDK for Plisio API

Project description

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.

Supported Versions

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;
  • 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]
)

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(
    plisio.CryptoCurrency.ETH,
    'hash1,hash2',
    'amount1,amount2',
    'normal',
    0,
)

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)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

plisio-1.0.5.tar.gz (20.6 kB view hashes)

Uploaded Source

Built Distribution

plisio-1.0.5-py3-none-any.whl (17.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page