Регистрация платежа

Введение

Предварительно должна быть создана платежная сессия:

либо для разовой оплаты;
либо для оплаты с последующим созданием подписки;
либо платежный токен.

Для запуска процесса оплаты используем данный метод. Этот процесс оплаты в последующем необходимо подтвердить (по технологии с 3DSecure, по коду из SMS (otp) или иной способ). Какой вариант подтверждения необходимо провести – будет понятно из ответа вызова данного метода, параметр "confirmType" со значением "secure3d" или "otp".

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

Входные параметры

Метод работает без параметра CancellationToken. т.к. при вызове метода - обязательно процесс должен пройти до своего логического конца.

Заголовок запроса

POST
Endpoint: /payment/process HTTP/1.1
Content-Type: application/json
Session-Id: {значение}
<Основные параметры>

Основные параметры

Поле	Тип	Обяз.	Описание
Request-Id	guid	да	Идентификатор конкретного запроса
Requestor-Name	string	нет	Наименование сервиса. Для веба - домен, на котором запущен виджет. Для SDK - идентификатор приложения. Для API - имя вызывающей системы.
Requestor-Type	string	нет	Тип витрины. API Web Widget Web Page SDK Apple SDK Android
Requestor-Version	string	нет	Версия виджета/sdk

Поле	Тип	Обяз.	Описание
Session-Id	string [32]	да	Идентификатор платежной сессии

Тело запроса

Поле	Тип	Обяз.	Описание
ssoTokenId	base64	условно	Идентификатор токена МТС Логин (id_token)
ssoCookie	base64	условно	Идентификатор сессии пользователя МТС Логин (значение куки MTSWebSSO)
paymentTool	paymentTool	да	Структура с данными по источнику оплаты
loyalty	object	нет	Данные о программе лояльности, которая была использована в платеже

Обязательность ssoTokenId и ssoCookie полей:

Если не был вызван метод получение ПИ и информации о платеже, то должен быть передан один из двух параметров ssoTokenId или ssoCookie. Если переданы оба, то идентификация будет выполнена по параметру ssoTokenId.

Описание структуры paymentTool

Поле	Тип	Обяз.	Описание
id	string	нет	Идентификатор платежного инструмента
ewalletBinding card extMobileСommerce sberPay vtbPay sbp cbdc	object	нет	Структура с данными, соответствующими типу ПИ (способу оплаты)

Описание paymentTool

Значение	Описание способа оплаты
ewalletBinding	Оплата со счета электронного кошелька МТС Деньги
card	Банковская карта Visa, Mastercard и другие
extMobileСommerce	Лицевой счет сторонних операторов При передачи способа оплаты extMobileСommerce, никаких доп. параметров не требуется (см. пример).
sberPay	Оплата через приложение sberPay
vtbPay	оплат через приложение ВТБ-Пей
cbdc	Структура с параметрами метода цифровой рубль
sbp	Оплата через СБП

Описание структуры ewalletBinding

Поле	Тип	Обяз.	Описание
bindingId	string	да	Идентификатор счета/токена

Описание структуры card

Поле	Тип	Обяз.	Описание
number	string	да	Данные платежного инструмента
expityMonth	int32[2]	да	Месяц действия карты (MM)
expiryYear	int32[4]	да	Год действия карты (YYYY)
cvc	string[3]	да	СVC-код
ownerName	string[200]	нет	Имя держателя карты

Описание структуры sberPay

Поле	Тип	Обяз.	Описание
flowType	string(enum)	да	web ios android
isCreateBinding	boolean	нет	запрос на создание cчета СберПей

Описание структуры vtpPay

Поле	Тип	Обяз.	Описание
returnUrl	String	нет	URL на веб-сайте продавца, куда будет переведен покупатель в случае успешной оплаты или обратного перехода
hasReturnButton	String	нет	Признак отрисовки кнопки "вернуть куда-то". Если используется дефолтная страница мтсПей

Описание структуры sbp

Поле	Тип	Обяз.	Описание
redirectUrl	string	нет	Ссылка для редиректа пользователя после оплаты
isSbpTokenCreate	boolean	нет	Признак запроса на создание СБП Счета

