Необходимость добавить возможность оплаты чего-либо в своём проекте всплывает достаточно часто, при этом возня с ИП, банковскими договорами и прочей бюрократией мало кого привлекает, особенно если масштабы проекта сопоставимы с небольшим telegram-ботом или чем-то подобным. На помощь приходят такие сервисы как QIWI, ЮMoney и другие (не рекламирую, просто нахожу удобным для себя).

Подход прочитать документацию API такого сервиса, написать небольшой модуль и использовать в своих проектах - лучший путь, но начинающие программисты зачастую находят это нудным, сложным и ищут простое готовое решение. Так и я решил когда-то и не нашёл, а теперь вместо переписывания одного модуля по 100 раз решил собрать небольшую библиотеку для быстрой интеграции платежей QIWI.

Установка

В терминале пишем команду и ожидаем конца загрузки:

pip install PyEasyQiwi

Создание платежа

Для начала импортируем класс для создания соединения с QIWI аккаунтом:

from PyEasyQiwi import QiwiConnection

Конструктор класса принимает один аргумент - ваш секретный API ключ, для начала нам понадобится аккаунт QIWI со статусом "Основной", так как сервис запрещает проводить анонимные платежи. Авторизуемся на сайте:

Далее в верхней панели переходим по вкладкам: Ещё > Приём переводов

Нажимаем "Начать приём платежей" и в верхней панели переходим в создание API ключей

Настраиваем новую пару ключей, дав ей любое название:

На этом этапе копируем и сохраняем ваш секретный ключ (тот что на оранжевом фоне), далее возможности посмотреть его снова не будет. Не забывайте, что секретный ключ даёт доступ к вашему аккаунту без логинов, паролей и прочего, храните его надёжно и не передавайте третьим лицам. В случае если такое произошло, в этом же разделе можно удалить ранее созданные ключи.

Теперь, когда мы получили API ключ, вернёмся к коду.

Создадим подключение указав наш секретный ключ:

api_key = "your_api_key"
conn = QiwiConnection(api_key)

Теперь мы можем использовать экземпляр класса для управления приёмом платежей, начнём с создания счёта на оплату для нашего пользователя, используем метод conn.create_bill()

pay_url, bill_id, response = conn.create_bill(value=1000.00, description="User1")
print(pay_url)

>>> https://oplata.qiwi.com/form/?...

pay_url - строка содержащая ссылку для оплаты (для отправки клиенту или редиректа)

bill_id - строка содержащие полное наименование счёта на оплату, состоит из текста указанного в conn.create_bill(..., description="User1") и полной даты создания платежа. (для идентификации каждого отдельно взятого платежа, фактически его ID в вашей базе данных)

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

Теперь перейдём по ссылке в pay_url и увидим страницу с формой для оплаты любым удобным из доступных методов:

Так же все операции проведённые через API отобразятся в сервисе:

Конечно, наш метод позволяет более гибко настроить то, что пользователь увидит на данной странице, разберём по порядку все доступные опции:

conn.create_bill(value, currency, delay, description, theme_code, comment, qiwi_pay, card_pay)

1. value - Обязательный аргумент, сумма для оплаты. Например 100.59. Допустимые значения 1-1000000 (QIWI ограничивает транзакции на сумму более 1000000 рублей).

2. currency - Валюта для проведения платежа. По умолчанию RUB, доступны варианты "RUB" и "KZT".

3. delay - Срок действия платежа в минутах. По умолчанию 15 минут. Устанавливает максимальный временной промежуток для оплаты пользователем, после чего закрывает возможность оплаты.

4. description - Описание платежа, по умолчанию - unknown. Используется для более точной идентификации каждого платежа. Разумно использовать ID пользователя из вашей базы данных.

5. theme_code - Уникальный код оформления страницы платежа. По умолчанию - пустое значение. Подробнее - далее в статье.

6. comment - Комментарий который увидит пользователь при оплате. По умолчанию - пустая строка.

7. qiwi_pay - Возможность оплаты с кошелька QIWI для пользователя. По умолчанию True.

8. card_pay - Возможность оплаты банковской картой для пользователя. По умолчанию True.

Более полный пример создания платежа

