Обработка уведомлений об изменении статуса платежей — один из ключевых компонентов любой платежной интеграции. Именно от того, насколько правильно настроена система колбэков, зависит автоматизация бизнес-процессов: подтверждение заказов, отправка товаров, уведомление клиентов и синхронизация данных между системами. PayShark.io предоставляет гибкую систему callback-уведомлений, которая позволяет мерчантам получать информацию о статусах сделок и выплат в реальном времени.
Callback — это POST-запрос, который PayShark отправляет на указанный URL при изменении статуса сделки или выплаты. URL для уведомлений можно задать двумя способами: в настройках мерчанта в админке (глобальный callback для всех сделок) или передать параметр callback_url при создании сделки через API. Приоритет имеет callback_url из запроса — если он указан, уведомление будет отправлено именно на него, а не на URL из админки.
Формат callback-уведомления по сделке
Уведомление отправляется как POST-запрос с телом в формате JSON. Структура данных:
{
"id": "order-uuid",
"external_id": "123",
"status": "success",
"sub_status": "fully_completed",
"amount": 1000,
"currency": "rub",
"payment_gateway": "sberbank"
}
Поле status может принимать значения: success (успешно завершена), fail (ошибка), pending (в обработке). Поле sub_status предоставляет более детальную информацию о состоянии сделки.
Подстатусы сделок
Полный список подстатусов и их значение: pending — сделка создана; accepted — принята системой; waiting_for_payment — реквизиты предоставлены, ожидается перевод; successfully_paid — платеж зачислен; successfully_paid_by_resolved_dispute — оплачено после разрешения спора; waiting_details_to_be_selected — ожидание выбора реквизитов; waiting_for_dispute_to_be_resolved — ожидание разрешения спора; canceled_by_dispute — отменена по спору; expired — истек срок действия; cancelled — отменена мерчантом.
Последовательность статусов выплат: pending, processing_by_trader, processing_by_administrator, fully_completed. При ошибке выплата переходит в cancelled.
Обработка уведомлений на стороне мерчанта
Ваша система должна принимать POST-запросы на callback_url, парсить JSON и выполнять соответствующие действия. Рекомендуется возвращать HTTP 200 в ответ на уведомление, чтобы PayShark знал, что уведомление получено. Если сервер возвращает ошибку, PayShark повторяет отправку несколько раз с увеличивающимся интервалом.
Для обеспечения безопасности рекомендуется проверять источник уведомлений. PayShark отправляет уведомления со своих IP-адресов, которые можно получить через службу поддержки.
Практические сценарии обработки
При получении статуса successfully_paid: подтвердить заказ в системе, отправить товар или активировать услугу, уведомить клиента об успешной оплате. При статусе cancelled или expired: отменить заказ, вернуть средства на баланс клиента, уведомить клиента об отмене. При статусе dispute: приостановить выполнение заказа, уведомить службу поддержки, подготовить документы для разбирательства.
Для выплат при статусе fully_completed: отметить выплату как выполненную в системе. При статусе cancelled: создать новую выплату или уведомить получателя.
Надежная система callback-уведомлений — основа автоматизации платежных процессов на PayShark.io. Правильная обработка всех статусов и подстатусов гарантирует, что бизнес-процессы будут выполняться своевременно и без сбоев.