Описание структуры cbdc

Поле	Тип	Обяз.	Описание
redirectUrl	string	нет	Ссылка для редиректа пользователя после оплаты

Описание структуры loyalty

Поле	Тип	Обяз.	Описание
amount	int	нет	Сумма баллов программы лояльности пользователя, использованная для оплаты. Платеж кэшбэком не может полностью закрывать оплату, минимум 1 рубль должен быть оплачен основным платежным инструментом.
isNextWithdrawalEnable	boolean	нет	Признак списания баллов лояльности для следующих операций. Актуально для сценариев подписки. По умолчанию false

Поле

Тип

Обяз.

Описание

amount

int

нет

Сумма баллов программы лояльности пользователя, использованная для оплаты.

Платеж кэшбэком не может полностью закрывать оплату, минимум 1 рубль должен быть оплачен основным платежным инструментом.

isNextWithdrawalEnable

boolean

нет

Признак списания баллов лояльности для следующих операций. Актуально для сценариев подписки. По умолчанию false

Выходные параметры

Заголовок ответа

Content-Type: application/json; charset=utf-8
http-code: 200
http-status: OK

Тело ответа

Поле	Тип	Обяз.	Описание
confirm	object	нет	Обязательно, если требуется подтверждение операции
result	object	нет	Обязательно, если подтверждение не требуется и процесс завершен

Описание структуры confirm

Поле	Тип	Обяз.	Описание
entity	entityEnum	да	Требуется подтвердить процесс: payment - платеж subscription - подписку или иное
tool	object	да	Способ подтверждения.

Поле

Тип

Обяз.

Описание

entity

entityEnum

да

Требуется подтвердить процесс:

payment - платеж
subscription - подписку
или иное

tool

object

да

Способ подтверждения.

Описание структуры tool

Поле	Тип	Обяз.	Описание
type	typeEnum	да	Требуется подтверждение: secure3D, card3ds2. otp extAuth sberPay vtbPay sbp cbdc
card3ds	object	нет	Параметры для проведения процедуры 3DSecure.
card3ds2	object	нет	Параметр для проведения процедуры 3DSecure 2.0.
otp	object	нет	Параметры для проведения процедуры OTP.
extAuth	object	нет	Сторонняя аутентификация
sberPay	object	нет	аутентификация сберпей
vtbPay	object	нет	аутентификация втбпей
sbp	object	нет	аутентификация СБП
cbdc	object	нет	аутентификация цифровой рубль

Описание структуры card3ds

Поле	Тип	Обяз.	Описание
acsUrl	string	да	URL-адрес банка эмитента (сервер ACS), на который клиент должен быть перенаправлен
PaReq	string	да	Параметр для проведения процедуры 3DSecure
termUrl	string	да	URL-адрес для передачи PaRes от банка эмитента

Описание структуры card3ds2

Поле	Тип	Обяз.	Описание
threeDsServerTransId	string	нет	Уникальный идентификатор транзакции 3DS 2.0
threeDsMethodUrl	string	нет	URL 3D Secure метода ACS-сервера эмитента
threeDsMethodData	string	нет	BASE-64 данные для 3D Secure метода

Описание структуры otp

Поле	Тип	Обяз.	Описание
leftUntilResendAttempt	int32	да	Период в секундах, через который можно запросить повторный OTP код
phone	string	да	Номер мобильного телефона пользователя, в маскированном формате ****99-99

Описание структуры sberPay

Поле	Тип	Обяз.	Описание
sdk	object	условно	URL-адрес страницы запуска приложения подтверждения
web	object	условно	Уникальный идентификатор мерчанта в Sber

Описание структуры web

Поле	Тип	Обяз.	Описание
authUrl	string	да	URL-адрес страницы запуска приложения подтверждения
bankInvoiceId	string	да	идентификатор платежа в системе Сбер(order_id)
sbolDeepLink	string	да	Ссылка на переход в мобильное приложение "Сбербанк-Онлайн" для завершения оплаты. Оплата без использования sdk-sberpay.

Описание структуры sdk

