feat: add PayKilla payment provider

2026-06-04 13:32:15 +03:00
parent 1ccda9ebd1
commit c46aaad7e3
20 changed files with 1974 additions and 8 deletions
@@ -197,7 +197,7 @@

 | Переменная | Назначение |
 | --- | --- |
-| `PAYMENT_METHODS_ORDER` | Порядок кнопок оплаты: `severpay,wata,freekassa,platega,yookassa,stars,cryptopay,heleket`. |
+| `PAYMENT_METHODS_ORDER` | Порядок кнопок оплаты: `severpay,wata,freekassa,platega,yookassa,stars,cryptopay,heleket,paykilla`. |
 | `SUBSCRIPTION_PURCHASE_DESCRIPTION_ENABLED` | Показывать описание подписки перед выбором срока. |
 | `SUBSCRIPTION_PURCHASE_DESCRIPTION_RU` / `SUBSCRIPTION_PURCHASE_DESCRIPTION_EN` | Локализованное описание подписки. |
 | `PAYMENT_<METHOD>_WEBAPP_LABEL_RU` / `PAYMENT_<METHOD>_WEBAPP_LABEL_EN` | Текст кнопки провайдера в Web App. |
@@ -213,6 +213,7 @@
 | `WATA_ENABLED` | Включает Wata. |
 | `CRYPTOPAY_ENABLED` | Включает CryptoPay. |
 | `HELEKET_ENABLED` | Включает Heleket. |
+| `PAYKILLA_ENABLED` | Включает PayKilla. |

 Конкретные ключи отображения:

@@ -271,6 +272,12 @@ PAYMENT_HELEKET_WEBAPP_ICON
 PAYMENT_HELEKET_TELEGRAM_LABEL_RU
 PAYMENT_HELEKET_TELEGRAM_LABEL_EN
 PAYMENT_HELEKET_TELEGRAM_EMOJI
+PAYMENT_PAYKILLA_WEBAPP_LABEL_RU
+PAYMENT_PAYKILLA_WEBAPP_LABEL_EN
+PAYMENT_PAYKILLA_WEBAPP_ICON
+PAYMENT_PAYKILLA_TELEGRAM_LABEL_RU
+PAYMENT_PAYKILLA_TELEGRAM_LABEL_EN
+PAYMENT_PAYKILLA_TELEGRAM_EMOJI
 ```

 ### YooKassa
@@ -357,6 +364,33 @@ PAYMENT_HELEKET_TELEGRAM_EMOJI
 | `HELEKET_VERIFY_WEBHOOK_SIGNATURE` | Проверять подпись webhook. |
 | `HELEKET_TRUSTED_IPS` | Список доверенных IP webhook-источников. |

+### PayKilla
+
+Для приема оплат нужен API key типа **HMAC** с правом **INVOICE**. Право **WITHDRAWAL** для оплаты подписок не требуется; включайте его только для отдельной интеграции выплат.
+
+Webhook настраивается в PayKilla Dashboard: **Settings -> Webhooks**. Укажите `WEBHOOK_BASE_URL` + `/webhook/paykilla`, например `https://bot.example.com/webhook/paykilla`. Включите события `INVOICE_PAID` и `INVOICE_EXPIRED` как минимум. Рекомендуемый набор галочек: `INVOICE_PAID`, `PAYMENT_COMPLETED`, `PAYMENT_FAILED`, `PAYMENT_OVERPAID`, `PAYMENT_UNDERPAID`, `PAYMENT_PARTIAL`, `INVOICE_EXPIRED`, `COMPLIANCE_FAILED`. Если хотите видеть промежуточные статусы в логах PayKilla, дополнительно включите `INVOICE_CREATED`, `PAYMENT_PENDING`, `TRANSACTION_CONFIRMED` и `TRANSACTION_FINAL`.
+
+| Переменная | Назначение |
+| --- | --- |
+| `PAYKILLA_BASE_URL` | Базовый URL API, по умолчанию `https://account-api.paykilla.com`. |
+| `PAYKILLA_WIDGET_URL` | URL hosted checkout, по умолчанию `https://gopay.paykilla.com`. |
+| `PAYKILLA_API_KEY` / `PAYKILLA_V2_API_KEY` | Public HMAC key с правом `INVOICE`. |
+| `PAYKILLA_SECRET_KEY` / `PAYKILLA_V2_SECRET_KEY` | Secret HMAC key для подписи API-запросов и проверки webhook. |
+| `PAYKILLA_CURRENCY` | Валюта инвойса. Для RUB/USD/EUR/AED/GBP используется `FIAT_BASED`, для остальных - `FIXED_AMOUNT`. |
+| `PAYKILLA_PAYMENT_CURRENCIES` | Crypto tickers для оплаты, например `USDTTRC,BTC,ETH`. |
+| `PAYKILLA_SUPPORTED_CURRENCIES` | Валюты инвойса, разрешенные в этом магазине. |
+| `PAYKILLA_INVOICE_TYPE` | Необязательный override: `FIAT_BASED`, `FIXED_AMOUNT` или `OPEN_AMOUNT`. |
+| `PAYKILLA_RETURN_URL` | URL кнопки возврата на checkout-странице. |
+| `PAYKILLA_SUCCESS_URL` | URL после успешной оплаты; используется с auto-redirect. |
+| `PAYKILLA_CANCEL_URL` | URL после отмены оплаты. |
+| `PAYKILLA_LIFETIME_SECONDS` | TTL инвойса, отправляется как `expiredAt`. |
+| `PAYKILLA_RECV_WINDOW_MS` | `recvWindow` для подписанных API-запросов. |
+| `PAYKILLA_USER_PAYS_SERVICE_FEE` | `true`, если пользователь оплачивает service fee. |
+| `PAYKILLA_USER_PAYS_NETWORK_FEE` | `true`, если пользователь оплачивает network fee. |
+| `PAYKILLA_VERIFY_WEBHOOK_SIGNATURE` | Проверять `X-API-SIGN` по raw body webhook. |
+| `PAYKILLA_WEBHOOK_URL` | Точный публичный webhook URL для проверки подписи, если он отличается от `WEBHOOK_BASE_URL` + `/webhook/paykilla`. |
+| `PAYKILLA_TRUSTED_IPS` | Необязательный список доверенных IP webhook-источников. |
+
 ## Тарифы и legacy-цены

 Рекомендуемый способ настройки тарифов - раздел **Система -> Тарифы** в админке. Он сохраняет JSON в `TARIFFS_CONFIG_PATH`.
