Если вдруг что-то останется непонятным — напишите нам в поддержку: https://t.me/lava_sup_bot

Для того, чтобы начать настройку интеграции на платформе, потребуется создать API key и добавить webhook.

1. Перейдите в раздел Интеграции в основном меню, выберите тип интеграции Public API.

2. Нажмите Настроить API key.

3. Платформа создаст ключ автоматически: скопируйте и сохраните его на своём устройстве.

1. Создайте API key и подтвердите, что вы его сохранили.
2. Нажмите на кнопку Добавить Webhook.

3. Заполните поля:

• URL — это ссылка на сервис, куда будут отправляться webhook (сервер, который будет обрабатывать запросы);
• Тип события:

1. payment.success — Успешная оплата
2. payment.failed — Неуспешная оплата
3. subscription.recurring.payment.success — Успешное продление подписки
4. subscription.recurring.payment.failed — Неуспешное продление подписки
5. subscription.cancelled — Отмена подписки
6. refund.success — Успешный возврат
7. chargeback.initiated — Получен запрос на чарджбэк

4. Выберите тип аутентификации:

• Basic - введите логин и пароль от вашего сервиса, куда будут отправляться webhook.

• API key вашего сервиса - введите API key от вашего сервиса, куда будут отправляться webhook. Максимальная длина ключа — 80 символов.

Для этого нажмите на три точки рядом с нужным ключом и выберите Добавить Webhook.

Products - для работы с цифровыми продуктами: получение списка продуктов и изменение их параметров (например, цены).

Invoices — для создания контрактов на покупку (в том числе на произвольную сумму), проверки их статуса и настройки возврата покупателя на страницу автора после оплаты.
Доступны методы /api/v2/invoices и /api/v3/invoice

Custom Price Invoices - позволяет создать контракт на произвольную сумму для продуктов, опубликованных с признаком «Цена по запросу через API». Стоимость и валюта передаются в каждом запросе — без необходимости менять настройки продукта.

Reports - для получения данных для аналитики по продажам через API.

Subscriptions - для управления подписками пользователей.

Donate - для получения ссылок на донат.

1. укажите API key:

• нажмите кнопку Authorize в верхнем углу страницы:

• заполните ApiKeyAuth (apiKey), (используйте API key, который вы получили в ЛК Автора в пользовательском интерфейсе lava.top Интеграции → API → Создать API key (более подробно рассказывали про это здесь)):

2. нажмите кнопку Try it out, введите необходимые данные и выберите опцию Execute:

В интерфейсе lava.top при публикации Цифрового продукта, Консультации или Курса включите опцию «Цена по запросу API». Блок стоимости скроется. Продукт будет доступен только по ссылке и только через API.

Используйте метод POST /api/v3/invoice. Передайте offerId продукта, опубликованного с признаком «Цена по запросу», а также amount и currency в теле запроса.

1.curl --location 'https://gate.lava.top/api/v3/invoice' \
2.  --header 'Accept: application/json' \
3.  --header 'X-Api-Key: {api_key}' \
4.  --header 'Content-Type: application/json' \
5.  --data-raw '{
6.	"email": "client@example.com",
7.	"offerId": "836b9fc5-7ae9-4a27-9642-592bc44072b7",
8.	"currency": "EUR",
9.	"amount": 120
10.  }'

С указанием провайдера

1.curl --location 'https://gate.lava.top/api/v3/invoice' \
2.  --header 'Accept: application/json' \
3.  --header 'X-Api-Key: {api_key}' \
4.  --header 'Content-Type: application/json' \
5.  --data-raw '{
6.	"email": "client@example.com",
7.	"offerId": "836b9fc5-7ae9-4a27-9642-592bc44072b7",
8.	"currency": "EUR",
9.	"amount": 120,
10.	"paymentProvider": "PAYPAL"
11.  }'

Используйте метод POST /api/v3/invoice. Добавьте в тело запроса опциональные поля successful_return_url, failure_return_url, cancel_return_url. Можно передать любое подмножество — одно поле, два или все три.

Все три адреса

1.curl --location 'https://gate.lava.top/api/v3/invoice' \
2.  --header 'Accept: application/json' \
3.  --header 'X-Api-Key: {api_key}' \
4.  --header 'Content-Type: application/json' \
5.  --data-raw '{
6.    "email": "client@example.com",
7.    "offerId": "836b9fc5-7ae9-4a27-9642-592bc44072b7",
8.    "currency": "EUR",
9.    "successful_return_url": "https://school.example.com/thanks",
10.    "failure_return_url": "https://school.example.com/payment-error",
11.    "cancel_return_url": "https://school.example.com/checkout"
12.  }'

Только страница успешной оплаты