Для начала разберёмся с параметром theme_code:

Этот параметр позволяет задать своё (на сколько это возможно) оформление страницы оплаты, и сервис QIWI предлагает небольшой инструмент для настройки кода персонализации: перейдя по ссылке настраиваем всё по своему желанию и сохраняем наш код, позже передадим его в качестве аргумента.

Теперь когда у нас есть всё необходимое попробуем создать новый счёт на оплату, используя всё тот же метод conn.create_bill():

value = 3010.11
currency = "RUB"
delay = 30
description = "test_user_ID"
theme_code = "my_code"
comment = "Привет Хабр!"
qiwi_pay = False
card_pay = True


pay_url, bill_id, response = conn.create_bill(value, currency, delay, description, theme_code, comment, qiwi_pay, card_pay)
print("Ссылка для оплаты: ", pay_url)

>>> https://oplata.qiwi.com/form/?..............

Проверяем, мы отключили оплату с кошелька QIWI, установили код персонализации и добавили комментарий:

Проверка статуса платежа

Вообще, откровенно говоря, сервис умеет присылать ответ на ваш сервер как только один из счетов будет оплачен, но я не успел реализовать это в библиотеке это несёт за собой определённые сложности. Поэтому в данной статье я рассмотрю пример ручной проверки статуса платежа, что в целом - вполне будет решать поставленную задачу не забивая голову болью об обработке ответа на сервер и тд.

В качестве примера возьмём счёт на оплату созданный выше, как вы помните метод conn.create_bill() вернул нам bill_id , он нам и понадобится для отслеживания статуса.

status, response = conn.check_bill(bill_id)
print(status)

>>> WAITING 

status - строка содержащая статус платежа: WAITING - счёт ожидает оплаты, PAID - счёт ожидает оплаты, REJECTED - счёт отклонён, EXPIRED - срок оплаты просрочен (Используется для проверки статуса оплаты)

response - словарь с более подробной информацией о счёте

Теперь у нас есть точное понимание, в каком состоянии находится выставленный счёт, как использовать это в своих проектах - решать вам, простейший пример использования:

status, response = conn.check_bill(bill_id)

if status == "PAID":
  # Пользователь оплатил
else:
  # Пользователь не оплатил

Отмена выставленных платежей

Помимо выставления платежей, надо уметь их отменять. Зачем хранить открытым счёт на оплату если пользователь уже сообщил вам (нажав кнопку отмена или например закрыв приложение), потенциально это всегда может привести к неожиданному результату - поэтому хорошей практикой будет закрыть счёт и забыть про него.

Для этого нам всё так же понадобится ID счёта, в нашем случае bill_id и новый метод conn.remove_bill()

conn.remove_bill(bill_id)

Данный метод ничего не возвращает, но если мы попробуем перейти по ссылке для оплаты которую создавали ранее, то увидим следующее:

Так же при проверке статуса платежа будет понятно, что он уже недействителен:

status, response = conn.check_bill(bill_id)
print(status)

>>> REJECTED 

Оплаченный или просроченный счёт закрывать не требуется:

Для ленивых

Небольшой пример для создания платежа со всеми возможными настройками, проверки его статуса, и закрытия этого счёта.

from PyEasyQiwi import QiwiConnection

# Создаём подключение
api_key = "your_api_key"
conn = QiwiConnection(api_key)

# Создаём счёт на оплату
value = 500.01
currency = "RUB"
delay = 30
description = "test_user_ID"
theme_code = "my_code"
comment = "PyEasyQiwi"
qiwi_pay = False
card_pay = True


pay_url, bill_id, response = conn.create_bill(value, currency, delay, description, theme_code, comment, qiwi_pay, card_pay)
print("Ссылка для оплаты: ", pay_url)


# Проверяем статус платежа
status, response = conn.check_bill(bill_id)
print("Текущий статус платежа:", status)

# Закрываем счёт на оплату
conn.remove_bill(bill_id)
print("Счёт закрыт!")

Заключение

На этом всё, буду рад если найдёте это полезным для себя. Адекватная критика всегда приветствуется, это мой первый опыт написания статей, так что не судите строго, старался для людей! Ссылки на документацию ниже: