Запросы API v1.1.0
Кошелёк Pay API
Документация перемещена
Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:
В следующих версиях документа в запросы и/или ответы могут быть добавлены новые необязательные поля.
Для обеспечения обратной совместимости необходимо игнорировать их при формировании запросов и при приеме ответов от сервера до внесения соответствующих изменений в ПО, работающее на стороне ТСП.
Запрос списка возможных провайдеров платежей
HTTP-метод: POST
URL: /api/v1/merchant/availability-info/task
Описание
ТСП передает Кошельку информацию о счете к оплате и создает задачу на получение данных о провайдерах платежей.
В зависимости от кода ответа на запрос определяется способ получения списка провайдеров платежей:
1) Синхронный: ответ на вызов содержит HTTP Status Code 200
. При этом в теле ответа содержатся непосредственно запрашиваемые данные о провайдерах платежей.
2) Асинхронный: ответ на вызов содержит HTTP Status Code 201
. При этом в теле ответа будет содержаться поле availabilityInfoId
, а в HTTP-заголовке Location — URL, который необходимо периодически опрашивать для получения данных о провайдере, используя запрос /api/v1/merchant/availability-info/{availabilityInfoId}
.
Принципы получения списка доступных провайдеров платежей
Параметры запроса
Параметры заголовка запроса
Параметр | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Состоит из значения параметра |
Параметры тела запроса
Тело запроса передается в виде объекта JSON следующей структуры:
Поле | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Уникальный идентификатор запроса (GUID, 36 символов). Если по каким-либо причинам ответ на запрос не получен от Кошелька, то можно отправить этот запрос повторно, используя то же самое значение параметра |
| String | Да | Идентификатор сессии, извлеченный ТСП из штрихкода при сканировании карты или с информацией о QR-коде (не более 32 символов, латинские буквы и цифры, либо 6 символов для одномерных штрихкодов). |
| String | Да | Идентификтор ТСП, выданный Cardsmobile при его подключении (GUID, 36 символов). |
| String | Да | Идентификатор кассы (256 символов). |
| Object CheckoutInvoice | Да | Информация о пречеке. |
| Object User | Да | Информация о пользователе. |
Параметры ответа
HTTP Status Code: 200
Запрос выполнен успешно, ответ содержит сведения о списке провайдеров платежей (используется синхронный режим).
Тело ответа — объект JSON следующей структуры:
Пoле | Тип | Обязательно | Значение |
---|---|---|---|
| Boolean | Да | Флаг автоматического выбора и запуска на кассе оплаты через Кошелёк Pay по умолчанию. Если |
| Array of paymentTypeAvailabilityInfo | Да | Массив, содержащий в себе список доступных провайдеров платежей. |
HTTP Status Code: 201
Запрос выполнен успешно, ответ содержит сведения для отдельного запроса на получение списка доступных провайдеров платежей (используется асинхронный режим).
Заголовок ответа:
Тело ответа — объект JSON следующей структуры:
Поле | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Идентификатор, по которому можно запросить информацию о списке доступных провайдеров платежей. |
| Integer | Да | Время, через которое необходимо осуществить первую проверку статуса готовности в запросе |
HTTP Status Code: 422
Запрос не выполнен. Тело ответа — объект JSON, описывающий ошибку.
Получение списка доступных провайдеров платежей
HTTP-метод: GET
URL: /api/v1/merchant/availability-info/{availabilityInfoId}
Описание
ТСП запрашивает у Кошелька список доступных провайдеров платежей в асинхронном режиме, т. е. если запрос /api/v1/merchant/availability-info/task
вернул HTTP Status Code 201
.
В этом случае методы /api/v1/merchant/availability-info/task
и /api/v1/merchant/availability-info/{availabilityInfoId}
используются в паре (принцип периодического опроса — поллинга).
Необходимо последовательно:
1) вызвать api/v1/merchant/availability-info/task
, получить availabilityInfoId
__ (идентификатор, используя который, можно будет впоследствии получить данные), и timeout
__ (время, через которое необходимо осуществить первую проверку статуса готовности)
2) вызывать метод api/v1/merchant/availability-info/{availabilityInfoId}
с периодом ожидания, равным timeout
для первого вызова и pollingTimeout
для последующих вызовов до тех пор, пока в ответе поле computationComplete
не будет содержать значение true
).
Параметры запроса
Отсутствуют.
Параметры ответа
HTTP Status Code: 200
Запрос выполнен успешно. Тело ответа — объект JSON следующей структуры:
Поле | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Идентификатор, полученный в запросе. |
| Boolean | Да | Готовность результата запроса:
|
| Long | Да | Инструкция от сервера: отправить повторный запрос через указанное время (в миллисекундах). Передается, если |
| Boolean | Да | Флаг автоматического выбора и запуска на кассе оплаты через Кошелёк Pay по умолчанию. Если |
| Array of PaymentTypeAvailabilityInfo | Да | Массив, содержащий в себе список доступных провайдеров платежей. |
HTTP Status Code: 422
Запрос не выполнен.
Тело ответа — объект JSON, описывающий ошибку.
Инициализация платежа
HTTP-метод: POST
URL: /api/v1/merchant/checkout
Описание
ТСП передает Кошельку информацию о счёте к оплате и значение cardSession
пользователя, который должен оплатить этот счёт.
Параметры запроса
Параметры заголовка запроса
Параметр | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Состоит из значения параметра |
Параметры тела запроса
Тело запроса передается в виде объекта JSON следующей структуры:
Поле | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Уникальный идентификатор запроса (GUID, не более 36 символов). Если по каким-либо причинам ответ на запрос не получен от Кошелька, то можно отправить этот запрос повторно, используя то же самое значение параметра |
| String | Да | Идентификатор сессии, извлеченный ТСП из штрихкода при сканировании карты или с информацией о QR-коде (не более 32 символов, латинские буквы и цифры, либо 6 символов для одномерных штрихкодов). |
| String | Да | Идентификтор ТСП, выданный Cardsmobile при его подключении (GUID, 36 символов). |
| String | Да | Идентификатор кассы (256 символов). |
| Object CheckoutInvoice | Да | Информация о пречеке. |
| Object User | Да | Информация о пользователе. |
| Array of PaymentMethod | Да | Массив объектов, содержащий в себе информацию о способах оплаты, поддерживаемых ТСП. |
Параметры ответа
HTTP Status Code: 200
Запрос выполнен успешно.
Тело ответа — объект JSON следующей структуры:
Поле | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Уникальный идентификатор запроса. |
| String | Да | Идентификатор транзакции. |
| Enum | Да | Статус транзакции:
|
| Object Slip | Зависит от значения поля | Объект Slip, содержащий данные о проведенной банковской операции. Будет возвращен, если операция оплаты была проведена через банк (статусы |
HTTP Status Code: 422
Запрос не выполнен. Тело ответа — объект JSON, описывающий ошибку.
Получение статуса транзакции
HTTP-метод: POST
URL: /api/v1/merchant/transaction/status
Описание
Ответ со статусами платежной транзакции и транзакции отмены. a. Реализация приема postback/callback ответов от Кошелька
ТСП необходимо реализовать на своей стороне метод, который будет вызывать сервер Кошелька для передачи ТСП статуса платежа. Этот способ получения статуса является предпочтительным, т.к. в данном случае сервер Кошелька сразу передает ТСП ответ, и ТСП не нужно работать в режиме polling c сервером Кошелька с запросом b в ожидании ответа с финальным статусом транзакции. Сервер Кошелька должен передавать при вызове метода тот же объект, который возвращает в response на вызов b. Схема работы через периодические вызовы метода b со стороны ТСП должна использоваться в случае технической невозможности подключения сервера Кошелька к серверу ТСП (или напрямую к кассам) для передачи ответов через postback. Request body: см. Response body в пункте b. b. Реализация подключения к методу получения статуса от сервера Кошелька.
Рекомендации по вызову метода
Статус транзакции необходимо запрашивать:
В первый раз: не раньше чем через 250 мс и не позже чем через 500 мс.
Дальнейшие вызовы должны быть не чаще чем раз в 250 мс.
Касса должна ожидать статус не дольше, чем 30 секунд, и вызывать отмену оплаты, если время ожидания превышено.
Конкретная реализация остается на усмотрение ТСП, но важно убедиться, что не остается никакого потока, который продолжает опрашивать серверы Кошелька.
Параметры запроса
Тело запроса передается в виде объекта JSON следующей структуры:
Поле | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Уникальный идентификатор запроса (GUID, не более 36 символов). Если по каким-либо причинам ответ на запрос не получен от Кошелька, то можно отправить этот запрос повторно, используя то же самое значение параметра |
| String | Нет | Идентификатор транзакции оплаты (GUID, 36 символов). Необязателен, если передается |
| String | Нет | Идентификатор транзакции отмены (GUID, 36 символов). Необязателен, если передается |
Параметры ответа
HTTP Status Code: 200
Запрос выполнен успешно.
Тело ответа — объект JSON следующей структуры:
Поле | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Уникальный идентификатор запроса. |
| String | Да | Идентификатор транзакции оплаты. |
| String | Нет | Идентификатор транзакции отмены. |
| Enum | Да | Статус транзакции:
— или пустое значение, если указанный в запросе |
| Enum | Да | Категория оплат:
|
| Enum | Да | Тип провайдера:
|
| Object Slip | Зависит от значения поля | Объект Slip, содержащий данные о проведенной банковской операции. Будет возвращен, если операция оплаты была проведена через банк (статусы |
| Enum | Нет | Статус транзакции отмены:
|
| Enum | Нет | Код ошибки, возникшей при выполнении операции оплаты или возврата. Параметр передается только для |
Возможные значения параметра errorCode
errorCode
1. Для сценария оплаты:
Значение | Описание |
---|---|
| Превышен лимит для совершения операции. |
| Сумма покупки ниже установленного лимита (составляет 4 рубля). |
| Общий код ошибки провайдера платежей. |
| Привязанный счет пользователя не найден (платеж через СБП с привязанного счета пользователя). |
| Платеж отклонен банком (платеж через СБП с привязанного счета пользователя). |
2. Для сценария возврата:
Значение | Описание |
---|---|
| Возврат отклонен, т.к. транзакция оплаты с данным |
| Возврат отклонен по одной из причин:
|
| Возврат отклонен, т.к. есть незавершенная транзакция отмены. Дождитесь завершения процесса возврата по транзакции отмены с |
| Возврат отклонен, т.к. запрошенная сумма к возврату превышает сумму оплаты по транзакции оплаты с данным |
| Общий код ошибки провайдера платежей. |
| Возврат отклонен, т.к. транзакция оплаты с данным |
| Только для транзакций СБП. Не найдено платежное поручение в банке ТСП при выполнении операции возврата. |
HTTP Status Code: 422
Запрос не выполнен. Тело ответа — объект JSON, описывающий ошибку.
Отправка чека
HTTP-метод: POST
URL: /api/v1/merchant/transaction/receipt
Описание
ТСП передает Кошельку информацию о фискальном чеке для его отображения пользователю в Кошельке.
Параметры запроса
Тело запроса передается в виде объекта JSON следующей структуры:
Поле | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Уникальный идентификатор запроса (GUID, не более 36 символов). Если по каким-либо причинам ответ на запрос не получен от Кошелька, то можно отправить этот запрос повторно, используя то же самое значение параметра |
| String | Да | Идентификатор транзакции оплаты (GUID, 36 символов). |
| String | Да | Идентификтор ТСП, выданный Cardsmobile при его подключении (GUID, 36 символов). |
| String | Да | Идентификатор кассы (256 символов). |
| Object Invoice | Да | Информация о счете в формате "ключ-значение". См. объект Invoice. |
| Object | Нет | Объект, содержащий дополнительные поля, например: скидки, бонусы и т.д. (набор пар "ключ-значение"). |
Параметры ответа
HTTP Status Code: 200
Запрос выполнен успешно. Тело ответа — пустое.
HTTP Status Code: 422
Запрос не выполнен. Тело ответа — объект JSON, описывающий ошибку.
Отмена оплаты
HTTP-метод: POST
URL: /api/v1/merchant/transaction/cancel
Описание
ТСП передает Кошельку запрос на отмену транзакции оплаты.
В запросе не указывается сумма отмены, т.к. операция отмены проводится на полную сумму, указанную в транзакции оплаты.
Параметры запроса
Тело запроса передается в виде объекта JSON следующей структуры:
Поле | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Уникальный идентификатор запроса (GUID, не более 36 символов). Если по каким-либо причинам ответ на запрос не получен от Кошелька, то можно отправить этот запрос повторно, используя то же самое значение параметра |
| String | Да | Идентификтор ТСП, выданный Cardsmobile при его подключении (GUID, 36 символов). |
| String | Да | Идентификатор кассы (256 символов). |
| String | Да | Идентификатор транзакции оплаты (GUID, 36 символов). |
Параметры ответа
HTTP Status Code: 200
Запрос выполнен успешно.
Тело ответа — объект JSON следующей структуры:
Поле | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Уникальный идентификатор запроса. |
| String | Да | Идентификатор транзакции отмены. |
| Enum | Да | Статус транзакции отмены:
|
| String | Да | Идентификатор транзакции оплаты. |
| Enum | Да | Статус транзакции оплаты, в который она перешла после вызова отмены (или в котором она осталась, если отмена была отклонена):
|
| Object Slip | Зависит от значения поля | Объект Slip, содержащий данные о проведенной банковской операции. Будет возвращен, если операция оплаты была проведена через банк (статусы |
HTTP Status Code: 422
Запрос не выполнен. Тело ответа — объект JSON, описывающий ошибку.
Возврат оплаты
HTTP-метод: POST
URL: /api/v1/merchant/transaction/refund
Описание
ТСП передает Кошельку запрос на возврат покупателю средств, полученных в результате транзакции оплаты.
Параметры запроса
Параметры заголовка запроса
Параметр | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Состоит из значения параметра |
Параметры тела запроса
Тело запроса передается в виде объекта JSON следующей структуры:
Поле | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Уникальный идентификатор запроса (GUID, не более 36 символов). Если по каким-либо причинам ответ на запрос не получен от Кошелька, то можно отправить этот запрос повторно, используя то же самое значение параметра |
| String | Да | Идентификатор ТСП, выданный Cardsmobile при его подключении (GUID, 36 символов). |
| String | Да | Идентификатор кассы (256 символов). |
| String | Да | Идентификатор транзакции оплаты (GUID, 36 символов). |
| Number | Да | Сумма возврата в копейках. Не должна превышать сумму оплаты. Только положительное значение. |
| String | Нет | Трехбуквенный код валюты в формате ISO-4217:
|
| Array of Item | Да | Массив товаров, включенных в возвращаемую покупку (каждый товар — объект Item). |
Параметры ответа
HTTP Status Code: 200
Запрос выполнен успешно.
Тело ответа — объект JSON следующей структуры:
Поле | Тип | Обязательно | Значение |
---|---|---|---|
| String | Да | Уникальный идентификатор запроса. |
| String | Да | Идентификатор транзакции возврата. |
| Enum | Да | Статус транзакции возврата:
|
| String | Да | Идентификатор транзакции оплаты. |
| Enum | Да | Статус транзакции оплаты, в который она перешла после вызова отмены (или в котором она осталась, если отмена была отклонена):
|
| Object Slip | Нет | Объект Slip, содержащий данные о проведенной банковской операции. Будет возвращен, если операция оплаты уже была была проведена через банк (статусы |
| Enum | Нет | Код ошибки, возникшей при выполнении операции возврата. Передается только для |
Возможные значения параметра errorCode
errorCode
Значение | Описание |
---|---|
| Возврат отклонен, т.к. транзакция оплаты с данным |
| Возврат отклонен, т.к. транзакция:
|
| Возврат отклонен, т.к. уже есть незавершенная транзакция отмены. Дождитесь завершения процесса возврата по транзакции отмены с |
| Возврат отклонен, т.к. запрошенная сумма к возврату превышает сумму оплаты по транзакции оплаты с данным |
| Общий код ошибки провайдера платежей |
| Возврат отклонен, т.к. транзакция оплаты с данным |
| Только для транзакций СБП. Не найдено платежное поручение в банке ТСП при выполнении операции возврата. |
HTTP Status Code: 422
Запрос не выполнен. Тело ответа — объект JSON, описывающий ошибку.
Last updated