@@ -31,6 +31,7 @@
 | Wata | `WEBHOOK_BASE_URL` + `/webhook/wata` | Если включена проверка подписи, настройте `WATA_WEBHOOK_VERIFY_SIGNATURE` и `WATA_PUBLIC_KEY`. |
 | CryptoPay | `WEBHOOK_BASE_URL` + `/webhook/cryptopay` | Указывается в настройках Crypto Bot / CryptoPay webhook. |
 | Heleket | `WEBHOOK_BASE_URL` + `/webhook/heleket` | При необходимости включите `HELEKET_VERIFY_WEBHOOK_SIGNATURE` и `HELEKET_TRUSTED_IPS`. |
+| PayKilla | `WEBHOOK_BASE_URL` + `/webhook/paykilla` | Указывается в PayKilla Dashboard -> Settings -> Webhooks; включите события оплаты инвойсов. |
 | Telegram Stars | Отдельный платежный webhook не нужен | Stars-события приходят через webhook Telegram-бота: `WEBHOOK_BASE_URL` + `/tg/webhook`. |

 После настройки сделайте тестовый платеж и проверьте, что в логах `backend` видно входящий `POST` на нужный путь. Если провайдер сообщает, что адрес недоступен, сначала проверьте DNS/HTTPS и reverse proxy для `WEBHOOK_BASE_URL`, затем убедитесь, что путь начинается ровно с `/webhook/...` без `/api`, `/auth` и frontend-домена.
