Как подключить оплату GetPlatinum к сайту через API v2 и выдавать доступ после платежа

API v2 позволяет оставить корзину на своём сайте и отправить покупателя на платёжную форму GetPlatinum. У сайта при этом две работы. Сначала сервер создаёт заказ и получает ссылку для покупателя. Позже он принимает от GetPlatinum отдельное уведомление с результатом платежа. По нему уже можно выдать доступ.

Выберите способ создания заказа

Когда цена, материалы и доступ в канал уже настроены в GetPlatinum, используйте POST /init-payment-url-by-offer. Метод берёт из предложения позиции, сумму, валюту и параметры подписки. Оплата останется связанной с предложением в кабинете. Если в предложении указан закрытый канал Telegram или MAX, сохранятся и настройки доступа. При необходимости сначала подготовьте предложение в кабинете.

Метод создания платёжной ссылки для готового предложения в API v2
Платёжная ссылка по готовому предложению. Стрелка 1 отмечает строку метода POST /init-payment-url-by-offer, стрелка 2 — поле offerId в образце запроса. Справа приведены демонстрационные значения из документации, а не данные покупателя.

Если содержимое корзины задаёт ваш сайт, используйте POST /init-payment-url. В этом случае сайт сам передаёт позиции и стоимость заказа. Оба метода возвращают адрес платёжной формы в поле formUrl. Отдельные запросы на создание заказа и выбор платёжной системы для этих двух методов не нужны.

Если сайт собран на конструкторе, посмотрите готовые инструкции для Tilda и для BotHelp.

Отправьте запрос с сервера сайта

API доступен после одобрения заявки организации. Откройте в GetPlatinum «Настройки», выберите организацию и скопируйте API-ключ. Храните его на сервере. К базовому адресу https://example.getplatinum.ru/api/public/v2/pay добавьте путь метода. Вместо example подставьте имя своего аккаунта. Отправьте JSON с заголовком Authorization: Bearer {API_KEY}.

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

  • offerId — число из столбца «Номер» в разделе «Предложения». Предложение должно принадлежать организации, чей ключ вы используете.
  • dealId — уникальный идентификатор заказа на вашем сайте. Сохраните его у себя до перехода покупателя на оплату.
  • clientParams — объект с данными покупателя. Передайте его идентификатор clientId и контакт для чека — email или телефон.
  • notificationUrl — адрес на вашем сервере, куда GetPlatinum отправит уведомления о создании заказа и результате платежа.

Для /init-payment-url-by-offer адреса переходов successUrl и failUrl необязательны. Если их пропустить, GetPlatinum возьмёт адреса из настроек предложения. Если для неуспешной оплаты адрес не задан и в кабинете, откроется стандартная страница GetPlatinum.

У /init-payment-url другой состав обязательных полей. Передайте dealId, amount, currency, positions, clientParams, notificationUrl и successUrl. Для каждой позиции укажите категорию prefix, наименование name, цену price, количество quantity и ставку НДС vat. Цены и сумму заказа передавайте в минимальных единицах валюты, например в копейках. Значение amount должно совпасть с суммой произведений цены на количество по всем позициям.

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

Разделите сообщения покупателю и уведомления серверу

За результат для сайта отвечает notificationUrl. За сообщение покупателю от GetPlatinum отвечает настройка «Уведомления для заказов, созданных по API». Она, в частности, нужна для отправки сообщения бота со ссылкой на канал, привязанный к предложению. Если эти сообщения отправляет сам проект, учтите это, когда будете настраивать уведомления покупателям.

Ещё одна настройка в кабинете называется «Webhook уведомления». Если она включена, GetPlatinum дополнительно отправляет уведомление на заданный там URL. Формат отличается. На этот URL в dealId приходит внутренний номер заказа GetPlatinum, а в теле есть поле checksum. Ниже разбираем обработчик для того адреса, который сайт передал в notificationUrl.

Проверьте подпись до разбора JSON

Считайте тело HTTP-запроса в исходном виде, как последовательность байтов. Вычислите HMAC-SHA256 с API-ключом организации, преобразуйте результат в шестнадцатеричную строку верхнего регистра и сравните с заголовком X-Checksum функцией безопасного сравнения. Для Python это выглядит так.

expected = hmac.new(api_key.encode(), raw_body, hashlib.sha256).hexdigest().upper()
valid = hmac.compare_digest(expected, received_checksum)

Здесь raw_body — байты запроса, received_checksum — значение заголовка, а hmac и hashlib — модули стандартной библиотеки Python. Разбирайте JSON после проверки подписи. Если пересобрать JSON перед расчётом HMAC, можно изменить пробелы или порядок полей и получить другую подпись.

Расчёт подписи уведомления HMAC-SHA256 в API v2
Проверка уведомления в API v2. Первая стрелка указывает на вычисление HMAC-SHA256 по исходному телу запроса, вторая — на сравнение с заголовком X-Checksum. Ниже показан официальный пример проверки на PHP.

Определите, какое событие пришло

Для обычной оплаты проверьте notificationType = 1 и isSuccess = true. Сопоставьте dealId с заказом на сайте, а сумму и валюту из paymentData — с ожидаемыми. При неуспешной оплате paymentData имеет значение null. Доступ выдавайте только после подтверждения успешного платежа. Событие с типом 7 сообщает всего лишь о создании заказа.

Для подписки используйте её собственные события. Тип 2 означает первую успешную оплату, тип 3 — успешное очередное списание. Если покупатель вернулся на successUrl до прихода уведомления, покажите ему состояние заказа из вашей системы. Сам переход по этому адресу оплату не подтверждает.

Обработайте повторную доставку один раз

После обработки верните HTTP-код 2xx. При другом коде или отсутствии ответа в течение 10 секунд GetPlatinum делает до трёх повторов — через 5 минут, 30 минут и 3 часа после предыдущей попытки. Тело и подпись при повторах сохраняются.

Учитывайте это в своей системе. Сохраняйте идентификатор уже обработанного платежа вместе с результатом, прежде чем подтверждать доставку. Для платёжной операции в paymentData передаётся mdOrder. Если уведомление относится к той же операции и доступ уже выдан, подтвердите приём без повторной выдачи. При подписке сверяйте саму операцию списания, чтобы очередное продление не отбросить как повтор предыдущего.

Сверьте результат с платёжной системой

При спорном результате отправьте POST /status с dealId вашего заказа или mdOrder платежа. Сразу после создания ссылки, до первой попытки оплаты, платёжные поля могут быть null, а isSuccess будет false. Проверьте этот случай отдельно от успешно оплаченного заказа.

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

Подключитесь к GetPlatinum

Принимайте оплату за свои товары и услуги

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

Зарегистрироваться в GetPlatinum

Подключаете оплату для клиентов?

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

Стать партнёром GetPlatinum