Колбэки: общая информация

Platega уведомляет вас об изменениях статуса платежа и подписки HTTP-запросом на ваш URL. Один URL на мерчанта, задаётся при подключении. Все колбэки, описанные в этом разделе, приходят на него.

Направление запроса обратное обычным методам API: не вы обращаетесь к Platega, а Platega отправляет POST на ваш сервер. Поэтому страницы раздела описывают запрос, который вы принимаете и обрабатываете, а адрес, указанный на них, — это ваш URL, а не наш.

Где указать URL

Личный кабинет, раздел Настройки → Callback URLs. Адрес один на все события: и на изменение статуса платежа, и на возвраты.

Требования к URL

✅ только HTTPS, HTTP запрещён;

✅ только публичный IP-адрес или доменное имя;

✅ действующий SSL-сертификат, выданный доверенным удостоверяющим центром;

❌ самоподписанные (self-signed) сертификаты не допускаются;

❌ приватные диапазоны 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8 запрещены;

❌ localhost и loopback-адреса запрещены.

Запрос

Метод POST, тело application/json; charset=utf-8.

Заголовки:

X-MerchantId — ваш идентификатор мерчанта;

X-Secret — ваш секретный ключ, по нему вы проверяете, что запрос наш;

User-Agent: Platega Payment.

Поля в теле — camelCase. Поля без значения не передаются вообще, а не приходят с null: например, в колбэке по обычному платежу не будет ни subscriptionId, ни refundId.

Ответ

Ответьте 200 OK. Тело ответа не разбираем.

Ошибка, таймаут или обрыв соединения считаются неудачной попыткой. Таймаут — 30 секунд.

Повторные попытки

Всего 3 попытки: первая сразу, затем через 5, 10 и 15 минут после неудачной.

Если неудачны все три, сам по себе колбэк больше не придёт. Отправить его повторно можно из личного кабинета — повтор доступен для платежей во всех статусах, которые вообще приходят в колбэках: CONFIRMED, CANCELED, CHARGEBACKED, PARTIALLY_REFUNDED и DISPUTED. Если повтор не проходит, обратитесь в поддержку. Текущий статус платежа всегда доступен запросом GET /transaction/{id}.

Идемпотентность и порядок

Обрабатывайте колбэки идемпотентно по полю id. Один и тот же статус может прийти повторно — это нормальная ситуация, а не ошибка: так бывает при повторной отправке и в нескольких штатных сценариях, описанных на страницах статусов.

Порядок доставки не гарантирован: колбэки отправляются параллельно, а у неудачных попыток свои задержки. Опирайтесь на статус в теле, а не на очерёдность получения.

Поля тела

Поле	Тип	Когда приходит
`id`	uuid	всегда. Для платежей — идентификатор платежа, для статусов подписки — идентификатор подписки
`amount`	number	всегда. Сумма платежа в валюте платежа
`currency`	string	всегда
`status`	string	всегда. См. страницы статусов
`paymentMethod`	integer	всегда для платежей. Код метода оплаты
`payload`	string	всегда. То, что вы передали при создании платежа; пустая строка, если не передавали
`paymentLinkId`	uuid	только если платёж создан по платёжной ссылке
`subscriptionId`	uuid	только для платежей по подписке и статусов подписки
`nextChargeAt`	date-time	только когда следующее списание определено
`refundId`	uuid	только по возвратам
`refundAmount`	number	сумма конкретной операции возврата
`refundedAmount`	number	сколько возвращено по платежу всего
`refundableAmount`	number	сколько ещё можно вернуть
`refundStatus`	string	`Succeeded` или `Declined`

Поле amount всегда остаётся суммой исходного платежа и после возврата не меняется — сколько возвращено и сколько ещё можно вернуть, смотрите в refundedAmount и refundableAmount.

Возвраты

Колбэк уходит на каждую завершённую операцию возврата, включая отклонённую провайдером. По одному платежу их будет столько, сколько было операций, и различать их нужно по refundId. Отклонённый возврат всей суммы колбэком не сопровождается.

Какие статусы приходят

Платежи: CONFIRMED, CANCELED, CHARGEBACKED, PARTIALLY_REFUNDED, DISPUTED.

Подписки: SUBSCRIPTION_ACTIVATED, SUBSCRIPTION_PAST_DUE, SUBSCRIPTION_CANCELLED, SUBSCRIPTION_FAILED — они описаны в разделе про подписки. В этих колбэках id — идентификатор подписки, а не платежа.

Статус PENDING в колбэках не приходит: платёж в этом статусе ещё ничем не завершился.

Тестовый запрос

Так выглядит наш запрос целиком. Этой командой можно проверить свой обработчик, подставив свой URL:

Это полное тело колбэка по обычному платежу: других полей в нём нет — ни subscriptionId, ни refundId, ни paymentLinkId. Они появляются только в сценариях, описанных на страницах статусов.

Колбэки — общая информация

Колбэки: общая информация#

Где указать URL#

Требования к URL#

Запрос#

Ответ#

Повторные попытки#

Идемпотентность и порядок#

Поля тела#

Возвраты#

Какие статусы приходят#

Тестовый запрос#