Поле	Тип	Обяз.	Описание
merchantLogin	string	да	Уникальный идентификатор мерчанта в Sber
bankInvoiceId	string	да	идентификатор платежа в системе Сбер(order_id)
orderNumber	string	да	идентификатор платежа в системе МтсПей(payment_id)
apiKey	string	да	ключ Партнера(merchantLogin) для работы с сервисами платежного шлюза через SDK
sbolDeepLink	string	да	Ссылка на переход в мобильное приложение "Сбербанк-Онлайн" для завершения оплаты. Оплата без использования sdk-sberpay.

Описание структуры vtbPay

Поле	Тип	Обяз.	Описание
browser	string	да	URL-адрес страницы запуска приложения подтверждения
android	string	да	URL-адрес страницы запуска приложения подтверждения
ios	string	да	URL-адрес страницы запуска приложения подтверждения

Описание структуры sbp

Поле	Тип	Обяз.	Описание
paymentPageUrl	string	да	Ссылка на форму оплаты счета (платежную страницу)
qrcId	string	да	Идентификатор зарегистрированного QR кода в СБП

Описание структуры cbdc

Поле	Тип	Обяз.	Описание
paymentPageUrl	string	да	Ссылка на форму оплаты счета (платежную страницу)
qrcId	string	да	Идентификатор зарегистрированного QR кода в цифровой рубль

Описание структуры result

Поле	Тип	Обяз.	Описание
operationDate	dateTime	да	Дата и время выполнения операции

Пример

Заголовок запроса

POST /payment/process HTTP/1.1
Host:
Content-Type: application/json
Request-Id: 5cdd933a-48d0-4f59-a1a0-3b76f3fae658
Session-Id: d6946779-dd1a-4e91-8e21-e0ddc8a00288

Тело запроса

{
  "paymentTool": {
    "extMobileСommerce": {}
  }
}

{
  "paymentTool" : {
    "id" : "8df44628-5fe8-40b8-8a2d-e214209a5cae"
  },
  "loyalty": {
    "amount": 100,
    "isNextWithdrawalEnable": true
  }
}

{
  "paymentTool": {
    "type": "card",  //не обязательное
    "card": {
      "number": "5366720491618146",
      "expiryMonth": 7,
      "expiryYear": 2023,
      "cvc": "251",
      "ownerName": "Ivan Ivanov",
      "needSaveCard": true
    }
  }
}

{
  "paymentTool" :
  {
    "type" : "ewalletBinding", //не обязательное
    "ewalletBinding" :
    {
      "id" : "1147849C95D145B196878C93922C3FFF"
    }
  }
}

Заголовок ответа

Content-Type: application/json; charset=utf-8
http-code: 200
http-status: OK

Тело ответа

{
  "confirm": {
    "entity": "payment",
    "tool": {
      "type": "card3ds",
      "сard3ds": {
        "acsUrl": "string",
        "paReq": "string",
        "termUrl": "string"
      }
    }
  }
}

   "confirm" :
  {
    "entity" : "payment",
    "tool" :
    {
      "type" : "card3ds2",
      "card3ds2":
      {
        "threeDsServerTransId" : "string",
        "threeDsMethodUrl" : "string",
        "threeDsMethodData" : "string"
      }
    }
  }
}

   "confirm": {
    "entity": "payment",
    "tool": {
      "type": "card3ds2"
    }
  }
}

{
  "confirm": {
    "entity": "payment",
    "tool": {
      "type": "otp"
    }
  }
}

{
  "result": {
    "operationDate": "2020-12-28T07:40:29.870Z"
  }
}

Возможные коды ошибок