1.curl --location 'https://gate.lava.top/api/v3/invoice' \
2.  --header 'Accept: application/json' \
3.  --header 'X-Api-Key: {api_key}' \
4.  --header 'Content-Type: application/json' \
5.  --data-raw '{
6.    "email": "client@example.com",
7.    "offerId": "836b9fc5-7ae9-4a27-9642-592bc44072b7",
8.    "currency": "EUR",
9.    "paymentProvider": "PAYPAL",
10.    "successful_return_url": "https://school.example.com/thanks?utm_source=lava"
11.  }'

Требования к значениям:

• Только схема https
• Абсолютный URL
• Не более 512 символов на каждое поле

После оплаты покупатель сначала возвращается на страницу lava.top, а затем сразу переходит на ваш адрес.

Промежуточная страница показывает индикатор загрузки и не дублирует статус оплаты — результат покупатель уже видел в форме оплаты и увидит на вашей странице.

К вашему адресу мы добавляем два параметра:

• invoiceId — ID инвойса
• status — success / failed / cancelled

• Работает только для инвойсов, созданных через API. На прямые продажи через lava.top не распространяется
• Для подписок работает только на первой оплате. Продления выполняются без участия браузера
• Если автоматический переход не сработал, покупатель остаётся на нашей странице и видит ссылку для перехода вручную

Скачайте пакет с PyPI, обычно с помощью pip:

1.pip install lava-top-sdk

Убедитесь, что при установке библиотеки lava-top-sdk также устанавливаются все её зависимости.

Доступно на npm

1.npm install --save lava-top-sdk

Подключите пакет из репозитория Maven

1.<dependency>
2.	<groupId>top.lava</groupId>
3.	<artifactId>lava-top-kotlin-sdk</artifactId>
4.	<version>1.0.0</version>
5.</dependency>

Если webhook не были доставлены, система предпримет попытки повторно отправить их на указанный URL. Повторные попытки осуществляются по логике: сначала 1с, 5с, 15с, далее 10 попыток с интервалом в 1 мин, далее, если не удалось, еще 5 попыток с интервалом в 1 час.

Всего будет сделано до 20 попыток.

Историю можно найти в карточке аккаунта. Для этого перейдите в редактирование Интеграции → API → История веб-хуков (кнопка в правом верхнем углу страницы).

Здесь фиксируются события, на которые настроены соответствующие webhook. Эти события различаются по типу, статусу и паре API Key+webhook. В деталях платежа можно увидеть тело запроса, отправленного в момент события, а также историю попыток отправки (при неудачном списании по подписке webhook приходит только по последней попытке списания (т.е. если было 3 попытки списания, то webhook придет только по третей)). Чтобы просмотреть детали платежа, нужно кликнуть по строке webhook.

Чтобы найти нужный webhook можно использовать расширенные фильтры - искать по Почте покупателя, ID инвойса или Названию или ID продукта.

Каждое событие привязано к типу платежа и статусу контракта.

Типы платежей:

• оплата (покупка цифрового продукта, курса, консультации или первый платёж по подписке);
• рекуррентный платёж (продление или отмена подписки).

Статусы контракта:

• success (успешный платёж);
• failed (незавершённый платёж, например, недостаточно средств на балансе клиента);
• cancelled (отменённый, в случае подписки).

Поэтому в истории можно встретить следующие Типы событий:

• payment.success — успешная покупка продуктов (не донатов) или первая оплата подписки;
• payment.failed — неуспешная покупка продуктов (не донатов) или первая оплата подписки;
• subscription.recurring.payment.success — успешное продление подписки (второй, третий и последующие платежи);
• subscription.recurring.payment.failed — неуспешное продление подписки (второй, третий и последующие платежи);
• subscription.cancelled — отмена ранее купленной подписки;
• refund.success — возврат средств по продаже выполнен, полный или частичный;
• chargeback.initiated — покупатель открыл диспут через свой банк.

Чтобы получать события, создайте webhook и отметьте нужные события в поле «Тип события». Ограничений на комбинации нет: один webhook может принимать как одно событие, так и все семь. Соответствие позиций в форме и типов событий — в разделе «Настройка интеграции»:

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

Оба события приходят в общей обёртке. Тело события — в поле data, его состав зависит от типа события.

1.{
2.  "event_id": "7ea82675-4ded-4133-95a7-a6efbaf165cc",
3.  "event_type": "refund.success",
4.  "created_at": "2024-02-05T09:38:27.33277Z",
5.  "data": { }
6.}

Payload события refund.success

