Перейти к содержимому

Платежи

Методы работы с платежами АТОЛ 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>.

Для взаимодействия с платежной формой необходимо поддерживать основной метод - регистрацию платежа, и три опциональных: списание по двухстадийной оплате, отмену/возврат и проверку статуса заказа.

Метод регистрации платежа

http
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.returnUrlURL для кнопки «Вернуться в магазин» на платежной формеДаstring(255)
additionalProps.appReturnUrlURL для кнопки «Вернуться в приложение». Используется только в режиме 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[].paymentTypecard / bank_app / sbp / bnpl / accountДаstring
paymentMethods[].bankIdИдентификатор банка (таблица выше)Даnumber
paymentMethods[].accountUrlURL для оплаты по счетуНет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.mainstring
data.paymentUrls.mainСсылка на главную страницу формы оплатыstring
data.paymentUrls.mainFrameТо же для отображения внутри фреймаstring
data.paymentUrls.mainAppТо же для отображения внутри приложенияstring
data.paymentUrls.directПрямые ссылки на конкретный метод оплаты без главной страницы: card, tpay, dolyame, sbp, accountobject
data.paymentUrls.directFrame / directAppТо же для фрейма / приложенияobject
data.positions[]Позиции заказа: id (UUID позиции), name, price, sum, quantity, measure, receiptarray

paymentUrl устарел

Поле data.paymentUrl помечено в OpenAPI-спецификации как deprecated - перенаправляйте покупателя на data.paymentUrls.main.

При ошибке возвращаются status: "error", errorCode, errorMessage (HTTP 400 или 500).

Пример

json
{
  "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": "Адрес доставки" } ]
  }
}
json
{
  "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
      }
    ]
  }
}
json
{
  "errorCode": "SERVER_ERROR",
  "errorMessage": "some error message here",
  "status": "error"
}

Получение статуса платежа

http
GET /v1/ecom/payments/{orderId}/status

Запрашивайте статус, если callback не пришел в течение длительного времени.

Параметр ответаОписаниеФормат
statusСтатус выполнения запроса (success / error)string
data.statusЧисловое значение статуса платежа (см. таблицу ниже)number
data.statusMessageТекстовая интерпретация статусаstring
data.bindingIdID привязки сохраненной карты; null, если карта не сохраняласьstring | null
data.paymentUrlСсылка на форму оплатыstring
json
{
  "status": "success",
  "data": {
    "status": 0,
    "statusMessage": "Платеж находится в обработке"
  }
}

Статусы платежа

КодЗначениеРасшифровка
0processingВ обработке
1successУспех (выполнен)
2notRespondingБанк не ответил
3errorОплата с ошибкой, повтор операции невозможен
4canceledОтменен
5refundedВозвращен
6fraudПодозрение в мошенничестве
7partialCancelЧастичная отмена
8partialRefundЧастично возвращен
9paymentIsOverdueПлатеж просрочен
10confirm3dsПодтверждение 3-D Secure
11awaitingDepositОжидает списания по двухстадийной оплате
12retryErrorОплата с ошибкой, возможен повтор операции
255cardCheckedКарта проверена (привязка карты без списания средств)

Ответ также содержит data.bindingId - ID привязки сохраненной карты (null, если карта не сохранялась); он используется для оплаты по сохраненной карте.

Отмена/возврат средств оплаты заказа

http
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.

json
{
  "amount": 10000,
  "positions": [
    {
      "parentItemId": "e11b21fa-58e7-4918-bb38-159065c36a62",
      "sum": 1000,
      "quantity": 999000
    }
  ]
}
json
{ "status": "success", "message": "OK" }

Отмена асинхронная - ответ не означает, что возврат прошел

Ответ подтверждает прием запроса, а не завершение операции. На тестовом контуре реальный вызов вернул:

json
{ "status": "success", "message": "Заказ в процессе отмены" }

Поле message содержит произвольный текст и не является признаком результата. Итог читайте отдельным запросом статуса заказа: 4 - отменен, 5 - возвращен, 7/8 - частичная отмена и частичный возврат. Не помечайте заказ возвращенным по ответу на /cancel и не повторяйте отмену вслепую, если ответ не пришел, - сначала перечитайте статус.

Списание средств по двухстадийной оплате

http
POST /v1/ecom/payments/{orderId}/deposit

После успешной оплаты двухстадийной транзакции сумма замораживается на счету покупателя. При отсутствии возвратов и отмены запросите списание в течение 7 суток после проведения транзакции - этим методом или кнопкой «Провести списание» в ЛК. Автоматически списание не происходит.

http
POST /v1/ecom/payments/b0d84710-71f0-49ee-8219-f1b31a8d6770/deposit
json
{ "status": "success", "message": "OK" }

Возвращаемые позиции заказа

http
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
json
{
  "status": "success",
  "data": {
    "positions": [
      {
        "parentItemId": "e11b21fa-58e7-4918-bb38-159065c36a62",
        "name": "Товар",
        "price": 1000,
        "quantity": 10000,
        "sum": 10000,
        "measure": 3
      }
    ]
  }
}

См. также