code	message	userMessage
00100001	Session {0} not found	Сессия не найдена
00100002	WEBSSO: Authentication is not taken place	WEBSSO: Аутентификация не пройдена
00100003	The payment is already completed within this session {0}	Платеж уже завершен в рамках этой сессии
00100004	The sequence of operations is broken. {0}	В процессе проведения операции произошла ошибка. Попробуйте позже.
00100011	Payment tool not available	Операция не выполнена. Измените способ оплаты и попробуйте снова.
00100013	Missing required parameter of payment {service.params.name}	Отсутствует обязательный параметр оплаты {service.params.title}. Обратитесь в службу поддержки.
00100019	The operation is prohibited for unauthorized users	Операция запрещена для неавторизованных пользователей
00100020	Invoice payment declined	Платеж по счету отклонен
00100021	Invoice payment in progress	Платеж по счету в процессе проведения
00100023	Loyalty program not available	Списания с программы лояльности не доступны для данного платежа
00100024	Loyalty program not provided for this payment scenario	Программы лояльности не поддерживается для данного сценария платежа
00100025	Loyalty program amount is greater than the allowable repayment ratio	Сумма списания по программе лояльности больше максимального коэффициента данного платежа
00100026	Loyalty program amount is greater than the user's balance	Сумма списания по программе лояльности больше доступного пользователю баланса
00100027	Incorrect loyalty program amount	Некорректная сумма списания по программе лояльности
00100036	Failed to create payment token. Payment cancelled. Please try again.	Не удалось создать платежный токен. Платеж отменен. Повторите попытку.
00100043	Scenario cannot be continued because payment status in_progress	Произошла системная ошибка. Деньги списаны, но мы скоро их вернём
00199998	Validation error	Не пройдена валидация данных
00199999	An unexpected error has occurred	Непредвиденная ошибка
02000009	Error of check of parameters of payment.	Ошибка проверки параметров платежа. {текст сообщения от Мерчанта}
02000017	Payment completed unsuccessfully	Попробуйте повторить операцию или обратитесь в службу поддержки
02000021	Unknown operation status. Contact Support.	Неизвестный статус операции. Обратитесь в службу поддержки.
02005000	PCEK: unexpected error. extSystemErrorCode: [errorCode]	Непредвиденная ошибка
02005001	PCEK: payment confirmation problems. extSystemErrorCode: [errorCode]	Проблемы с подтверждением платежа. Попробуйте снова.
02005002	Processing: Card has expired	У карты истек срок действия
02005003	MPI: 3d secure problems. extSystemErrorCode: [errorCode]	Проблемы с подтверждением платежа. Попробуйте снова.
02005006	PCEK: payment limits restriction. extSystemErrorCode: [errorCode]	Превышен лимит на платежи через выбранный способ оплаты
02005007	PCEK: service unavailable	Сервис временно недоступен. Попробуйте повторить позже.
02005009	Processing: Insufficient funds	Недостаточно средств
02005011	Processing: Invalid CVC value	Неверное значение CVC2
02005013	Processing: Invalid card expiration date	Неверная дата истечения срока действия карты
02005014	Processing: Invalid card number	Неверный номер карты
02005016	Bank acquirer: invalid merchant or terminal. extSystemErrorCode: [errorCode]	Оплата через выбранный способ оплаты временно недоступна
02005017	Bank issuer: general error. extSystemErrorCode: [errorCode]	Ваш банк отклонил платёж
02005018	Bank issuer: potential fraud or safety restriction. extSystemErrorCode: [errorCode]	Оплата по выбранной карте недоступна
02005019	PCEK: payment declined. extSystemErrorCode: [errorCode]	Платёж отклонен. Смените способ оплаты и попробуйте снова.
02005023	PCEK: The amount is greater than the maximum allowed. extSystemErrorCode: [errorCode]	Сумма платежа больше максимально разрешенной
02005024	PCEK: The amount is less than the minimum allowed. extSystemErrorCode: [errorCode]	Сумма платежа меньше минимально разрешенной
02005025	PCEK: potential fraud or safety restriction. extSystemErrorCode: [errorCode]	Платёж отклонён системой безопасности
02005030	Acquiring bank refusal: fraud control	Операция не выполнена. Нарушение лимитов. Измените данные карты и попробуйте снова.
02005031	Processing: Incorrect payment parameters specified	Некорректные параметры оплаты. Обратитесь в службу поддержки.
02005032	Processing: Receiving payment to this number is prohibited	Приём платежа на этот номер запрещён. Попробуйте изменить услугу оплаты или обратитесь в поддержку 8-800-250-08-90.
02005033	PCEK Provider: The system cannot process the payment	Операция не выполнена. Выберите другой способ оплаты или обратитесь в службу поддержки.
02005034	PCEK FM: bank card is used in another account. extSystemErrorCode: [errorCode]	Банковская карта уже привязана к другому аккаунту
02005036	Bank issuer: payment restriction. extSystemErrorCode: [errorCode]	Ваш банк ограничил оплату с выбранной карты
02005037	PCEK: user is not found. extSystemErrorCode: [errorCode]	Пользователь не найден
02005040	PCEK FM: safety restriction. extSystemErrorCode: [errorCode]	Превышен лимит на платежи
02005042	PCEK: service unavailable. extSystemErrorCode: [errorCode]	Сервис временно недоступен
02005043	PCEK: bank issuer have some problems. extSystemErrorCode: [errorCode]	Ваш банк отклонил платёж
02005044	PCEK FM: potential fraud or safety restriction. extSystemErrorCode: [errorCode]	Платёж отклонён системой безопасности
02005046	PCEK: operation is unavailable. extSystemErrorCode: [errorCode]	Операция недоступна
02005047	PCEK Provider: service unavailable. extSystemErrorCode: [errorCode]	Сервис временно недоступен
02005048	PCEK Provider: wrong payment parameters specified. extSystemErrorCode: [errorCode]	Неверные реквизиты оплаты
02005049	PCEK: payment from billing account is not available. extSystemErrorCode: [errorCode]	Оплата со счёта телефона временно недоступна
02005051	ESPP: service unavailable. extSystemErrorCode: [errorCode]	Оплата временно недоступна
02005052	ESPP: client is legal entity. extSystemErrorCode: [errorCode]	Выбранный способ оплаты доступен только физическим лицам
02005053	ESPP: payment restriction installed by the client. extSystemErrorCode: [errorCode]	Оплата со счёта запрещена
02005054	ESPP: incorrect account parameters. extSystemErrorCode: [errorCode]	Оплата через выбранный способ оплаты временно недоступна
02005055	ESPP: insufficient funds. extSystemErrorCode: [errorCode]	Недостаточно средств
02005056	Bank issuer: insufficient funds extSystemErrorCode: [errorCode]	Недостаточно средств
02005057	Bank issuer: invalid CVC or another safety restriction. extSystemErrorCode: [errorCode]	Неверный код безопасности (CVC/CVV)
02005058	Bank issuer: card expired. extSystemErrorCode: [errorCode]	Истек срок действия карты
02005060	Bank issuer: potential fraud or safety restriction. extSystemErrorCode: [errorCode]	Ваш банк отклонил платеж. Ограничения на карте.
02005061	Bank acquirer: general error. extSystemErrorCode: [errorCode]	Банк отклонил платёж
02005064	Bank issuer: payment restriction. extSystemErrorCode: [errorCode]	Ваш банк ограничил оплату с выбранной карты
02005065	Bank acquirer: fatal general error. extSystemErrorCode: [errorCode]	Банк отклонил платёж
02006001	MasterHub: Request error	Операция не выполнена. Попробуйте позже.
02006002	MasterHub: Payment error	Операция не выполнена. Попробуйте позже.
02006003	MasterHub: MSISDN not correct	Операция не выполнена. Проверьте номер телефона и попробуйте снова.
02006004	MasterHub: contentId not found	Операция не выполнена. Попробуйте позже.
02006300	chargingEP: Insufficient funds	Недостаточно средств. Измените способ оплаты и попробуйте снова.
02006301	chargingEP: Payment cannot be processed according to these parameters	Данный способ оплаты не может быть использован для этого пользователя. Выберете другой способ оплаты или обратитесь в службу поддержки.
02006302	chargingEP: The system cannot process the payment	Операция не выполнена. Попробуйте повторить операцию или обратитесь в службу поддержки.
02006303	chargingEP: The system cannot process the payment	Операция не выполнена. Выберете другой способ оплаты или обратитесь в службу поддержки.
02006304	chargingEP: Account is partially blocked, there are not enough funds.	Недостаточно средств. Погасите задолженность или измените способ оплаты
03000007	Subscription {0} not found from merchant {1}	Подписка не найдена
03000008	Invalid operation for current subscription status: Current status: {0}	Подписка в статусе {}, над которым данная операция запрещена
03005002	The limit of subscriptions to the user is exceeded	Превышен лимит подписок на пользователя