vkcoin

Билиотека для платёжного API VK Coin. Оффициальная документация: https://vk.com/@hs-marchant-api

После обновления 2.0 множество функций и классов изменило свой прежний вид. Миграция. Старая документация.

Установка

• Скачайте и установите Python версии 3.6 и выше, если он не установлен
• Введите следующую команду в командную строку:

pip install vkcoin

Если вы любите приключения, можно установить библиотеку с GitHub. В таком случае она может работать нестабильно:

pip install git+git://github.com/crinny/vkcoin.git

• Вы прекрасны!

Начало работы

Для начала разработки, необходимо создать исполняемый файл с расширением .py, например test.py. Вы не можете назвать файл vkcoin.py, так как это приведёт к конфликту. Теперь файл нужно открыть и импортировать библиотеку:

import vkcoin

merchant = vkcoin.VKCoin(user_id=123456789, key='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

Параметр	Тип	Описание
user_id	Integer	ID аккаунта ВКонтакте
key	String	Ключ для взаимодействия с API
token	String	Токен ВКонтакте для WebSocket

Методы

Необязательные параметры при вызове функций выделены курсивом.

get_payment_url - получет ссылку на оплату VK Coin

merchant.get_payment_url(amount=10, payload=78922, free_amount=False)
>>> https://vk.com/coin#m1625cf67_1_-298c0d20

Параметр	Тип	Описание
amount	Float	Количество VK Coin для перевода
payload	Integer	Число от -2000000000 до 2000000000, вернется в списке транзаций
free_amount	Boolean	True, чтобы разрешить пользователю изменять сумму перевода

get_transactions - получает список ваших транзакций

merchant.get_transactions(tx=[2])
>>> [{'id': 1000000, 'from_id': 371576679, 'to_id': 1, 'amount': '1', 'type': 2, 'payload': 0, 'external_id': 0, 'created_at': 1557241950}]

Параметр	Тип	Описание
tx	List	Массив ID переводов для получения или [1] - 1000 последних транзакций со ссылок на оплату, [2] — 100 последних транзакций на текущий аккаунт
last_tx	Integer	Если указать номер последней транзакции, то будут возвращены только транзакции после указанной

send_payment - делает перевод другому пользователю

result = merchant.send_payment(to_id, amount)
>>> {'id': 1000000, 'amount': 1, 'current': 1430}

Параметр	Тип	Описание
amount	Float	Сумма перевода
to_id	Integer	ID аккаунта, на который будет совершён перевод

get_balance - возвращает баланс аккаунта

merchant.get_balance(123456789, 987654321)
>>> {'371576679': 1430}

Тип	Описание
Integer	ID аккаунтов, баланс которых нужно получить (если не указывать ничего, то возвратится баланс текущего аккаунта)

set_shop_name - устанавливает название магазина

Обратите внимание что название может быть закешированно на срок до 5 часов. Сбросить кеш никак нельзя.

merchant.set_shop_name(name='Best Shop Ever')
>>> 1

Параметр	Тип	Описание
name	String	Новое название магазина

run_longpoll - запускает LongPoll

merchant.run_longpoll(tx=[1], interval=0.05)

Параметр	Тип	Описание
tx	List	Массив ID переводов для получения или [1] - 1000 последних транзакций со ссылок на оплату, [2] — 100 последних транзакций на текущий аккаунт
interval	Float	Частота опроса серверов на новые платежи в секундах

Callback

Оффициальный Callback. Поднимает сервер и принимает входящие запросы от VK Coin.

set_callback_endpoint - устанавливает Endpoint

merchant.set_callback_endpoint('0.0.0.0', 80)

Параметр	Тип	Описание
address	String	Адрес, на который будет поступать информация
port	Integer	Порт

remove_callback_endpoint - удаляет Endpoint

merchant.remove_callback_endpoint()

run_callback - запускает сервер для Callback

merchant.run_callback()

Пример использования

WebSocket

VKCoin для взаимодействия между клиентом и сервером использует протокол WebSocket. Данный класс реализован для получения обратных вызовов при входящих транзакциях на аккаунт, доступ к которому должен быть предоставлен токеном в классе VKCoin:

Для получения токена - перейдите по ссылке, нажмите "Разрешить" и скопируйте часть адресной строки после access_token= и до &expires_in (85 символов)

Если при использовании способа выше вы получаете ошибку, перейдите по ссылке: https://oauth.vk.com/token?grant_type=password&client_id=2274003&client_secret=hHbZxrka2uZ6jB1inYsH&username=LOGIN&password=PASSWORD, перед этим заменив login и password на ваш логин и пароль. После перехода по этой ссылке вам будет выдан расширенный токен.

После инициализации объекта необходимо зарегистрировать функцию, которая будет обрабатывать входящие платежи. Для этого используется декоратор payment_handler

@merchant.payment_handler(handler_type='websocket')
def your_func(data):
	pass

При получении обратного вызова - входящей транзакции - в зарегестрированную функцию возвращается словарь, который является абстракцией входящего перевода и содержит следующие параметры:

data['to_id']  # ваш ID
data['from_id']  # ID отправителя (инициатор входящей транзакции)
data['amount']  # количество полученных коинов
data['payload']  # Payload

Пример использования

Longpoll

Постоянно опрашивает сервер на наличие новых платежей и при поступлении таковых, оповещает об этом через декоратор.

После инициализации объекта необходимо зарегистрировать функцию, которая будет обрабатывать входящие платежи. Для этого используется декоратор payment_handler

@merchant.payment_handler(handler_type='longpoll')
def your_func(data):
	pass

При получении обратного вызова - входящей транзакции - в зарегестрированную функцию возвращается словарь, который является абстракцией входящего перевода и содержит следующие параметры:

data['to_id']  # ваш ID
data['id']  # ID платежа
data['balance']  # баланс вашего аккаунта 
data['from_id']  # ID отправителя (инициатор входящей транзакции)
data['amount']  # количество полученных коинов
data['created_at']  # Unix Timestamp, когда был совершён перевод

Пример использования

Примеры

Примеры расположены в отдельной папке репозитория.