Короткий ответ и границы сценария
Полный платёжный API-сценарий состоит из создания заказа, запроса с ключом и nonce, сохранения pay_url, подписанного webhook и идемпотентной выдачи результата. Материал рассчитан на backend-разработчика сайта, бота, SaaS или мобильного приложения. Сначала определите бизнес-объект, который изменится после оплаты: заказ, бронь, период доступа, лицензия или обязательство перед клиентом.
Backend создаёт order_2026_184, отправляет сумму строкой и сохраняет ответ до возврата URL клиенту. Позже webhook переводит заказ в paid в одной транзакции; браузерный success_redirect только показывает результат и не выдаёт товар. Это конкретный пример модели, а не универсальное разрешение для любой категории. Условия подключения, способы оплаты и документы подтверждаются для проекта во время модерации.
Интеграция платежей — это протокол состояний, а не один HTTP-запрос. Сервер проекта создаёт платёж, сохраняет payment_id и pay_url, отдаёт ссылку клиенту, принимает подписанные события и идемпотентно меняет заказ. Каждый переход должен быть наблюдаемым и повторяемым.
Как выбрать рабочий вариант
Сравнивайте варианты по тому, какое действие нужно подтвердить и кто отвечает за следующий шаг. В таблице — три контрольные точки именно для темы «API приема платежей».
| Контрольная точка | Как зафиксировать | С чем связать |
|---|---|---|
| server-to-server ключ | Записать принятое решение, владельца и критерий готовности. | pay_url и внутренний order_id. |
| X-Nonce | Сохранить выбранное значение и версию условий. | callback_url и ожидаемый результат. |
| уникальный order_id | Определить проверку, состояние ошибки и безопасный повтор. | машина состояний, payment_id и время обработки. |
Шесть точек, которые определяют результат
server-to-server ключ
Контрольная точка «server-to-server ключ» задаёт исходные данные для материала «API приёма платежей: от запроса до подтверждения». Зафиксируйте решение в карточке заказа до создания платежа, чтобы повторный запрос не создавал новую продажу случайно.
X-Nonce
Пункт «X-Nonce» должен быть понятен покупателю до перехода в форму: покажите сумму, назначение и ожидаемый результат. Интерфейс отдельно объясняет ожидание, успех, отмену и истечение, не подменяя серверный статус красивым экраном.
уникальный order_id
Для пункта «уникальный order_id» определите техническое доказательство завершения: проверенное событие, совпавшие сумма и валюта, известные order_id и payment_id. Только после этой проверки запускайте продуктовую выдачу или исполнение заказа.
pay_url
У элемента «pay_url» должен быть владелец исключений. Ему нужна история попыток и правило, которое объясняет, можно ли безопасно повторить создание, отправку ссылки или выдачу без доступа к API-ключам.
callback_url
Требование «callback_url» проверьте повторной доставкой callback. Два одинаковых события не должны дважды продлевать доступ, резервировать место, начислять баланс или отправлять товар; ограничение фиксируют на уровне данных.
машина состояний
Для точки «машина состояний» заранее опишите возврат, спор и задержку результата. Покупателю нужен понятный канал поддержки, а команде — связь между исходным заказом, платежом, документом и обратной операцией.
Пошаговая схема
- server-to-server ключ. Ограничьте таймаут исходящего запроса и логируйте trace-id без ключей и персональных данных. Запишите входные данные, ответственного и условие завершения. Если нужен денежный результат, сообщение пользователя и визуальный редирект не заменяют проверенный серверный статус.
- X-Nonce. Генерируйте уникальный X-Nonce для каждой попытки, но сохраняйте order_id при безопасном повторе создания. Запишите входные данные, ответственного и условие завершения. Если нужен денежный результат, сообщение пользователя и визуальный редирект не заменяют проверенный серверный статус.
- уникальный order_id. Сохраняйте raw body webhook до проверки подписи и сравнивайте HMAC в constant-time режиме. Запишите входные данные, ответственного и условие завершения. Если нужен денежный результат, сообщение пользователя и визуальный редирект не заменяют проверенный серверный статус.
- pay_url. Обрабатывайте payment.paid, payment.canceled и payment.expired как явные состояния. Запишите входные данные, ответственного и условие завершения. Если нужен денежный результат, сообщение пользователя и визуальный редирект не заменяют проверенный серверный статус.
- callback_url. Проверяйте интеграцию тестовыми сценариями, включая повтор события и недоступность вашего callback URL. Запишите входные данные, ответственного и условие завершения. Если нужен денежный результат, сообщение пользователя и визуальный редирект не заменяют проверенный серверный статус.
Шестая точка — машина состояний — завершает цикл. Она должна быть видна в личном кабинете или внутренней системе проекта, чтобы поддержка могла восстановить ход операции без доступа к секретным ключам и без просьбы прислать скриншот.
Как собрать сценарий на RollyPay
Backend создаёт платёж методом POST /api/v1/payments. Для задачи «API приема платежей» он передаёт X-API-Key, новый X-Nonce и стабильный order_id, связанный с пунктом «server-to-server ключ». В ответ сохраняются payment_id и pay_url.
Результат приходит на callback_url. До JSON-разбора сервер проверяет X-Signature как HMAC-SHA256 от X-Timestamp + "." + raw body, затем сверяет сумму, валюту, order_id и ожидаемый переход «уникальный order_id».
Выдача по payment.paid защищается уникальным ключом, связанным с «callback_url». payment.canceled и payment.expired закрывают попытку, но не стирают историю; повтор события заканчивается тем же итогом без повторного побочного эффекта.
Для темы «API приёма платежей: от запроса до подтверждения» условия и варианты подключения собраны на странице решения RollyPay. Там можно сопоставить сценарий с продуктом, а здесь сохранить инструкцию и контрольные детали для реализации.
Частые ошибки
Нет внутреннего объекта продажи. Пункт «server-to-server ключ» существует только в переписке, поэтому платёж нельзя однозначно связать с товаром или обязательством. Сначала создайте внутренний заказ и только затем внешний платёж.
Интерфейс принят за доказательство. Пункт «X-Nonce» может быть кнопкой, QR, ссылкой или экраном возврата. Денежный результат всё равно подтверждают серверное состояние и проверенное событие.
Разорваны данные процесса. Пункты «уникальный order_id» и «callback_url» должны быть связаны через order_id, payment_id, сумму, валюту и последнее событие. Тогда повтор или позднее подтверждение обрабатываются безопасно.
Нет владельца исключений. Пункт «машина состояний» включает возврат, истечение, спор и сбой доставки. Для каждого случая нужны статус, ответственная роль и понятное сообщение покупателю.
Что проверить до публикации
Для server-to-server запросов RollyPay используется X-API-Key, а X-Nonce защищает от повтора одного запроса. Уникальный order_id является естественным ключом идемпотентности создания платежа. Секреты хранятся только на backend и не попадают в браузер, мобильный клиент или репозиторий.
Webhook подписывается HMAC-SHA256 по строке X-Timestamp, точка и исходное тело запроса. Проверка выполняется до JSON-разбора; после неё обработчик сверяет событие, сумму, валюту и заказ, фиксирует event/payment_id и отвечает 2xx только после надёжного сохранения результата.
- Категория проекта и предмет продажи описаны одинаково на сайте, в боте и в заявке на подключение.
- Цена, валюта, срок действия предложения и правила возврата видны до оплаты.
- Секреты находятся только на сервере, а журнал не содержит API-ключей и полного тела с чувствительными данными.
- Успех, отмена, истечение, повтор события и недоступность callback проверены до реальных продаж.
- Налоговый или кассовый документ создаётся по правилам статуса продавца и связан с заказом.
Архитектура темы: от решения до контроля
server-to-server ключ. Ограничьте таймаут исходящего запроса и логируйте trace-id без ключей и персональных данных. На уровне продукта зафиксируйте вход, переход состояния и доказательство завершения. На уровне поддержки определите, где увидеть order_id и payment_id. На уровне пользователя заранее покажите, что произойдёт после оплаты и куда обратиться, если результат задержался.
X-Nonce. Генерируйте уникальный X-Nonce для каждой попытки, но сохраняйте order_id при безопасном повторе создания. На уровне продукта зафиксируйте вход, переход состояния и доказательство завершения. На уровне поддержки определите, где увидеть order_id и payment_id. На уровне пользователя заранее покажите, что произойдёт после оплаты и куда обратиться, если результат задержался.
уникальный order_id. Сохраняйте raw body webhook до проверки подписи и сравнивайте HMAC в constant-time режиме. На уровне продукта зафиксируйте вход, переход состояния и доказательство завершения. На уровне поддержки определите, где увидеть order_id и payment_id. На уровне пользователя заранее покажите, что произойдёт после оплаты и куда обратиться, если результат задержался.
pay_url. Обрабатывайте payment.paid, payment.canceled и payment.expired как явные состояния. На уровне продукта зафиксируйте вход, переход состояния и доказательство завершения. На уровне поддержки определите, где увидеть order_id и payment_id. На уровне пользователя заранее покажите, что произойдёт после оплаты и куда обратиться, если результат задержался.
callback_url. Проверяйте интеграцию тестовыми сценариями, включая повтор события и недоступность вашего callback URL. На уровне продукта зафиксируйте вход, переход состояния и доказательство завершения. На уровне поддержки определите, где увидеть order_id и payment_id. На уровне пользователя заранее покажите, что произойдёт после оплаты и куда обратиться, если результат задержался.
Пилларная страница связывает семь узких инструкций кластера. Не пытайтесь решить их одним абзацем: выбор статуса, мобильный путь, webhook, возврат и выдача доступа имеют разные риски и должны проверяться отдельными сценариями.
Практические заметки для запуска
server-to-server ключ. Ограничьте таймаут исходящего запроса и логируйте trace-id без ключей и персональных данных. Владелец шага, сохраняемый идентификатор и проверяемый результат определяются заранее. Связка с пунктом «уникальный order_id» фиксируется в данных заказа, а не остаётся устной договорённостью. Для темы «API приёма платежей: от запроса до подтверждения» это упрощает поддержку, повторную доставку события и разбор спорной операции.
X-Nonce. Генерируйте уникальный X-Nonce для каждой попытки, но сохраняйте order_id при безопасном повторе создания. Владелец шага, сохраняемый идентификатор и проверяемый результат определяются заранее. Связка с пунктом «pay_url» фиксируется в данных заказа, а не остаётся устной договорённостью. Для темы «API приёма платежей: от запроса до подтверждения» это упрощает поддержку, повторную доставку события и разбор спорной операции.
уникальный order_id. Сохраняйте raw body webhook до проверки подписи и сравнивайте HMAC в constant-time режиме. Владелец шага, сохраняемый идентификатор и проверяемый результат определяются заранее. Связка с пунктом «callback_url» фиксируется в данных заказа, а не остаётся устной договорённостью. Для темы «API приёма платежей: от запроса до подтверждения» это упрощает поддержку, повторную доставку события и разбор спорной операции.
pay_url. Обрабатывайте payment.paid, payment.canceled и payment.expired как явные состояния. Владелец шага, сохраняемый идентификатор и проверяемый результат определяются заранее. Связка с пунктом «машина состояний» фиксируется в данных заказа, а не остаётся устной договорённостью. Для темы «API приёма платежей: от запроса до подтверждения» это упрощает поддержку, повторную доставку события и разбор спорной операции.
callback_url. Проверяйте интеграцию тестовыми сценариями, включая повтор события и недоступность вашего callback URL. Владелец шага, сохраняемый идентификатор и проверяемый результат определяются заранее. Связка с пунктом «server-to-server ключ» фиксируется в данных заказа, а не остаётся устной договорённостью. Для темы «API приёма платежей: от запроса до подтверждения» это упрощает поддержку, повторную доставку события и разбор спорной операции.
машина состояний. Ограничьте таймаут исходящего запроса и логируйте trace-id без ключей и персональных данных. Владелец шага, сохраняемый идентификатор и проверяемый результат определяются заранее. Связка с пунктом «X-Nonce» фиксируется в данных заказа, а не остаётся устной договорённостью. Для темы «API приёма платежей: от запроса до подтверждения» это упрощает поддержку, повторную доставку события и разбор спорной операции.
server-to-server ключ. Генерируйте уникальный X-Nonce для каждой попытки, но сохраняйте order_id при безопасном повторе создания. Владелец шага, сохраняемый идентификатор и проверяемый результат определяются заранее. Связка с пунктом «уникальный order_id» фиксируется в данных заказа, а не остаётся устной договорённостью. Для темы «API приёма платежей: от запроса до подтверждения» это упрощает поддержку, повторную доставку события и разбор спорной операции.
X-Nonce. Сохраняйте raw body webhook до проверки подписи и сравнивайте HMAC в constant-time режиме. Владелец шага, сохраняемый идентификатор и проверяемый результат определяются заранее. Связка с пунктом «pay_url» фиксируется в данных заказа, а не остаётся устной договорённостью. Для темы «API приёма платежей: от запроса до подтверждения» это упрощает поддержку, повторную доставку события и разбор спорной операции.
уникальный order_id. Обрабатывайте payment.paid, payment.canceled и payment.expired как явные состояния. Владелец шага, сохраняемый идентификатор и проверяемый результат определяются заранее. Связка с пунктом «callback_url» фиксируется в данных заказа, а не остаётся устной договорённостью. Для темы «API приёма платежей: от запроса до подтверждения» это упрощает поддержку, повторную доставку события и разбор спорной операции.