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.
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.
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 thepsys_cid
to thesource_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 thesource_amount
.
# Example: using required fields only
first_invoice = plisio.create_invoice('currency', 'order_name', 'order_number')
# Example: using cryptocurrency
second_invoice = plisio.create_invoice(
'currency',
'order_name',
'order_number',
amount='amount',
allowed_psys_cids='allowed_psys_cids',
description='description',
callback_url='callback_url',
email='email',
language='language',
plugin='plugin',
version='version',
)
# Example: using fiat currency
third_invoice = plisio.create_invoice(
'currency',
'order_name',
'order_number',
source_currency='fiat currency',
source_rate='source_rate',
allowed_psys_cids='allowed_psys_cids',
description='description',
callback_url='callback_url',
email='email',
language='language',
plugin='plugin',
version='version',
)
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, thePlanName
enum;use_wallet
— pay fee from wallet;use_wallet_balance
— balance of wallet that will be used to pay fee;plans
— the modelFeePlan
;custom
— the modelCustom
;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 into
parameter;fee_plan
— a name of the one of fee plans;fee_rate
— custom feeRate. conf_target (blocks) for BTC like cryptocurrencies or gasPrice in GWAI for ETH based cryptocurrencies;type_
— operation type, likes inget_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 thecurrency
to thesource_currency
at the moment of transfer;fee
— transaction fee stated in the transfer;wallet_hash
— destination hash (iftype_
is the cash_out);sendmany
— dictionary of hashes and values (iftype
is the mass_cash_out);params
— a modelWithdrawParams
;created_at_utc
— timestamp in the UTC timezone; it may need to be divided by 1000;amount
— transfer amount in cryptocurrencytx_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:
get_operation
to view a specific transaction byid
;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_
— modelOperationType
consisted 4 types: cash_in, cash_out, mass_cash_out, invoice;status
— modelOperationStatus
, 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
— modelWithdrawParams
;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.