[<img src="https://blockbee.io/static/assets/images/blockbee_logo_nospaces.png" width="300"/>](image.png)
# BlockBee's Django Library
Django's implementation of BlockBee's payment gateway
## Requirements:
```
Python >= 3.0
Django >= 2.0
Requests >= 2.20
```
## Install
```shell script
pip install django-blockbee
```
[on pypi](https://pypi.python.org/pypi/django-blockbee)
or
[on GitHub](https://github.com/blockbee-io/django-blockbee)
Add to INSTALLED_APPS:
```python
INSTALLED_APPS = (
'blockbee',
...
)
```
Run migrations:
```shell script
python3 manage.py migrate blockbee
```
Collect static files:
```shell script
python3 manage.py collectstatic
```
Add BlockBee's URLs to your project's urls.py file:
```python
urlpatterns = [
path('blockbee/', include('blockbee.urls')),
...
]
```
Add your BlockBee API Key (obtained from our [Dashboard](https://dash.blockbee.io/)).
```python
BLOCKBEE_API_KEY = 'your_api_key'
```
## Configuration
After the installation you need to set up Providers for each coin you wish to accept.
You need to go into your Django Admin and create a new BlockBee ``Provider`` for each coin with your cold wallet address where the funds will be forwarded to.
## Usage
### Creating an Invoice
In your order creation view, assuming ``user_order`` is your order object:
* ##### If you want the address generated:
```python
from blockbee import Invoice
...
def order_creation_view(request):
...
invoice = Invoice(
request=request,
order_id=user_order.id,
coin='btc',
value=user_order.value
)
payment_address = invoice.address()
if payment_address is not None:
# Show the payment address to the user
...
else:
# Handle request error, check RequestLogs on Admin
```
* ##### If you want the `blockbee.models.Request` object:
```python
from blockbee import Invoice
...
def order_creation_view(request):
...
invoice = Invoice(
request=request, # This if your view request. It's meant to create the callback URL
order_id=user_order.id,
coin='btc',
value=user_order.value
)
payment_request = invoice.request()
if payment_request is not None:
# Show the payment address to the user
...
else:
# Handle request error, check RequestLogs on Admin
```
#### Where:
``request`` is Django's view HttpRequest object
``order_id`` is just your order id
``coin`` is the ticker of the coin you wish to use, any of our supported coins (https://blockbee.io/cryptocurrencies/). You need to have a ``Provider`` set up for that coin.
``value`` is an integer of the value of your order
``apikey`` is the API Key that you got from your BlockBee Dashboard
### Getting notified when the user pays
```python
from django.dispatch import receiver
from blockbee.signals import payment_complete
@receiver(payment_complete)
def payment_received(order_id, payment, value):
# Implement your logic to mark the order as paid and release the goods to the user
...
```
Where:
``order_id`` is the id of the order that you provided earlier, used to fetch your order
``payment`` is an ``blockbee.models.Payment`` object with the payment details, such as TXID, number of confirmations, etc.
``value`` is the value the user paid
#### Important:
>
>Don't forget to import your signals file.
>
>On your App's `apps.py` file:
>
>```python
>class MyAppConfig(AppConfig):
> name = 'MyApp'
>
> def ready(self):
> super(MyAppConfig, self).ready()
>
> # noinspection PyUnresolvedReferences
> import MyApp.signals
>```
>[django docs](https://docs.djangoproject.com/en/3.0/topics/signals/#django.dispatch.receiver)
### Using our provided interface
Create a view in ``views.py``
```python
def payment(_r, request_id):
try:
req = Request.objects.get(id=request_id)
coin = req.provider.coin
qrcode = get_qrcode(coin, req.address_in)
fiat = get_conversion(coin, 'eur', req.value_requested)
print(fiat)
ctx = {
'req': req,
'qrcode': qrcode,
'fiat': fiat['value_coin']
}
return render(_r, 'payment.html', context=ctx)
except Request.DoesNotExist:
pass
return redirect('store:request')
```
In your template HTML
```djangotemplate
{% extends 'base.html' %}
{% load blockbee_helper %}
{% block content %}
{% generate_payment_template %}
{% endblock %}
```
### Helpers
This library has a couple of helpers to help you get started. They are present in the file ``utils.py``.
``blockbee.valid_providers()`` is a method that returns a list of tuples of the active providers that you can just feed into the choices of a ``form.ChoiceField``
``blockbee.get_order_invoices(order_id)`` returns a list of ``blockbee.models.Request`` objects of your order (you can have multiple objects for the same order if the user mistakenly initiated the payment with another coin or if he mistakenly didn't send the full payment)
``blockbee.callback_url(_r, params)`` build your callback URL to provide to ``get_request``. Should be used inside a view since ``_r = request``
### BlockBee Helper
This is the helper responsible for the connections ot the API itself. All these functions are in the ``blockbee.py`` file.
``get_info(coin)`` returns the information of all cryptocurrencies or just if ``coin=''`` or a specific cryptocurrency if ``coin='ltc'`` for example. [docs](https://docs.blockbee.io/#operation/info)
``get_supported_coins()`` returns all the support cryptocurrencies. You can consult them in this [list](https://blockbee.io/fees/).
``get_logs(coin, callback_url)`` returns all the callback logs related to a request. ``callback_url`` should be the callback provided to our API. [docs](https://docs.blockbee.io/#operation/logs)
``get_qrcode(coin, address, value, size)`` returns a PNG of a QR Code with the address for payment. [docs](https://docs.blockbee.io/tag/Bitcoin#operation/btcqrcode)
``get_conversion(origin, to, value)`` returns the converted value in the parameter ``value_coin`` to the currency you wish, FIAT or Cryptocurrency.
``get_estimate(coin)`` returns the estimation of the blockchain fees for the cryptocurrency specified in the parameter ``coin``. E.g: ``get_estimate('trc20_usdt')`` [docs](https://docs.blockbee.io/#operation/estimate)
``get_address(coin, params)`` requests a payment address to BlockBee. Params include all the parameters that can be found [here](https://docs.blockbee.io/#operation/create). The parameter ``apikey`` is mandatory.
### How to use the QR code (with address, coin and value)
To generate a QR Code you must use ``get_qrcode`` in your view and feed the parameters to your template. To generate a QR Code image you must place content of the API response after ``data:image/png;base64,{{qr_code}}`` so the browser generates the QR Code.
```djangotemplate
<img src="data:image/png;base64,{{ qrcode.qr_code }}" alt="Payment QR Code"/>
```
You can also make the QR Code clickable.
```djangotemplate
<a href='{{ qrcode.payment_uri }}'>
<img src="data:image/png;base64,{{ qrcode.qr_code }}" alt="Payment QR Code"/>
</a>
```
You can also add a value to the QR Code setting the ``value`` parameter to the value of your order (e.g ``0.2 LTC``). This may not function correctly in some wallets. **Use at your own risk.**
## What is the Store application?
We made the ``store`` application to provide you with code examples on how to implement our service. It also has the code for our suggested UI (both CSS and HTML).
## Help
Need help?
Contact us @ https://blockbee.io/contacts/
### Changelog
#### 1.0.0
* Initial Release
#### 1.0.1
* Minor fixes
* UI Improvements
#### 1.0.2
* Minor fixes
#### 1.0.3
* Minor fixes
* Signals now use the value_coin
* Removed deprecated fields from the payment model
#### 1.0.4
* Minor fixes
#### 1.0.5
* Minor fixes
#### 1.0.6
* Minor fixes
#### 1.0.7
* Minor fixes
Raw data
{
"_id": null,
"home_page": "https://github.com/blockbee-io/django-blockbee",
"name": "django-blockbee",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "BlockBee",
"author_email": "info@blockbee.io",
"download_url": "https://files.pythonhosted.org/packages/2a/24/a9513decea4fc7a025450086178007cf4b606c6adc6eda3275d8d4eec4b1/django-blockbee-1.0.7.tar.gz",
"platform": null,
"description": "[<img src=\"https://blockbee.io/static/assets/images/blockbee_logo_nospaces.png\" width=\"300\"/>](image.png)\n\n\n# BlockBee's Django Library\nDjango's implementation of BlockBee's payment gateway\n\n## Requirements:\n\n```\nPython >= 3.0\nDjango >= 2.0\nRequests >= 2.20\n```\n\n\n\n## Install\n\n\n```shell script\npip install django-blockbee\n```\n\n\n[on pypi](https://pypi.python.org/pypi/django-blockbee)\nor\n[on GitHub](https://github.com/blockbee-io/django-blockbee)\n\nAdd to INSTALLED_APPS:\n\n```python\nINSTALLED_APPS = (\n 'blockbee',\n ...\n)\n```\n\n\nRun migrations:\n\n```shell script\npython3 manage.py migrate blockbee\n```\n\nCollect static files:\n\n```shell script\npython3 manage.py collectstatic\n```\n\nAdd BlockBee's URLs to your project's urls.py file:\n\n```python\nurlpatterns = [\n path('blockbee/', include('blockbee.urls')),\n ...\n]\n```\n\nAdd your BlockBee API Key (obtained from our [Dashboard](https://dash.blockbee.io/)).\n\n```python \n\nBLOCKBEE_API_KEY = 'your_api_key'\n\n```\n\n## Configuration\n\nAfter the installation you need to set up Providers for each coin you wish to accept.\n\nYou need to go into your Django Admin and create a new BlockBee ``Provider`` for each coin with your cold wallet address where the funds will be forwarded to.\n\n## Usage\n\n### Creating an Invoice\n\nIn your order creation view, assuming ``user_order`` is your order object:\n\n* ##### If you want the address generated:\n\n```python\nfrom blockbee import Invoice\n\n...\n\n\ndef order_creation_view(request):\n ...\n invoice = Invoice(\n request=request,\n order_id=user_order.id,\n coin='btc',\n value=user_order.value\n )\n\n payment_address = invoice.address()\n\n if payment_address is not None:\n # Show the payment address to the user\n ...\n else:\n# Handle request error, check RequestLogs on Admin\n```\n\n* ##### If you want the `blockbee.models.Request` object:\n\n```python\nfrom blockbee import Invoice\n\n...\n\n\ndef order_creation_view(request):\n ...\n invoice = Invoice(\n request=request, # This if your view request. It's meant to create the callback URL\n order_id=user_order.id,\n coin='btc',\n value=user_order.value\n )\n\n payment_request = invoice.request()\n\n if payment_request is not None:\n # Show the payment address to the user\n ...\n else:\n# Handle request error, check RequestLogs on Admin\n```\n\n#### Where:\n\n``request`` is Django's view HttpRequest object \n\n``order_id`` is just your order id \n\n``coin`` is the ticker of the coin you wish to use, any of our supported coins (https://blockbee.io/cryptocurrencies/). You need to have a ``Provider`` set up for that coin. \n\n``value`` is an integer of the value of your order\n\n``apikey`` is the API Key that you got from your BlockBee Dashboard\n\n \n\n### Getting notified when the user pays\n\n```python\nfrom django.dispatch import receiver\nfrom blockbee.signals import payment_complete\n\n\n@receiver(payment_complete)\ndef payment_received(order_id, payment, value):\n # Implement your logic to mark the order as paid and release the goods to the user\n ...\n```\n\nWhere: \n\n``order_id`` is the id of the order that you provided earlier, used to fetch your order \n``payment`` is an ``blockbee.models.Payment`` object with the payment details, such as TXID, number of confirmations, etc. \n``value`` is the value the user paid\n\n\n#### Important:\n>\n>Don't forget to import your signals file. \n>\n>On your App's `apps.py` file:\n>\n>```python\n>class MyAppConfig(AppConfig):\n> name = 'MyApp'\n> \n> def ready(self):\n> super(MyAppConfig, self).ready()\n>\n> # noinspection PyUnresolvedReferences\n> import MyApp.signals\n>```\n>[django docs](https://docs.djangoproject.com/en/3.0/topics/signals/#django.dispatch.receiver)\n\n\n\n### Using our provided interface\n\nCreate a view in ``views.py``\n\n```python\ndef payment(_r, request_id):\n try:\n req = Request.objects.get(id=request_id)\n coin = req.provider.coin\n\n qrcode = get_qrcode(coin, req.address_in)\n\n fiat = get_conversion(coin, 'eur', req.value_requested)\n\n print(fiat)\n\n ctx = {\n 'req': req,\n 'qrcode': qrcode,\n 'fiat': fiat['value_coin']\n }\n\n return render(_r, 'payment.html', context=ctx)\n\n except Request.DoesNotExist:\n pass\n\n return redirect('store:request')\n```\nIn your template HTML\n\n```djangotemplate\n{% extends 'base.html' %}\n{% load blockbee_helper %}\n{% block content %}\n {% generate_payment_template %}\n{% endblock %}\n```\n\n \n\n\n### Helpers\n\nThis library has a couple of helpers to help you get started. They are present in the file ``utils.py``.\n\n``blockbee.valid_providers()`` is a method that returns a list of tuples of the active providers that you can just feed into the choices of a ``form.ChoiceField``\n\n``blockbee.get_order_invoices(order_id)`` returns a list of ``blockbee.models.Request`` objects of your order (you can have multiple objects for the same order if the user mistakenly initiated the payment with another coin or if he mistakenly didn't send the full payment)\n\n``blockbee.callback_url(_r, params)`` build your callback URL to provide to ``get_request``. Should be used inside a view since ``_r = request``\n\n \n\n### BlockBee Helper\n\nThis is the helper responsible for the connections ot the API itself. All these functions are in the ``blockbee.py`` file. \n\n``get_info(coin)`` returns the information of all cryptocurrencies or just if ``coin=''`` or a specific cryptocurrency if ``coin='ltc'`` for example. [docs](https://docs.blockbee.io/#operation/info)\n\n``get_supported_coins()`` returns all the support cryptocurrencies. You can consult them in this [list](https://blockbee.io/fees/). \n\n``get_logs(coin, callback_url)`` returns all the callback logs related to a request. ``callback_url`` should be the callback provided to our API. [docs](https://docs.blockbee.io/#operation/logs)\n\n``get_qrcode(coin, address, value, size)`` returns a PNG of a QR Code with the address for payment. [docs](https://docs.blockbee.io/tag/Bitcoin#operation/btcqrcode)\n\n``get_conversion(origin, to, value)`` returns the converted value in the parameter ``value_coin`` to the currency you wish, FIAT or Cryptocurrency.\n\n``get_estimate(coin)`` returns the estimation of the blockchain fees for the cryptocurrency specified in the parameter ``coin``. E.g: ``get_estimate('trc20_usdt')`` [docs](https://docs.blockbee.io/#operation/estimate)\n\n``get_address(coin, params)`` requests a payment address to BlockBee. Params include all the parameters that can be found [here](https://docs.blockbee.io/#operation/create). The parameter ``apikey`` is mandatory.\n\n \n\n### How to use the QR code (with address, coin and value)\n\nTo generate a QR Code you must use ``get_qrcode`` in your view and feed the parameters to your template. To generate a QR Code image you must place content of the API response after ``data:image/png;base64,{{qr_code}}`` so the browser generates the QR Code.\n```djangotemplate\n<img src=\"data:image/png;base64,{{ qrcode.qr_code }}\" alt=\"Payment QR Code\"/>\n```\n\nYou can also make the QR Code clickable.\n\n```djangotemplate\n<a href='{{ qrcode.payment_uri }}'>\n <img src=\"data:image/png;base64,{{ qrcode.qr_code }}\" alt=\"Payment QR Code\"/>\n</a>\n```\n\nYou can also add a value to the QR Code setting the ``value`` parameter to the value of your order (e.g ``0.2 LTC``). This may not function correctly in some wallets. **Use at your own risk.**\n\n## What is the Store application?\n\nWe made the ``store`` application to provide you with code examples on how to implement our service. It also has the code for our suggested UI (both CSS and HTML).\n\n\n## Help\n\nNeed help? \nContact us @ https://blockbee.io/contacts/\n\n\n### Changelog \n\n#### 1.0.0\n* Initial Release\n\n#### 1.0.1\n* Minor fixes\n* UI Improvements\n\n#### 1.0.2\n* Minor fixes\n\n#### 1.0.3\n* Minor fixes\n* Signals now use the value_coin\n* Removed deprecated fields from the payment model\n\n#### 1.0.4\n* Minor fixes\n\n#### 1.0.5\n* Minor fixes\n\n#### 1.0.6\n* Minor fixes\n\n#### 1.0.7\n* Minor fixes\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django implementation of BlockBee's payment gateway",
"version": "1.0.7",
"project_urls": {
"Homepage": "https://github.com/blockbee-io/django-blockbee"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2a24a9513decea4fc7a025450086178007cf4b606c6adc6eda3275d8d4eec4b1",
"md5": "0437d143d1cf5390fc05ebc9b1812a36",
"sha256": "c80dae31803b69fbc0d4d8293c7c5125383b45e61710d1054e2585769f0d8a97"
},
"downloads": -1,
"filename": "django-blockbee-1.0.7.tar.gz",
"has_sig": false,
"md5_digest": "0437d143d1cf5390fc05ebc9b1812a36",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 43789,
"upload_time": "2024-12-03T10:20:37",
"upload_time_iso_8601": "2024-12-03T10:20:37.756630Z",
"url": "https://files.pythonhosted.org/packages/2a/24/a9513decea4fc7a025450086178007cf4b606c6adc6eda3275d8d4eec4b1/django-blockbee-1.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-03 10:20:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "blockbee-io",
"github_project": "django-blockbee",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "django",
"specs": [
[
">=",
"3"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.20"
]
]
}
],
"lcname": "django-blockbee"
}
JSON
