Реализация HTTP-обмена x402 v2: заголовки, фасилитаторы и расчёты

Что это

Сведения актуальны на 25 октября 2026 года. Здесь описаны версия 2 протокола x402 и его привязка к HTTP. Перед внедрением заново проверьте обе спецификации и выбранную схему: сама по себе версия протокола не фиксирует все детали реализации. RFC 9110 резервирует HTTP 402 для будущего использования: сам код состояния не задаёт процедуру платежей, обеспечивающую совместимость реализаций.

x402 добавляет такую процедуру. Клиент запрашивает ресурс, сервер ресурсов передаёт платёжные требования, а фасилитатор может выполнять проверку и расчёты через /verify и /settle. Сервер может выполнять эти функции самостоятельно. Фасилитатор должен поддерживать выбранные схему и сеть.

Почему это важно

Привязка к HTTP передаёт JSON в кодировке base64 в трёх заголовках: PAYMENT-REQUIRED содержит платёжные требования сервера, PAYMENT-SIGNATURE — платёжные данные клиента, а PAYMENT-RESPONSE — результаты расчётов. Именно заголовок требований является основным местом их передачи; клиент не должен полагаться на наличие удобного JSON в теле ответа.

Основная спецификация разделяет проверку разрешения на платёж и перемещение средств. В стандартном сценарии authorization проверка предшествует выполнению операции с ресурсом, а расчёты проводятся после неё. В других определённых сценариях, включая upfront и escrow, средства вносятся до выполнения операции. Поэтому успешная проверка сама по себе не доказывает, что расчёты состоялись.

Как применять

• Продумайте реализацию клиента. Разберите PaymentRequired, выберите поддерживаемую запись из accepts и перед подписанием проверьте сумму, актив, сеть и получателя на соответствие политике расходов. Передайте полученные данные через PAYMENT-SIGNATURE. Отклоняйте незнакомые платёжные сценарии, не пытаясь угадать их последствия.
• Реализуйте проверки на сервере. Передайте требования и проверьте полученное разрешение на соответствие им. Соблюдайте порядок проверки и расчётов, установленный выбранным сценарием. Верните результат расчётов в PAYMENT-RESPONSE; сохраните идентификатор транзакции и сеть для сверки.
• Проверьте инфраструктуру для браузеров. Для клиентов с другого источника разрешите доступ к PAYMENT-REQUIRED и PAYMENT-RESPONSE через CORS, а при обработке предварительного запроса разрешите использование заголовка PAYMENT-SIGNATURE. Проверка из командной строки не охватывает эти ограничения браузера.
• Обрабатывайте неопределённые результаты. Описанный в документации результат settlement_pending означает, что отправленная в сеть транзакция ещё может быть подтверждена. Сверьте её состояние по идентификатору, прежде чем решать, нужен ли ещё один платёж.
• Используйте контрольный список для проверки. При интеграции зафиксируйте, какой компонент отвечает за ценообразование, подписание, проверку, расчёты и предоставление ресурса. Прежде чем разрешать агенту расходовать средства, отработайте отказ в платеже, недоступность фасилитатора и потерю ответов в непроизводственной среде.

Подводные камни

Если считать любой ответ 402 разрешением на расходование средств, запрос продавца подменяет разрешение пользователя. Храните это разрешение отдельно. Основная спецификация явно исключает управление бюджетом клиента из своей области действия.

Для эксплуатационного контроля ведите отдельные записи о результате платежа и предоставлении ресурса. Прежде чем выдавать новое разрешение, разберитесь с оплаченным запросом, по которому ресурс не был предоставлен. Эти рекомендации по учёту относятся к практике реализации и не означают, что HTTP обеспечивает автоматические возвраты или выполнение операции приложения ровно один раз.