Python SDK for the TelePay API
![TelePay Python](https://github.com/TelePay-cash/telepay-python/blob/main/docs/cover.png?raw=true)
Official TelePay client library for the Python language, so you can easely process cryptocurrency payments using the REST API.
![Blog](https://img.shields.io/badge/RSS-FFA500?style=flat-square&logo=rss&logoColor=white)
Installation
Install the package with pip:
pip install telepay
Or using Poetry:
poetry add telepay
Using the library
Refer to the TelePay Docs and follow the first steps guide, you'll get your TelePay account and API key.
To make requests to the TelePay API, you need to import a client. We have two clients:
TelePaySyncClient
: make requests synchronously.TelePayAsyncClient
make requests asynchronously.
Import and use the client
from telepay.v1 import TelePaySyncClient, TelePayAsyncClient
client = TelePaySyncClient(secret_api_key)
client = TelePayAsyncClient(secret_api_key)
Use the client as a context manager
We recommend using the client as a context manager, like this:
with TelePaySyncClient(secret_api_key) as client:
...
or
async with TelePayAsyncClient(secret_api_key) as client:
...
API endpoints
The API endpoints are documented in the TelePay documentation, refer to that pages to know more about them.
To manage the requests, if the client is async, you should use the await
keyword, like this:
response = await client.method(...)
Where method
is the endpoint method.
get_me
Info about the current merchant. Read docs
account = client.get_me()
get_balance
Get your merchant wallet assets with corresponding balance. Read docs
wallets = client.get_balance()
Or get a specific wallet balance by specifying the asset
, blockchain
and network
.
wallet = client.get_balance(asset='TON', blockchain='TON', network='network')
Assets
get_asset
Get asset details. Read docs
asset = client.get_asset(asset='TON', blockchain='TON')
get_assets
Get assets suported by TelePay. Read docs
assets = client.get_assets()
Invoices
get_invoice
Get invoice details, by its number. Read docs
invoice = client.get_invoice(number)
get_invoices
Get your merchant invoices. Read docs
invoices = client.get_invoices()
create_invoice
Creates an invoice, associated to your merchant. Read docs
invoice = client.create_invoice(
asset='TON',
blockchain='TON',
network='mainnet',
amount=1,
description='Product',
metadata={
'color': 'red',
'size': 'large',
},
success_url='https://example.com/success',
cancel_url='https://example.com/cancel',
expires_at=30
)
cancel_invoice
Cancel invoice, by its number. Read docs
invoice = client.cancel_invoice(number)
delete_invoice
Delete invoice, by its number. Read docs
status = client.delete_invoice(number)
Transfers
transfer
Transfer funds between internal wallets. Off-chain operation. Read docs
status = client.transfer(
asset='TON',
blockchain='TON',
network='mainnet',
amount=1,
username='test',
message='Thanks'
)
Withdrawals
get_withdraw_minimum
Obtains minimum amount required to withdraw funds on a given asset. Read docs
minimum = client.get_withdraw_minimum(
asset='TON',
blockchain='TON',
network='mainnet',
)
get_withdraw_fee
Get estimated withdraw fee, composed of blockchain fee and processing fee. Read docs
fees = client.get_withdraw_fee(
to_address='EQCKYK7bYBt1t8UmdhImrbiSzC5ijfo_H3Zc_Hk8ksRpOkOk',
asset='TON',
blockchain='TON',
network='mainnet',
amount=1,
message='test'
)
withdraw
Withdraw funds from merchant wallet to external wallet. On-chain operation. Read docs
status = client.withdraw(
to_address='EQCKYK7bYBt1t8UmdhImrbiSzC5ijfo_H3Zc_Hk8ksRpOkOk',
asset='TON',
blockchain='TON',
network='mainnet',
amount=1,
message='test'
)
Webhooks
Webhooks allows you to get updates delivered to your app server whenever we have events on our side. We will send a POST request over HTTPS, with serialized JSON data of the event, to the endpoint defined by you in the Developers > Webhooks section, in your merchant dashboard. Read more in the docs.
get_webhook
Get webhook details, by its id. Read docs
client.get_webhook(id)
get_webhooks
Get your merchant webhooks. Read docs
webhooks = client.get_webhooks()
create_webhook
Create a webhook. Read docs
webhook = client.create_webhook(
url='https://example.com',
secret='hello',
events=['all'],
active=True
)
update_webhook
Update a webhook. Read docs
webhook = client.update_webhook(
url='https://example.com',
secret='hello',
events=['invoice.completed'],
active=True
)
activate_webhook
Activate a webhook, by its id. Read docs
client.activate_webhook(id)
deactivate_webhook
Deactivate a webhook, by its id. Read docs
client.deactivate_webhook(id)
delete_webhook
Delete a webhook, by its id. Read docs
client.deactivate_webhook(id)
Webhook utils
The telepay.v1.webhooks
module contains utilities to manage webhooks received on your side.
get_signature(data, secret)
: Returns a webhook signature, used to verify data integrity of the webhook. This is optional, but highly recommended.TelePayWebhookListener
: A lightweight webhook listener, to receive webhooks from TelePay. You could build your own, like using django views, flask views, or any other web framework. Your choice.
Example using TelePayWebhookListener
from telepay.v1.webhooks import TelePayWebhookListener
def callback(headers, data):
print("Executing callback...")
listener = TelePayWebhookListener(
secret="SECRET",
callback=callback,
host="localhost",
port=5000,
url="/webhook",
log_level="error",
)
listener.listen()
Running the listener will output something like this:
![Webhook listener](https://github.com/TelePay-cash/telepay-python/blob/main/docs/webhook-listener.png?raw=true)
Modify the listener parameters to your needs, knowing this:
secret
: A secret token that your side knows and it's configured in the webhook definition, on the TelePay dashboard.callback
: The callback function that is called when new webhook arrives, receiving it's HTTP headers and data.host
: The host on which the listener will be running.port
: The port on which the listener will be exposed.url
: The webhook url, which is secret and should only be known by your app and TelePay. Otherwise, it could lead to security issues.log_level
: The listener logger level, like "error"
, "info"
or "debug"
.
Contributors ✨
The library is made by (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!