Agent Pay для разработчиков
PayFar предоставляет платежи агентов в виде MCP-сервера по адресу https://mcp.payfar.org/mcp. Хост подключается с ключом API или по OAuth 2.1, и каждый вызов инструмента проверяется политикой владельца до того, как будут перемещены какие-либо деньги или реквизиты карты.
Подключение
Есть два способа. Либо владелец создаёт ключ в приложении PayFar (Агенты → ваш агент → Ключи), и хост передаёт его как bearer-токен, либо хост регистрируется сам и проходит процедуру OAuth 2.1 authorization code с PKCE.
Динамическая регистрация клиентов (RFC 7591) открыта. Метаданные защищённого ресурса (RFC 9728) отдаются с хоста MCP, а метаданные сервера авторизации (RFC 8414) отдаёт API. Индикаторы ресурса (RFC 8707) обязательны: токен привязан к этому серверу и отклоняется в любом другом месте.
- Streamable HTTP: https://mcp.payfar.org/mcp
- stdio: npx @payfar/mcp, с PAYFAR_AGENT_KEY в переменных окружения
- Области доступа (scopes): payments:read, payments:create, credentials:read, threeds:read, services:read, topup:request, fulfilment:run
Цикл платежа
Сначала проверка, потом создание. `check_payment` запускает тот же механизм политик, что и реальный вызов, и возвращает решение, которое было бы принято, поэтому агент может сказать пользователю, что произойдёт, прежде чем брать на себя какие-либо обязательства.
`create_payment` возвращает approved, held или declined. Задержанный платёж (held) не является ошибкой: он ждёт решения владельца, а `wait_for_payment` выполняет long polling, пока тот не ответит. Только после одобрения `get_payment_credentials` выдаёт карту, в ограниченном по времени окне и с ограниченным числом показов.
Когда списание выполнено, сообщите об этом. Именно `report_payment_outcome` закрывает intent и позволяет при расчётах сопоставить его с реальной операцией; агент, который пропускает этот шаг, оставляет бюджет владельца зарезервированным.
Ошибки служат инструкциями
Каждая ошибка содержит стабильный код, сообщение для журнала и подсказку, написанную для того, чтобы агент мог по ней действовать. Самые важные коды:
- intent.pending_approval: владелец ещё не ответил; ждите, не повторяйте запрос.
- policy.declined: платёж отклонило правило, какое именно, указывает rule id. Не повторяйте тот же платёж.
- intent.window_closed / intent.reveals_exhausted: окно доступа к реквизитам закрылось. Создайте новый intent.
- pin.required: действие должен подтвердить человек в приложении. Агент здесь ничего сделать не может.
- card.unlock_failed: временная ошибка; повторите через минуту.
Навык (Skill)
Есть Agent Skill, который обучает хост всему процессу: когда проверять перед созданием, как читать решение, что делать с задержанным платежом и чего никогда не делать с реквизитами карты. Установите его вместе с MCP-сервером, а не пишите цикл вручную.
Он поставляется вместе с сервером: `npx @payfar/mcp skill install`; также его можно прочитать как ресурс `payfar://skill`.
Чего сервер делать не будет
MCP-сервер работает как переводчик, а не как арбитр. Он ничего не хранит, ничего не решает и передаёт учётные данные вызывающей стороны в PayFar без изменений: бэкенд является единственным местом, где проверяются учётные данные и применяются политики.
Реквизиты карты возвращаются только тому вызову, который их запрашивает, и никогда не попадают в журналы, события, уведомления или тела ошибок. Если вы найдёте их где-то ещё, это ошибка, о которой стоит сообщить.