@@ -153,6 +154,37 @@ Heleket используется для крипто-инвойсов с отд

 Справочник переменных: [Heleket](../configuration/env-vars.md#heleket).

+## PayKilla
+
+PayKilla используется для крипто-инвойсов V2 через hosted checkout `https://gopay.paykilla.com/{invoice_id}`. API-запросы подписываются HMAC-SHA256, webhook проверяется по заголовку `X-API-SIGN` и raw body.
+
+Какие полномочия нужны API key:
+
+1. В PayKilla Dashboard откройте **Settings -> API keys**.
+2. Создайте ключ типа **HMAC**.
+3. Для приема оплат включите permission **INVOICE**.
+4. Permission **WITHDRAWAL** не нужен для Minishop-платежей; не включайте его без отдельной необходимости выплат.
+5. Сохраните `publicKey` в `PAYKILLA_API_KEY`, а `secretKey` в `PAYKILLA_SECRET_KEY`.
+
+Как настроить webhook в PayKilla:
+
+1. Откройте **Settings -> Webhooks**.
+2. В URL укажите `WEBHOOK_BASE_URL` + `/webhook/paykilla`, например `https://bot.example.com/webhook/paykilla`.
+3. Минимальные галочки: `INVOICE_PAID`, `INVOICE_EXPIRED`.
+4. Рекомендуемые галочки для production: `INVOICE_PAID`, `PAYMENT_COMPLETED`, `PAYMENT_FAILED`, `PAYMENT_OVERPAID`, `PAYMENT_UNDERPAID`, `PAYMENT_PARTIAL`, `INVOICE_EXPIRED`, `COMPLIANCE_FAILED`.
+5. Опционально включите `INVOICE_CREATED`, `PAYMENT_PENDING`, `TRANSACTION_CONFIRMED` и `TRANSACTION_FINAL`, если нужны промежуточные события в логах.
+6. Оставьте `PAYKILLA_VERIFY_WEBHOOK_SIGNATURE=True`. Если публичный URL у PayKilla отличается от `WEBHOOK_BASE_URL` + `/webhook/paykilla`, задайте точное значение в `PAYKILLA_WEBHOOK_URL`.
+
+Что настроить в Minishop:
+
+1. Включите `PAYKILLA_ENABLED`.
+2. Укажите `PAYKILLA_API_KEY` и `PAYKILLA_SECRET_KEY`.
+3. Проверьте `PAYKILLA_CURRENCY` и `PAYKILLA_PAYMENT_CURRENCIES`, например `USDTTRC,BTC,ETH`.
+4. При необходимости задайте `PAYKILLA_SUCCESS_URL`, `PAYKILLA_RETURN_URL` и `PAYKILLA_CANCEL_URL`.
+5. Добавьте `paykilla` в `PAYMENT_METHODS_ORDER`, если хотите задать явный порядок кнопок.
+
+Справочник переменных: [PayKilla](../configuration/env-vars.md#paykilla).
+
 ## Telegram Stars

 Telegram Stars используются напрямую и поддерживаются в legacy-ценах и JSON-каталоге тарифов.
@@ -46,7 +46,7 @@ App, а не веб-кабинетом Remnashop. В Minishop `SUBSCRIPTION_MINI

 Платежные провайдеры берутся из таблицы Remnashop `payment_gateways`.
 Поддерживаются и автоматически маппятся: Telegram Stars, YooKassa, WATA,
-CryptoPay, Heleket, FreeKassa и Platega. Для них importer переносит флаги
+CryptoPay, Heleket, PayKilla, FreeKassa и Platega. Для них importer переносит флаги
 включения, API-ключи/merchant IDs и прямые технические параметры, без которых
 провайдер не сможет работать: YooKassa receipt email/VAT, FreeKassa second
 secret/payment method/server IP и Platega payment method.
@@ -55,7 +55,8 @@ Provider currency и supported-currency ограничения не перено
 в Minishop валюта платежа управляется тарифами и `DEFAULT_CURRENCY_SYMBOL`.
 Если старый gateway Remnashop был настроен на нестандартную валюту, importer
 оставит предупреждение в JSON-сводке; проверьте `CRYPTOPAY_ASSET`,
-`HELEKET_CURRENCY`, `HELEKET_SUPPORTED_CURRENCIES` или
+`HELEKET_CURRENCY`, `HELEKET_SUPPORTED_CURRENCIES`, `PAYKILLA_CURRENCY`,
+`PAYKILLA_PAYMENT_CURRENCIES` или
 `PLATEGA_SUPPORTED_CURRENCIES` вручную.

 Провайдеры YooMoney, Cryptomus, MulenPay, PayMaster, RoboKassa и UrlPay сейчас
@@ -77,6 +78,7 @@ Remnashop может хранить секреты в формате `enc_...`.
 - WATA webhook/callback URL: `WEBHOOK_BASE_URL` + `/webhook/wata`;
 - CryptoBot/Crypto Pay webhook URL: `WEBHOOK_BASE_URL` + `/webhook/cryptopay`;
 - Heleket payment webhook/callback URL: `WEBHOOK_BASE_URL` + `/webhook/heleket`;
+- PayKilla webhook URL: `WEBHOOK_BASE_URL` + `/webhook/paykilla`;
 - FreeKassa notification/result URL: `WEBHOOK_BASE_URL` + `/webhook/freekassa`;
 - Platega webhook URL: `WEBHOOK_BASE_URL` + `/webhook/platega`;
 - Telegram webhook `WEBHOOK_BASE_URL` + `/tg/webhook` выставляется ботом