Skip to content

Plisio/plisio-python

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

13 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

About

Plisio pythin API

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages