Быстрый старт
Четыре шага прямой интеграции с API АТОЛ - с ИИ-ассистентом или своими руками. Фискализация, доступы, код, проверка в песочнице.
Вы делаете прямую интеграцию по API: готовый плагин или платежная кнопка не подходят, код пишется на своей стороне. Дальше - четыре шага, которые проходит человек. Техническую работу - чтение контракта, подбор полей, код - можно отдать ИИ-ассистенту или сделать самому по справочникам этого портала. На каждом шаге есть оба маршрута.
Что понадобится
- Юридическое лицо или ИП, зарегистрированное в РФ.
- Доступ в личный кабинет АТОЛ Pay - в нем выдается API-токен. Кабинет боевой среды вы заводите сами на lk.atolpay.ru, доступ в тестовую выдают по запросу (шаг 3).
- Адрес на вашем сайте, куда АТОЛ будет присылать уведомления об оплате (callback). Нужен публично доступный HTTPS-адрес; на время тестов подойдет временный туннель, например ngrok.
- Если идете с ассистентом - ИИ-клиент с поддержкой MCP: Claude Code, Claude Desktop, Cursor или VS Code. Если пишете код сами, он не нужен: ниже для каждого шага есть ручной маршрут.
- Если на шаге 2 выберете свою фискализацию - еще и доступ к АТОЛ Онлайн (логин, пароль, код группы ККТ).
Четыре шага
Выберите, как будете работать
Документация одна. Разница - кто ее читает: ассистент через MCP или вы по страницам этого портала.
MCP-сервер отдает ассистенту документацию этого портала и инструменты интеграции. Он работает на нашей стороне - скачивать и запускать ничего не нужно. Для Claude Code достаточно одной команды:
claude mcp add --transport http atol-docs https://pay.atol.ru/mcpКонфиги для Claude Desktop, Cursor и VS Code - в разделе Интеграция через ИИ. Инструменты документации работают без токенов и настроек: подключили - и ассистент уже отвечает по документации, а не по памяти.
Ассистент не нужен: этот портал и есть ваш рабочий стол. Документация, OpenAPI и примеры лежат на соседних страницах - не в памяти модели.
Что открыть, прежде чем писать код:
- Сквозные кейсы - шаг 2, одна развилка: чеки пробивает АТОЛ Pay или вы сами.
- Примеры АТОЛ Pay - эталонный
POST /v1/ecom/paymentsна Node.js, Python, PHP и curl. - Регистрация платежа -
контракт: поля,
paymentMethods, ограниченияorderId. - Callback-уведомления - что придет на ваш сервер и почему обработчик должен отвечать 200 и быть идемпотентным.
Контракт целиком - в Swagger UI и в OpenAPI 3.0 на этом портале: из спецификации удобно генерировать клиент и типы, без ассистента.
Когда карта ясна - шаг 2, затем доступы. Собирать код будете на шаге 3.
Решите, нужна ли вам своя фискализация
Единственная развилка, которую нужно пройти человеку: от нее зависит, делаете вы одну интеграцию или две. От выбора не уйти ни с ассистентом, ни без него.
АТОЛ Pay Ecom. Чеки не нужны либо их пробивает АТОЛ Pay сам - из блока
receipt в запросе платежа. Один API, один callback.
АТОЛ Pay Ecom + АТОЛ Онлайн v5. Нужны маркировка, авансы, частичные отгрузки или чеки коррекции - чеки вы отправляете сами.
Сомневаетесь - откройте сквозные кейсы использования: там сравнение вариантов по восьми критериям и правило выбора. Можно спросить ассистента - он читает ту же страницу.
Выбрали свою фискализацию - учтите, что нужны отдельные доступы к АТОЛ Онлайн (логин, пароль, код группы ККТ) и зарегистрированные на вас кассы. Запросите их сейчас, чтобы не ждать на шаге 4: порядок - в Общем алгоритме взаимодействия.
Получите доступы и соберите интеграцию
Доступы выдает личный кабинет: ни ассистент, ни эта страница их за вас не заведут. Пройдите пункты по порядку, а первый сделайте сразу: доступ в тестовую среду выдается по письменному запросу, а без него нечего будет проверять на шаге 4.
1. Заведите кабинет и запросите тестовый доступ
Кабинет боевой среды lk.atolpay.ru вы создаете сами - понадобятся телефон и email.
Тестовая среда - это отдельный кабинет (croc-sandbox-lk.atolpay.ru) со своими логином и паролем: их предоставляют по запросу на 1@atol.ru. Именно в тестовой среде вы будете проверять интеграцию на шаге 4 - напишите письмо заранее.
2. Пройдите проверку в банке (онбординг)
Эквайринг подключает банк, поэтому нужна его анкета: в разделе Продукты > Интернет-эквайринг заполните анкету выбранного банка. По результатам проверки банк выдает логин/пароль продавца - они автоматически сохраняются в настройках личного кабинета, отдельно вписывать их никуда не нужно.
3. Сгенерируйте API-токен
В разделе Настройки > API Токены сгенерируйте секретный токен - это ключ, которым ваш код (и, если захотите, ассистент) обращается к API. Он передается во всех запросах API в HTTP-заголовке:
Authorization: Bearer <access_token>Есть и альтернатива - подпись запроса заголовками x-secret-id и
x-signature, см. Авторизация.
Токен - секрет: не публикуйте его в открытом коде и не отправляйте в мессенджеры.
4. Настройте заказы и фискализацию
Эти настройки заполняются один раз в кабинете - ни ассистент, ни ваш код их не видят. Сделайте до тестов.
В разделе Настройки > Настройки заказов укажите:
- обратный URL по умолчанию (
returnUrl) - куда покупатель вернется после оплаты; - URL для callback-уведомлений о статусах заказов - куда АТОЛ пришлет результат;
- банк для оплаты картой и СБП, двухстадийный платеж по умолчанию.
В разделе Провайдер чеков загрузите данные для фискализации (включая версию ФФД), если планируете отправлять чеки.
5. Только для варианта Б: доступ к АТОЛ Онлайн
Если на шаге 2 вы выбрали свою фискализацию, понадобится отдельный набор
доступов: логин, пароль и код группы (group_code) из личного
кабинета АТОЛ Онлайн, плюс зарегистрированные на вас кассы. Учетные данные
АТОЛ Pay здесь не подойдут - это разные сервисы с разными кабинетами. Порядок
получения - Общий алгоритм взаимодействия.
Доступы есть. Дальше - код.
Опишите задачу ассистенту обычными словами. Чем конкретнее формулировка, тем меньше уточняющих вопросов:
Подключи прием оплаты АТОЛ Pay к моему Express-приложению: одностадийный платеж картой и СБП, обработчик callback-уведомлений, чек из блока receipt.
Не знаете, на чем написан ваш сайт, - это нормально: откройте проект в ассистенте и попросите разобраться самому.
Посмотри мой проект и подключи прием оплаты АТОЛ Pay: карта и СБП, чеки пробивает АТОЛ Pay. В конце скажи, что мне нужно вписать руками и где.
Если на шаге 2 вы выбрали свою фискализацию, назовите вариант прямо:
Делаем вариант Б из сквозных кейсов: АТОЛ Pay без блока receipt, чеки предоплаты и полного расчета отправляем сами через АТОЛ Онлайн v5. Стек - Python/FastAPI.
Ассистент сам возьмет план интеграции под ваш стек (start_integration),
готовые рецепты (get_recipe), описания методов и коды ошибок - и напишет
код. Больше формулировок - в примерах промптов.
Токен ассистенту давать не обязательно
Чтобы получить код интеграции, токен не нужен - инструменты документации, планов и валидации работают без него. Токен передают MCP-серверу только когда хотят, чтобы ассистент сам делал тестовые вызовы API; денежные операции при этом остаются отключенными. См. учетные данные.
Минимальный контур - четыре куска кода. Это тот же набор, который ассистент
собирает из start_integration и get_recipe; здесь он разложен по страницам.
- Регистрация платежа.
POST /v1/ecom/paymentsсamountв копейках, вашимorderId,sessionType,returnUrlиnotificationUrl. Ответ, который вас интересует, -data.paymentUrls.main. Контракт: метод регистрации. Готовый запрос: примеры. - Редирект покупателя на
data.paymentUrls.main. Платежную форму, 3-D Secure и банки вы не рисуете - их отдает АТОЛ Pay. Сценарий целиком: одностадийный платеж. - Обработчик callback. HTTP POST на ваш
notificationUrl. Ответьте 200 даже если заказ уже обработан; ключ идемпотентности -orderId+type. Поtype: paymentиpaymentStatus: 1выдавайте товар (вариант А) или пробивайте чек предоплаты (вариант Б). Полезная нагрузка: callback-уведомления. - Опрос статуса как fallback. Если callback не пришел -
GET /v1/ecom/payments/{orderId}/status. См. получение статуса.
Вариант А. Блок receipt кладется в тот же
запрос регистрации. Суммы позиций - в копейках, quantity - в тысячных,
providerId: 100. Чек «Приход» уйдет сам после оплаты, «Возврат прихода» -
сам при POST /cancel.
Вариант Б. В запросе платежа блока receipt нет. После callback оплаты
отправляете чек сами: токен → POST /{group_code}/sell → report по uuid.
Порядок: общий алгоритм, код -
примеры АТОЛ Онлайн. Помните про единицы: Pay считает
в копейках, Online - в рублях. Как связать два API -
кейс с доставкой.
Чек-лист, прежде чем идти на шаг 4:
- регистрация возвращает
data.paymentUrls.main; orderId- латиница, цифры и:+-_.; для Альфа-Банка не длиннее 36 символов;- callback отвечает 200 и идемпотентен по
orderId+type; - если есть чек в Pay - сумма позиций сходится с
amount(иначеINVALID_RECEIPT_AMOUNT); buyer.emailне длиннее 64 символов.
Ошибки, которые стоит держать открытыми: коды АТОЛ Pay и ошибки АТОЛ Онлайн.
Когда код готов, не переключайтесь на боевую среду сразу - сначала шаг 4.
Проверьте результат в песочнице
Песочница (она же sandbox, тестовая среда) - копия сервиса, где деньги не списываются по-настоящему, а чеки тестового контура АТОЛ Онлайн не уходят в налоговую. Устроена она так же, как боевая, поэтому проверять интеграцию нужно именно здесь.
Убедиться нужно в четырех вещах:
- платеж регистрируется, и в ответе приходит ссылка на оплату
(
data.paymentUrls.main); - после оплаты покупатель возвращается на ваш
returnUrl; - на ваш адрес приходит callback-уведомление и статус заказа меняется;
- если платеж с блоком
receipt(вариант А) - приходит callbacktype: fiscalсreceiptIdчека.
Вариант Б. Дополнительно отправьте тестовый чек на
https://testonline.atol.ru/possystem/v5/{group_code}/sell и прочитайте
результат по uuid методом report. Убедитесь, что
в ответе есть ФД и ФПД, а ошибочные запросы возвращают коды 30 (некорректный
UUID) и 34 (документ еще в очереди).
Тестовые карты и данные обоих контуров - на странице Тестовые данные.
Попросите ассистента создать тестовый платеж и дать ссылку на оплату. Откройте
ее и оплатите тестовой картой. Для варианта Б ассистент
прочитает результат чека инструментом get_fiscal_report - в ответе должны
быть ФД и ФПД.
Полный чек-лист перевода в бой выдаст инструмент get_recipe с темой
go-live-checklist.
Первый платеж можно собрать curl-ом, не дожидаясь готовности всего бэкенда. Подставьте токен из тестового кабинета в переменную окружения - так секрет не окажется в истории команд.
curl -X POST "https://croc-sandbox-api-mobile.atolpay.ru/v1/ecom/payments" \
-H "Authorization: Bearer $ATOL_PAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"orderId": "test-order-1",
"sessionType": "oneStep",
"additionalProps": {
"returnUrl": "https://example.com/return"
},
"paymentMethods": [
{ "paymentType": "card", "bankId": 100 }
]
}'В ответе придет data.paymentUrls.main - откройте ссылку и оплатите
тестовой картой. Чтобы увидеть callback, в
additionalProps.notificationUrl укажите публичный HTTPS-адрес вашего
обработчика; на время тестов подойдет туннель вроде ngrok.
Статус без ожидания callback:
curl "https://croc-sandbox-api-mobile.atolpay.ru/v1/ecom/payments/test-order-1/status" \
-H "Authorization: Bearer $ATOL_PAY_TOKEN"data.status: 1 - оплата прошла, 0 - еще в обработке. Расшифровка кодов -
в статусах платежа.
Для варианта Б сначала получите токен АТОЛ Онлайн методом
getToken, затем отправьте чек - готовый запрос
в примерах АТОЛ Онлайн.
Тестовый контур: https://testonline.atol.ru/possystem/v5/.
Переход на боевую среду
Когда все работает, переключайтесь по списку:
- Базовый адрес API - тестовый на боевой (см. таблицу ниже) - и токен из боевого кабинета: кабинеты у сред разные.
- В боевом кабинете -
returnUrl, URL callback и пройденная анкета банка (Продукты > Интернет-эквайринг). - Для варианта Б - адрес
online.atol.ruи боевые логин, пароль и код группы АТОЛ Онлайн. - Если ассистент делает вызовы API сам - заголовок
X-Atol-Allow-Live: 1, см. учетные данные.
Ассистент соберет тот же список инструментом get_recipe с темой
go-live-checklist.
Среды
| Среда | Личный кабинет | API |
|---|---|---|
| Тестовая (sandbox) | https://croc-sandbox-lk.atolpay.ru | https://croc-sandbox-api-mobile.atolpay.ru/v1/ecom/ |
| Боевая (production) | https://lk.atolpay.ru | https://new-api-mobile.atolpay.ru/v1/ecom/ |
Swagger
Актуальное описание методов в формате Swagger UI доступно по адресу https://new-api-mobile.atolpay.ru/v1/ecom/documentation/. Эта же спецификация в формате OpenAPI 3.0 доступна в нашем портале и используется MCP-сервером.
Куда идти дальше
Эти страницы закрывают вопросы, которые всплывают на шагах 3–4, - и у тех, кто пишет код сам, и у тех, кто проверяет ассистента.
- Сценарии оплаты - одностадийный, двухстадийный, подписки: чем отличаются и что выбрать.
- Callback-уведомления - что приходит на ваш сервер и как это обрабатывать.
- Примеры АТОЛ Pay и примеры АТОЛ Онлайн - готовый код на четырех языках.
- Сквозные кейсы использования - архитектура целиком, с кодом и диаграммами.
- Коды ошибок АТОЛ Pay и ошибки АТОЛ Онлайн - если платеж или чек не проходят. Код ошибки можно вставить ассистенту: он найдет его в справочнике.
- Интеграция через ИИ - если решите все-таки отдать чтение документации ассистенту.