1.{
2.  "event_id": "7ea82675-4ded-4133-95a7-a6efbaf165cc",
3.  "event_type": "refund.success",
4.  "created_at": "2024-02-05T09:38:27.33277Z",
5.  "data": {
6.    "refund_id": "7ea82675-4ded-4133-95a7-a6efbaf165cc",
7.    "refund_type": "full",
8.    "initiator": "creator",
9.    "amount": 400.00,
10.    "currency": "EUR",
11.    "product": {
12.      "product_name": "Тестовый продукт",
13.      "product_id": "d31384b8-e412-4be5-a2ec-297ae6666c8f",
14.      "product_type": "DIGITAL_PRODUCT",
15.      "tier_id": "836b9fc5-7ae9-4a27-9642-592bc44072b7"
16.    },
17.    "customer_email": "test@lava.top",
18.    "balance_impact": {
19.      "debited_amount": 368.00,
20.      "currency": "EUR"
21.    },
22.    "subscription_cancelled": false
23.  }
24.}

Payload события chargeback.initiated

1.{
2.  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3.  "event_type": "chargeback.initiated",
4.  "created_at": "2024-02-05T09:38:27.33277Z",
5.  "data": {
6.    "chargeback_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
7.    "dispute_date": "2024-02-05",
8.    "reason_category": "fraud",
9.    "reason_description": "Fraudulent transaction",
10.    "amount": 400.00,
11.    "currency": "EUR",
12.    "product": {
13.      "product_name": "Тестовый продукт",
14.      "product_id": "d31384b8-e412-4be5-a2ec-297ae6666c8f",
15.      "product_type": "DIGITAL_PRODUCT",
16.      "tier_id": "836b9fc5-7ae9-4a27-9642-592bc44072b7"
17.    },
18.    "customer_email": "test@lava.top",
19.    "balance_impact": {
20.      "debited_amount": 400.00,
21.      "provider_fee": 40.00,
22.      "currency": "EUR"
23.    },
24.    "subscription_cancelled": false
25.  }
26.}

Статус показывает был ли получен webhook.

Может быть только два статуса:

• DELIVERED (доставлено) — webhook успешно доставлен.
• FAILED (не доставлено) — произошел сбой при доставке.

Статус webhook определяется HTTP-кодом, который поступает вместе с событием.

Платформа lava.top использует HTTP-коды ответа для обозначения успешного выполнения или ошибки при обработке API-запросов.

В случае получения кода о неудачной доставке lava.top повторяет попытки отправки до 19 раз.

Если webhook не были доставлены, система предпримет попытки повторно отправить их на указанный URL. Повторные попытки осуществляются по логике: сначала 1с, 5с, 15с, далее 10 попыток с интервалом в 1 мин, далее, если не удалось, еще 5 попыток с интервалом в 1 час.

Всего будет сделано до 20 попыток.

При каждой попытке отправить webhook в историю будет добавляться событие с соответствующим HTTP-кодом. Если статус-код указывает на успех, то появится одно событие об успешной или неуспешной оплате. При неуспешном ответе может быть до 20 попыток (они прекращаются после успешной отправки или после 19 попыток). Все эти события можно просмотреть в разделе «История попыток отправки» в деталях webhook. 

Наиболее популярные коды ответов:

• Код 401 / Код 403 — неверные данные авторизации, нельзя получить доступ к методу принятия webhook;
• Код 404 — в webhook прописан неверный URL
• Код 500 — ошибка на стороне сервера автора, который принимает webhook.

С помощью кнопки стрелки каждый webhook можно отправить повторно.

Нажмите и подтвердите отправку.

Добавлена возможность создания контракта на произвольную сумму через API.

Реализован метод POST /api/v3/invoice с поддержкой параметров amount и currency для продуктов, опубликованных с признаком «Цена по запросу через API».

Поддерживаемые типы контента: Цифровой продукт, Консультация, Курс.

Поддерживаемые валюты: RUB, USD, EUR. Тип контракта: ONE_TIME.

Обновлена навигация раздела «Интеграции».

В ЛК автора появился самостоятельный раздел «Интеграции» в боковом меню. Управление API-ключами и веб-хуками перенесено сюда из раздела Профиль. Навигационный путь: Интеграции → API.

Добавлена возможность оплаты подписок через Stripe.

Реализованы методы /api/v2/invoices и /api/v2/invoices/{id} с обновленной типизацией контрактов:

• INVOICE - оплата продуктов, консультаций, курсов,
• SUBSCRIPTION_FIRST_INVOICE - первое списание по подписке,
• SUBSCRIPTION_RENEWAL - рекуррентный платеж по подписке.

Добавлена возможность отправки донатов через Stripe.

Доработан запрос GET /invoices: теперь возвращается поле parentInvoiceId (ID родительской транзакции при оформлении подписки).

Добавлена возможностью оплаты через PayPal:

• оплата подписок,
• отправка доната.

Улучшен функционал работы с webkook:

• возможность повторной отправки,
• получение списка webhook,
• добавление типа (события) в тело webhook,
• возможность поиска webhook по Product ID в ЛК кабинете автора (Интеграции → API → История веб-хуков).

Добавлена поддержка UTM-меток.

Добавлена возможность оплаты цифровых продуктов через провайдера Stripe.