Платежи
Методы работы с платежами АТОЛ Pay Ecom - регистрация платежа, статус, отмена/возврат, списание по двухстадийной оплате.
Базовый URL продуктовой среды: https://new-api-mobile.atolpay.ru
(тестовая: https://croc-sandbox-api-mobile.atolpay.ru).
Авторизация
Все методы требуют либо заголовок Authorization с токеном из личного кабинета
(Настройки > API Токены), либо пару x-secret-id + x-signature (ID
секрета из раздела Настройки > Секреты аутентификации и подпись запроса на
его основе).
Расхождение источников по формату Authorization
OpenAPI-спецификация задает формат значения
Bearer {token} и требует передать либо Authorization, либо x-secret-id.
Документ «Интеграция c API АТОЛ Pay Ecom» показывает тот же заголовок без
префикса - Authorization: <access_token> - и заголовки x-secret-id /
x-signature в нем не упоминаются вовсе. Проверка на тестовом контуре
подтвердила формат спецификации: токен без префикса Bearer отклоняется с
ошибкой NO_AUTH_DATA (HTTP 412). Используйте Authorization: Bearer <token>.
Для взаимодействия с платежной формой необходимо поддерживать основной метод - регистрацию платежа, и три опциональных: списание по двухстадийной оплате, отмену/возврат и проверку статуса заказа.
Метод регистрации платежа
POST /v1/ecom/paymentsРезультат - ссылка на платежную форму (data.paymentUrls.main).
- Для одностадийного платежа передайте
sessionType: "oneStep". - Для двухстадийного -
sessionType: "twoStep"; после успешной оплаты запросите списание не позднее чем через 7 суток (deposit).
bankId устарел
Поле bankId верхнего уровня устарело - используйте массив paymentMethods.
Если переданы оба, приоритет у paymentMethods.
Методы оплаты (paymentMethods)
paymentType | Описание | Допустимые bankId |
|---|---|---|
card | Оплата по карте | 100 - Альфа-Банк, 700 - Т-Банк, 900 - ГПБ |
bank_app | Оплата через мобильное приложение банка | 700 - Т-Pay |
sbp | Оплата через СБП | 100 - Альфа-Банк, 200 - Открытие, 300 - Райффайзен, 400 - Сбербанк, 500 - Другой банк НСПК, 600 - ЮКасса |
bnpl | Оплата через сервис Т-Банк Долями | 701 - Т-Банк Долями |
account | Оплата по счету | 0 - значение по умолчанию |
Полный перечень допустимых bankId: 0, 100, 200, 300, 400, 500,
600, 700, 701, 900.
OpenAPI-спецификация в этой части устарела
Значение 200 (Открытие) описано в документе «Интеграция c API АТОЛ Pay
Ecom», но отсутствует в enum поля bankId в
OpenAPI-спецификации, приложенной к порталу.
Ориентируйтесь на таблицу выше; если сервис вернет ошибку валидации по этому
полю - уточните доступность способа оплаты в личном кабинете.
Для paymentType: "account" в ответе приходит accountUrl - ссылка на счет;
заказ завершается методом
POST /v1/ecom/payments/{orderId}/account/complete.
Метод оплаты должен быть предварительно подключен в личном кабинете - иначе он не появится ни в настройках ЛК, ни на форме оплаты.
Рекомендация
paymentMethods имеет приоритет над настройками по умолчанию. Используйте
это поле, только если методы оплаты отличаются от заказа к заказу. Если для
всех заказов методы одинаковы - не передавайте поле и задайте дефолтные
настройки в ЛК (Настройки > Настройки заказов): тогда методы можно менять
без правок в коде. Если настройки по умолчанию не заданы и paymentMethods
не передан, вернется ошибка PAYMENT_SETTINGS_NOT_FOUND.
Параметры запроса
| Параметр | Описание | Обяз. | Формат |
|---|---|---|---|
amount | Сумма платежа в копейках (1…2000000000) | Да* | number |
orderId | Идентификатор заказа на стороне продавца. Допустимы только цифры, латиница и символы :, +, -, _, .. Ограничение длины: 36 символов для Альфа-Банка, 255 для Т-Банка | Да | string(255) |
sessionType | Тип оплаты: oneStep / twoStep. Если не передан - берется из ЛК (Настройки > Настройки заказов > «Платежи в 2 стадии по умолчанию») | Нет | string |
additionalProps | Настройки платежа / дополнительные параметры | Да | object |
additionalProps.returnUrl | URL для кнопки «Вернуться в магазин» на платежной форме | Да | string(255) |
additionalProps.appReturnUrl | URL для кнопки «Вернуться в приложение». Используется только в режиме tp=app | Нет | string(255) |
additionalProps.notificationUrl | Адрес для отправки нотификаций. Если передан, все нотификации приходят на него, даже если в настройках ЛК указан другой. Можно добавлять query-параметры: https://example.com?userId=111&orderId=222 | Нет | string(255) |
additionalProps.sourceName | Источник создания платежа (для CMS-модулей): 1c-bitrix, bitrix24_cloud, CS-Cart, wordpress, opencart, tilda, modx, drupal, insales, website, api, lk, widget и др. По умолчанию сохраняется api | Нет | string |
additionalProps.sourceVersion | Версия источника создания платежа (для CMS-модулей) | Нет | string(32) |
bankId | Устарело. Идентификатор банка для оплаты картой - используйте paymentMethods | Нет | number |
buyerId | Идентификатор покупателя в системе продавца. Нужен для сохранения карты у пользователя; обязателен при recurring: true | Нет* | string(255) |
receipt | Информация для фискализации чека - см. Чеки | Нет | object |
inn | ИНН покупателя - для связи с транзакцией в ЛК | Нет | string(255) |
kpp | КПП покупателя - для связи с транзакцией в ЛК | Нет | string(255) |
recurring | Режим рекарринга: сохранить карту для последующих списаний без покупателя - см. Сохраненные карты. Требует buyerId; на форме остается только оплата картой | Нет | boolean |
merchant.name | Название магазина, отображаемое на платежной форме | Нет | string(255) |
paymentMethods | Массив методов оплаты, доступных на форме (см. выше). Если не передан - из настроек ЛК | Нет | array |
paymentMethods[].paymentType | card / bank_app / sbp / bnpl / account | Да | string |
paymentMethods[].bankId | Идентификатор банка (таблица выше) | Да | number |
paymentMethods[].accountUrl | URL для оплаты по счету | Нет | string |
userDefinedProps | Дополнительные параметры заказа | Нет | object |
userDefinedProps.cost.min | Минимальная разрешенная сумма заказа в копейках (1…2000000000, по умолчанию весь диапазон) | Нет | number |
userDefinedProps.cost.max | Максимальная разрешенная сумма заказа в копейках (1…2000000000) | Нет | number |
userDefinedProps.fields[].name | Название дополнительного поля ввода на форме (например, «Адрес доставки») | Нет | string(255) |
* amount можно не передавать, если задан диапазон свободной суммы
userDefinedProps.cost; buyerId обязателен при recurring: true.
Параметры ответа
| Параметр | Описание | Формат |
|---|---|---|
status | Статус выполнения запроса (success) | string |
data.orderId | Идентификатор заказа на стороне продавца | string |
data.amount | Сумма платежа в копейках | number |
data.paymentUrl | Устарело. Ссылка на форму оплаты - используйте data.paymentUrls.main | string |
data.paymentUrls.main | Ссылка на главную страницу формы оплаты | string |
data.paymentUrls.mainFrame | То же для отображения внутри фрейма | string |
data.paymentUrls.mainApp | То же для отображения внутри приложения | string |
data.paymentUrls.direct | Прямые ссылки на конкретный метод оплаты без главной страницы: card, tpay, dolyame, sbp, account | object |
data.paymentUrls.directFrame / directApp | То же для фрейма / приложения | object |
data.positions[] | Позиции заказа: id (UUID позиции), name, price, sum, quantity, measure, receipt | array |
paymentUrl устарел
Поле data.paymentUrl помечено в OpenAPI-спецификации как deprecated -
перенаправляйте покупателя на data.paymentUrls.main.
При ошибке возвращаются status: "error", errorCode, errorMessage
(HTTP 400 или 500).
Пример
{
"amount": 10000,
"orderId": "b0d84710-71f0-49ee-8219-f1b31a8d6770",
"sessionType": "oneStep",
"additionalProps": {
"returnUrl": "https://atolpay.ru/example",
"notificationUrl": "https://atolpay.ru/example",
"sourceVersion": "1.0.0"
},
"buyerId": "68770cca-3c95-4b81-9f6a-b3a6d1c0b38c",
"receipt": {
"buyer": { "email": "address@domain.me" },
"positions": [
{
"name": "Товар",
"price": 1000,
"quantity": 10000,
"measure": 3,
"paymentMethod": 0,
"paymentSubject": 0,
"tax": 0,
"isAgent": true,
"agentId": "b0d84710-71f0-49ee-8219-f1b31a8d6770",
"supplierId": "b0d84710-71f0-49ee-8219-f1b31a8d6770"
}
],
"providerId": 100,
"sno": 1
},
"inn": "7704211201",
"kpp": "770401001",
"paymentMethods": [
{ "paymentType": "card", "bankId": 100 }
],
"userDefinedProps": {
"cost": { "min": 1000, "max": 99900 },
"fields": [ { "name": "Адрес доставки" } ]
}
}{
"status": "success",
"data": {
"orderId": "b0d84710-71f0-49ee-8219-f1b31a8d6770",
"amount": 10000,
"paymentUrl": "https://atolpay.ru/b0d84710-71f0-49ee-8219-f1b31a8d6770",
"paymentUrls": {
"main": "https://atolpay.ru/b0d84710-71f0-49ee-8219-f1b31a8d6770",
"mainFrame": "https://atolpay.ru/b0d84710-71f0-49ee-8219-f1b31a8d6770?tp=frame",
"mainApp": "https://atolpay.ru/b0d84710-71f0-49ee-8219-f1b31a8d6770?tp=app",
"direct": {
"card": "https://atolpay.ru/b0d84710-71f0-49ee-8219-f1b31a8d6770/card",
"sbp": "https://atolpay.ru/b0d84710-71f0-49ee-8219-f1b31a8d6770/sbp"
}
},
"positions": [
{
"id": "e11b21fa-58e7-4918-bb38-159065c36a62",
"name": "Товар",
"price": 1000,
"sum": 10000,
"quantity": 10000,
"measure": 3
}
]
}
}{
"errorCode": "SERVER_ERROR",
"errorMessage": "some error message here",
"status": "error"
}Получение статуса платежа
GET /v1/ecom/payments/{orderId}/statusЗапрашивайте статус, если callback не пришел в течение длительного времени.
| Параметр ответа | Описание | Формат |
|---|---|---|
status | Статус выполнения запроса (success / error) | string |
data.status | Числовое значение статуса платежа (см. таблицу ниже) | number |
data.statusMessage | Текстовая интерпретация статуса | string |
data.bindingId | ID привязки сохраненной карты; null, если карта не сохранялась | string | null |
data.paymentUrl | Ссылка на форму оплаты | string |
{
"status": "success",
"data": {
"status": 0,
"statusMessage": "Платеж находится в обработке"
}
}Статусы платежа
| Код | Значение | Расшифровка |
|---|---|---|
| 0 | processing | В обработке |
| 1 | success | Успех (выполнен) |
| 2 | notResponding | Банк не ответил |
| 3 | error | Оплата с ошибкой, повтор операции невозможен |
| 4 | canceled | Отменен |
| 5 | refunded | Возвращен |
| 6 | fraud | Подозрение в мошенничестве |
| 7 | partialCancel | Частичная отмена |
| 8 | partialRefund | Частично возвращен |
| 9 | paymentIsOverdue | Платеж просрочен |
| 10 | confirm3ds | Подтверждение 3-D Secure |
| 11 | awaitingDeposit | Ожидает списания по двухстадийной оплате |
| 12 | retryError | Оплата с ошибкой, возможен повтор операции |
| 255 | cardChecked | Карта проверена (привязка карты без списания средств) |
Ответ также содержит data.bindingId - ID привязки сохраненной карты
(null, если карта не сохранялась); он используется для
оплаты по сохраненной карте.
Отмена/возврат средств оплаты заказа
POST /v1/ecom/payments/{orderId}/cancelДля отмены и возврата используется одна и та же ручка - вид операции определяется на сервере:
- Отмена - в день оплаты для одностадийных платежей или до проведения второй стадии для двухстадийных. Комиссия не списывается.
- Возврат - в другие дни для одностадийных платежей или после проведения второй стадии для двухстадийных.
Например: одностадийный платеж оплачен 1 мая - отмена 1 мая будет отменой, 2 мая - возвратом. Двухстадийный: до второй стадии - отмена, после - возврат.
Доступность операций по статусам:
| Операция | Одностадийный | Двухстадийный |
|---|---|---|
| Полный/частичный возврат | через сутки после оплаты, статусы «Завершен» (1), «Частично отменен» (7), «Частично возвращен» (8) | «Завершен» (1), «Частично отменен» (7), «Частично возвращен» (8), «Ожидает списания» (11) |
| Полная/частичная отмена | в день оплаты, статусы «Завершен» (1), «Частично отменен» (7) | «Ожидает списания» (11), «Частично отменен» (7) |
Частичная отмена доступна только для Т-Банка (в Альфа-Банке недоступна). В Альфа-Банке независимо от дня всегда будет частичный возврат.
Параметры запроса
| Параметр | Описание | Обяз. | Формат |
|---|---|---|---|
amount | Сумма возврата в копейках. Если не указана - полный возврат/отмена. Передается только вместе с positions (и наоборот): один параметр без второго вернет ошибку | Нет | number |
positions | Список позиций для частичной отмены/возврата. Обязателен при частичном возврате заказа с чеком | Нет | array |
positions[].parentItemId | Идентификатор родительской позиции | Да | string |
positions[].sum | Сумма за позицию в копейках | Да | number |
positions[].quantity | Количество предмета расчета в тысячных (999000 = 999.000) | Да | number |
Расчет sum и quantity при частичном возврате с чеком
Сервис проверяет каждую позицию по формуле sum = round(quantity / 1000 * price)
(округление до целого по правилам математики), а amount - как сумму всех
sum. Если хоть одно значение не сходится, вернется ошибка
(INVALID_POSITION_AMOUNT, INVALID_REFUND_RECEIPT_AMOUNT).
- Покупатель задает сумму - считайте
quantity = round(sum / price * 1000). - Покупатель задает количество - считайте
sum = round(quantity / 1000 * price). - На последнем частичном возврате всегда передавайте остатки
sumиquantityиз метода refund-items без вычислений: из-за округлений цена последнего возврата может отличаться от цены позиции.
Пример: заказ на 169 копеек с позицией price: 5133, quantity: 33
(51,33 ₽ × 0,033). Три возврата по quantity: 11 - sum 56, 56 и 57:
последний забирает накопившийся остаток, итого 169 и 33.
{
"amount": 10000,
"positions": [
{
"parentItemId": "e11b21fa-58e7-4918-bb38-159065c36a62",
"sum": 1000,
"quantity": 999000
}
]
}{ "status": "success", "message": "OK" }Отмена асинхронная - ответ не означает, что возврат прошел
Ответ подтверждает прием запроса, а не завершение операции. На тестовом контуре реальный вызов вернул:
{ "status": "success", "message": "Заказ в процессе отмены" }Поле message содержит произвольный текст и не является признаком результата.
Итог читайте отдельным запросом
статуса заказа: 4 - отменен, 5 - возвращен,
7/8 - частичная отмена и частичный возврат. Не помечайте заказ
возвращенным по ответу на /cancel и не повторяйте отмену вслепую, если
ответ не пришел, - сначала перечитайте статус.
Списание средств по двухстадийной оплате
POST /v1/ecom/payments/{orderId}/depositПосле успешной оплаты двухстадийной транзакции сумма замораживается на счету покупателя. При отсутствии возвратов и отмены запросите списание в течение 7 суток после проведения транзакции - этим методом или кнопкой «Провести списание» в ЛК. Автоматически списание не происходит.
POST /v1/ecom/payments/b0d84710-71f0-49ee-8219-f1b31a8d6770/deposit{ "status": "success", "message": "OK" }Возвращаемые позиции заказа
GET /v1/ecom/payments/{orderId}/refund-itemsВозвращает список позиций чека, доступных к возврату по заказу (используйте
перед частичным возвратом с фискализацией, чтобы получить parentItemId
и остатки количества). Метод работает только для оплаченных заказов;
полностью возвращенные позиции в ответ не попадают, после полного возврата
список пуст.
Поле ответа (data.positions[]) | Описание | Формат |
|---|---|---|
parentItemId | Идентификатор родительской позиции - передается в positions[].parentItemId метода отмены/возврата | string |
name | Наименование позиции | string |
price | Цена за единицу в копейках | number |
quantity | Доступное к возврату количество в тысячных (999000 = 999.000) | number |
sum | Сумма позиции в копейках | number |
measure | Единица измерения - см. Чеки | number |
{
"status": "success",
"data": {
"positions": [
{
"parentItemId": "e11b21fa-58e7-4918-bb38-159065c36a62",
"name": "Товар",
"price": 1000,
"quantity": 10000,
"sum": 10000,
"measure": 3
}
]
}
}См. также
- Callback-уведомления - как узнать о смене статуса.
- Сохраненные карты и рекуррентные платежи.
- Коды ошибок.