Обработчик платежа

Обработчик платежей — это URL вашего сервера, на который Unitpay отправляет серверные GET-запросы о ходе платежа. Через эти запросы вы можете:

• проверить заказ до оплаты;

• подтвердить, что заказ существует и может быть оплачен;

• автоматически выдать товар, оказать услугу или зачислить баланс после успешного списания;

• получать уведомления об ошибках по платежу.

Важно: если URL обработчика не указан, callback-запросы не отправляются, а платеж считается успешным автоматически.

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

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

Что считается корректным URL

URL обработчика будет сохранен, если:

• используется протокол http или https;

• указан валидный домен;

Примеры корректных URL

• https://example.com/payment-handler

• https://api.example.com/unitpay/callback

• http://merchant-service.net/pay

• https://xn--e1afmkfd.xn--p1ai/handler

Примеры некорректных URL

• ftp://example.com/callback — недопустимый протокол

• https://127.0.0.1/callback — IP-адрес вместо домена

• https://user:[email protected]/callback — встроенные данные авторизации

Как это работает

Обычно сценарий такой:

1. Покупатель начинает оплату.

2. Unitpay может отправить check, чтобы проверить заказ до списания.

3. После успешного списания Unitpay отправляет pay.

4. Если на одном из этапов возникла ошибка, может прийти error.

5. Для платежей с преавторизацией сначала может прийти preauth.

Важно: при preauth деньги только заблокированы. Товар, услугу или баланс нужно выдавать только после успешного списания.

Важно: error не всегда означает окончательный статус. После error в некоторых случаях позже может прийти pay.

Что нужно реализовать на своей стороне

Ваш обработчик должен:

• принимать GET-запросы от Unitpay;

• проверять IP-адрес отправителя;

• проверять signature;

• сверять orderSum и orderCurrency с данными заказа;

• на этапе check только проверять заказ;

• на этапе pay выдавать товар, оказывать услугу или зачислять баланс;

• корректно обрабатывать повторные запросы;

• возвращать JSON в нужном формате.

Важно: unitpayId — это уникальный идентификатор платежа в Unitpay. Если запрос с тем же unitpayId приходит повторно, не обрабатывайте платеж заново: не выдавайте товар повторно, не оказывайте услугу повторно и не зачисляйте баланс еще раз.

Методы

CHECK

Запрос на проверку заказа до оплаты.

На этом этапе нужно убедиться, что:

• заказ существует;

• сумма и валюта совпадают;

• заказ можно оплатить;

• после успешной оплаты услугу можно оказать.

Важно: на этапе check не нужно выдавать товар, оказывать услугу или зачислять баланс.

По умолчанию на новом проекте запрос CHECK выключен. Чтобы использовать его, включите эту опцию в настройках проекта.

PAY

Уведомление об успешном списании средств.

Именно на этом этапе нужно:

• выдать товар;

• оказать услугу;

• зачислить баланс;

• сохранить результат обработки платежа.

Если на этом этапе ваш сервер вернет ошибку, платеж получит статус «Не завершен». После устранения проблемы платеж можно повторно провести из интерфейса статистики.

Важно: деньги зачисляются на баланс партнера независимо от ответа обработчика.

Важно: обработка pay должна быть идемпотентной. Повторный запрос не должен приводить к повторной выдаче товара или повторному зачислению.

PREAUTH

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

Важно: не выдавайте товар и не оказывайте услугу при получении preauth. Делать это нужно только после успешного списания.

ERROR

Уведомление об ошибке на одном из этапов платежа.

Если ошибка вызвана пустым или некорректным ответом сервера партнера, запрос error может не отправляться.

Важно: error не всегда является конечным статусом. После него иногда может прийти pay.

Формат запроса

Unitpay отправляет GET-запрос на URL вашего обработчика.

Пример:

GET https://адрес_вашего_обработчика

method               = check
params[account]      = userId
params[date]         = 2025-10-01 12:32:00
params[paymentType]  = card
params[projectId]    = 123456
params[payerSum]     = 10.00
params[payerCurrency]= RUB
params[signature]    = 9bdf52a4830779a1383ac24f1b3ed054
params[orderSum]     = 10.00
params[orderCurrency]= RUB
params[unitpayId]    = 1234567890
params[test]         = 0

Параметры запроса

Параметр	Значение	Описание
method	string	Тип запроса: check, pay, preauth, error
unitpayId	число	Внутренний номер платежа в UnitPay
projectId	число	ID проекта в UnitPay
account	string	Идентификатор пользователя или заказа в вашей системе
payerSum	число	Сумма списания с лицевого счета абонента
sum	число	Сумма списания с лицевого счета абонента (дополнительное значение)
ip	string	IP-адрес плательщика (с которого инициировано создание платежа)
isPreauth	число	Признак преавторизации: 1 — да, 0 — нет
payerCurrency	string	Валюта списания с лицевого счета абонента по стандарту ISO 4217 (RUB, BYN, EUR, USD)
profit	число	Ваш доход с данного платежа, в рублях
paymentType	string	Код платежной системы
orderSum	число	Сумма заказа Обязательно сверяйте поступившее значение с оригинальной суммой заказа
orderCurrency	string	Валюта заказа по стандарту ISO 4217 (RUB, BYN, EUR, USD) Обязательно сверяйте поступившее значение с оригинальной валютой заказа
date	string	Дата платежа в формате YYYY-mm-dd HH:ii:ss (например 2024-10-01 12:32:00)
errorMessage	string	Детализация ошибки (только для метода error)
test	число	Признак тестового режима: 1 — тест, 0 — реальный платеж
3ds	число	Признак наличия 3-DS для операций по карте, флаг присутствует при PAY уведомлениях
subscriptionId	число	Идентификатор подписки, может приходить в preauth и pay
signature	string	Цифровая подпись. Образуется как sha256(method + "{up}" + params + "{up}" + secretKey), где sha256 - метод шифрования; "{up}" - разделитель параметров в хеш-функции; method - тип вызова (check, pay, error); params - значения параметров из массива params, объединенные разделителем "{up}". Все параметры должны быть предварительно отсортированы по ключу, в склейке не участвует параметр signature; secretKey - секретный ключ проекта (доступен в личном кабинете); Пример расчета подписи для запроса http://partnerUrl?method=check & params[b]=bob & params[c]=sam & params[a]=tod и секретного ключа "a1b1c1d1" sha256 ("check{up}tod{up}bob{up}sam{up}a1b1c1d1")

Успешный ответ

Если запрос обработан успешно, верните:

{
    "result": {
        "message": "Запрос успешно обработан"
    }
}

Параметр	Значение	Описание
message	string	Текстовый статус выполнения запроса.

Ошибочный ответ

Если запрос не может быть обработан, верните:

{
    "error": {
        "message": "Описание ошибки"
    }
}

message	string	Информация с описанием ошибки формирования платежа. При использовании формы оплаты текст из параметра "message" будет показан плательщику.
locale	string	Настраивает язык вводной части. Возможные значения: "en" или "ru". По умолчанию "ru" Например: "Магазин отклонил платеж: причина блокировки", где "Магазин отклонил платеж:" - вводная часть. "Причина блокировки" - значение параметра message

Частые ошибки интеграции

Чаще всего проблемы возникают из-за того, что:

• не проверяется signature;

• не проверяются IP-адреса;

• не сверяются orderSum и orderCurrency;

• товар выдается на этапе check, а не на этапе pay;

• сервер возвращает некорректный JSON.