Запросы API v1.1.0

Кошелёк Pay API

Документация перемещена

Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:

https://developers.koshelek.app

В следующих версиях документа в запросы и/или ответы могут быть добавлены новые необязательные поля.

Для обеспечения обратной совместимости необходимо игнорировать их при формировании запросов и при приеме ответов от сервера до внесения соответствующих изменений в ПО, работающее на стороне ТСП.

Запрос списка возможных провайдеров платежей

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

Принципы получения списка доступных провайдеров платежей

Параметры запроса

Параметры заголовка запроса

ПараметрТипОбязательноЗначение

token

String

Да

Состоит из значения параметраcashFingerPrint и парольной части TOTP. Значение получается от модуля Кошелёк TOTP, развернутого на кассовом сервере ТСП (см. Модуль Кошелёк TOTP).

Пример заголовка запроса
token: SW50ZWwoUikgQ29yZShUTSkgaTUtNzIwMFUgQ1BVIEAgMi41MEdIejtDUFUWO1RpbWk7TU1HNVMwMDAwMDEwNzc5TFAwMzFaOzE2MTcyNzYxNzk2MjA7MTkyLjE2OC4xLjEwMztVU0IgUm9vdCBIdWIgKFVTQiAzLjApI1VTQiBDb21wb3NpdGUgRGV2aWNlI1hpYW9NaSBVU0IgMi4wIFdlYmNhbSNJbnRLbChSKSBXaXJLbGVzcyBCbHVLdG9vdGgoUikjRUxBTiBXQkYgRmluZ2VycHJpbnQgU2Vuc29yI1VTQiBJbnB1dCBEZXZpY2UjSElELWNvbXBsaWFudCBtb3VzZQ==967

Параметры тела запроса

Тело запроса передается в виде объекта JSON следующей структуры:

ПолеТипОбязательноЗначение

requestId

String

Да

Уникальный идентификатор запроса

(GUID, 36 символов).

Если по каким-либо причинам ответ на запрос не получен от Кошелька, то можно отправить этот запрос повторно, используя то же самое значение параметра requestId (действует правило идемпотентности).

cardSession

String

Да

Идентификатор сессии, извлеченный ТСП из штрихкода при сканировании карты или с информацией о QR-коде (не более 32 символов, латинские буквы и цифры, либо 6 символов для одномерных штрихкодов).

storeId

String

Да

Идентификтор ТСП, выданный Cardsmobile при его подключении (GUID, 36 символов).

terminalId

String

Да

Идентификатор кассы (256 символов).

checkoutInvoice

Да

Информация о пречеке.

user

Object User

Да

Информация о пользователе.

Пример тела запроса
{
    "requestId": "1624931549080",
    "cardsession": "123456",
    "storeId": "ac99f4c8-1a8e-4b60-8aeb-fe20220f1b99",
    "terminalId": "mip9e26ay3z2s0oh",
    "checkoutInvoice": {
        "orderId": "ac99e4c8-1a7e-4b60-8aeb-fe10110f1b99",
        "totalAmount": 20,
        "discountAmount": 5,
        "subTotalAmount": 20,
        "items": [
            {
                "name": "testName",
                "article": "1111111",
                "price": null,
                "quantity": 1,
                "totalAmount": 20,
                "discountAmount": 5,
                "subTotalAmount": 100,
                "tax": "none"
            }
        ],
    },
    "user": {
        "loyaltyId": "000022"
    },
}

Параметры ответа

HTTP Status Code: 200

Запрос выполнен успешно, ответ содержит сведения о списке провайдеров платежей (используется синхронный режим).

Тело ответа — объект JSON следующей структуры:

ПoлеТипОбязательноЗначение

koshelekPayIsDefault

Boolean

Да

Флаг автоматического выбора и запуска на кассе оплаты через Кошелёк Pay по умолчанию.

Если true, то в списке провайдеров платежей paymentTypeAvailabilityInfoList всегда будет хотя бы один доступный (available= true).

paymentTypeAvailabilityInfoList

Да

Массив, содержащий в себе список доступных провайдеров платежей.

Пример тела ответа
{
    "koshelekPayIsDefault": true,
    "paymentTypeAvailabilityInfoList": [
        {
            "paymentType": "SBP",
            "available": true,
            "message": ""
        },
        {
            "paymentType": "DOLYAME",
            "available": false,
            "message": "Недоступно по причине низкого кредитного рейтинга: score < 0.2"
        }
    ]  
}

HTTP Status Code: 201

Запрос выполнен успешно, ответ содержит сведения для отдельного запроса на получение списка доступных провайдеров платежей (используется асинхронный режим).

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

Location: /api/v1/merchant/availability-info/{availabilityInfoId}

Тело ответа — объект JSON следующей структуры:

ПолеТипОбязательноЗначение

availabilityInfoId

String

Да

Идентификатор, по которому можно запросить информацию о списке доступных провайдеров платежей.

timeout

Integer

Да

Время, через которое необходимо осуществить первую проверку статуса готовности в запросе /availability-info/{availabilityInfoId}

Пример тела ответа
 {
   "availabilityInfoId": "ecda679e-f5ab-4250-b622-2a429d714b21",
   "timeout": 350
 }

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 следующей структуры:

ПолеТипОбязательноЗначение

availabilityInfoId

String

Да

Идентификатор, полученный в запросе.

computationComplete

Boolean

Да

Готовность результата запроса:

true — готов;

false — не готов.

pollingTimeout

Long

Да

Инструкция от сервера: отправить повторный запрос через указанное время (в миллисекундах).

Передается, если computationComplete = false.

koshelekPayIsDefault

Boolean

Да

Флаг автоматического выбора и запуска на кассе оплаты через Кошелёк Pay по умолчанию.

Если true, то в списке провайдеров платежей paymentTypeAvailabilityInfoList всегда будет хотя бы один доступный (available= true).

paymentTypeAvailabilityInfoList

Да

Массив, содержащий в себе список доступных провайдеров платежей.

Пример тела ответа
{
    "availabilityInfoId": "ecda679e-f5ab-4250-b622-2a429d714b21",
    "computationComplete": true,
    "koshelekPayIsDefault": true,
    "paymentTypeAvailabilityInfoList": [
        {
            "paymentType": "SBP",
            "available": true,
            "message": ""
        },
        {
            "paymentType": "DOLYAME",
            "available": false,
            "message": "Недоступно по причине низкого кредитного рейтинга: score < 0.2"
        }
    ]  
}

HTTP Status Code: 422

Запрос не выполнен.

Тело ответа — объект JSON, описывающий ошибку.

Инициализация платежа

HTTP-метод: POST

URL: /api/v1/merchant/checkout

Описание

ТСП передает Кошельку информацию о счёте к оплате и значение cardSession пользователя, который должен оплатить этот счёт.

Параметры запроса

Параметры заголовка запроса

ПараметрТипОбязательноЗначение

token

String

Да

Состоит из значения параметраcashFingerPrint и парольной части TOTP. Значение получается от модуля Кошелёк TOTP, развернутого на кассовом сервере ТСП (см. Модуль Кошелёк TOTP).

Пример заголовка запроса
token: SW50ZWwoUikgQ29yZShUTSkgaTUtNzIwMFUgQ1BVIEAgMi41MEdIejtDUFUWO1RpbWk7TU1HNVMwMDAwMDEwNzc5TFAwMzFaOzE2MTcyNzYxNzk2MjA7MTkyLjE2OC4xLjEwMztVU0IgUm9vdCBIdWIgKFVTQiAzLjApI1VTQiBDb21wb3NpdGUgRGV2aWNlI1hpYW9NaSBVU0IgMi4wIFdlYmNhbSNJbnRLbChSKSBXaXJLbGVzcyBCbHVLdG9vdGgoUikjRUxBTiBXQkYgRmluZ2VycHJpbnQgU2Vuc29yI1VTQiBJbnB1dCBEZXZpY2UjSElELWNvbXBsaWFudCBtb3VzZQ==967

Параметры тела запроса

Тело запроса передается в виде объекта JSON следующей структуры:

ПолеТипОбязательноЗначение

requestId

String

Да

Уникальный идентификатор запроса

(GUID, не более 36 символов).

Если по каким-либо причинам ответ на запрос не получен от Кошелька, то можно отправить этот запрос повторно, используя то же самое значение параметра requestId (действует правило идемпотентности).

cardSession

String

Да

Идентификатор сессии, извлеченный ТСП из штрихкода при сканировании карты или с информацией о QR-коде (не более 32 символов, латинские буквы и цифры, либо 6 символов для одномерных штрихкодов).

storeId

String

Да

Идентификтор ТСП, выданный Cardsmobile при его подключении (GUID, 36 символов).

terminalId

String

Да

Идентификатор кассы (256 символов).

checkoutInvoice

Да

Информация о пречеке.

user

Object User

Да

Информация о пользователе.

paymentMethods

Array of PaymentMethod

Да

Массив объектов, содержащий в себе информацию о способах оплаты, поддерживаемых ТСП.

Пример тела запроса
{
    "requestId": "4ee64eb1-0012-4cd0-aefe-966d48ea7b71",
    "cardSession": "A1G97N",
    "storeId": "ac99f4c8-1a8e-4b60-8aeb-fe20220f1b99",
    "terminalId": "mip9e26ay3z2s0oh",
    "checkoutInvoice": {
                "orderId": "12345",
                "totalAmount": "14245",
                "discountAmount": "100",
                "subTotalAmount": "14345",
                "items": [
                        {  
                            "name": "Товар 1",
                            "article": "1111111",
                            "price": 10000,
                            "currency": "RUB",
                            "quantity": 1125.0,
                            "measure": "GRAM",
                            "totalAmount": 1900,
                            "discountAmount": 100,
                            "subTotalAmount": 2000,
                            "tax": "vat10"
                        },
                        {  
                            "name": "Товар 2",
                            "article": "2222222",
                            "price": 12345,
                            "quantity": 1,
                            "totalAmount": 12345,
                            "discountAmount": 15,
                            "subTotalAmount": 3000,
                            "tax": "vat20"
                        }
                        ]
                },
    "user": {
                "loyaltyId": "1234567891011"
            },
    "paymentMethods": [
        {
         "type": "SBP"
        }
    ]
}

Параметры ответа

HTTP Status Code: 200

Запрос выполнен успешно.

Тело ответа — объект JSON следующей структуры:

ПолеТипОбязательноЗначение

requestId

String

Да

Уникальный идентификатор запроса.

transactionId

String

Да

Идентификатор транзакции.

status

Enum

Да

Статус транзакции:

new

canceled

pending

rejected

accepted

refunding

refunded

partial_refunded

slip

Object Slip

Зависит от значения поля status

Объект Slip, содержащий данные о проведенной банковской операции.

Будет возвращен, если операция оплаты была проведена через банк (статусы accepted, rejected), или если был проведен возврат оплаты (статусы refunded, partial_refunded).

Пример тела ответа
{
  "requestId": "314b0613-ae21-438c-b538-6b965e85d644",
  "transactionId": "f9a59682-3d05-4af6-8308-2c1f1665d733",
  "status": "new",
  "slip": {
        "id": "d95d9f7d-cea2-47c0-b9b5-4e7ad3ee4c63",
        "paymentTransactionId": "48f62a99-50a2-4e0c-a883-4be0a7c62dd7",
        "paymentType": "DOLYAME",
        "terminalId": "20210510T120700",
        "storeId": "KOSHELEK-42",
        "orderId": "9d913e76-24d9-468d-6c6d-2a41bcfb8d81",
        "operationDateTime": "2022-01-19T11:56:34.323Z",
        "totalAmount": 15000,
        "currency": "RUB"
        }
}

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. Реализация подключения к методу получения статуса от сервера Кошелька.

Рекомендации по вызову метода

Статус транзакции необходимо запрашивать:

  1. В первый раз: не раньше чем через 250 мс и не позже чем через 500 мс.

  2. Дальнейшие вызовы должны быть не чаще чем раз в 250 мс.

  3. Касса должна ожидать статус не дольше, чем 30 секунд, и вызывать отмену оплаты, если время ожидания превышено.

Конкретная реализация остается на усмотрение ТСП, но важно убедиться, что не остается никакого потока, который продолжает опрашивать серверы Кошелька.

Параметры запроса

Тело запроса передается в виде объекта JSON следующей структуры:

ПолеТипОбязательноЗначение

requestId

String

Да

Уникальный идентификатор запроса

(GUID, не более 36 символов).

Если по каким-либо причинам ответ на запрос не получен от Кошелька, то можно отправить этот запрос повторно, используя то же самое значение параметра requestId (действует правило идемпотентности).

transactionId

String

Нет

Идентификатор транзакции оплаты

(GUID, 36 символов).

Необязателен, если передается refTransactionId.

refTransactionId

String

Нет

Идентификатор транзакции отмены

(GUID, 36 символов).

Необязателен, если передается transactionId.

Пример тела запроса
{
    "requestId": "ab182f20-9c5a-11ea-ab12-0800200c9a66",
    "transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66"
}

Параметры ответа

HTTP Status Code: 200

Запрос выполнен успешно.

Тело ответа — объект JSON следующей структуры:

ПолеТипОбязательноЗначение

requestId

String

Да

Уникальный идентификатор запроса.

transactionId

String

Да

Идентификатор транзакции оплаты.

refTransactionId

String

Нет

Идентификатор транзакции отмены.

status

Enum

Да

Статус транзакции:

new

canceled

pending

rejected

accepted

refunding

refunded

partial_refunded

— или пустое значение, если указанный в запросе transactionId не найден.

paymentGroup

Enum

Да

Категория оплат:

INSTALLMENT — в рассрочку / частями.

SBP — через Систему быстрых платежей.

paymentProvider

Enum

Да

Тип провайдера:

DOLYAME — "Тинькофф Долями". SBP — СБП.

slip

Object Slip

Зависит от значения поля status

Объект Slip, содержащий данные о проведенной банковской операции.

Будет возвращен, если операция оплаты была проведена через банк (статусы accepted и rejected), или если был проведен возврат оплаты (статусы refunded и partial_refunded).

refStatus

Enum

Нет

Статус транзакции отмены:

new

rejected — отмена отклонена, оплата не возвращена покупателю.

accepted — отмена одобрена.

errorCode

Enum

Нет

Код ошибки, возникшей при выполнении операции оплаты или возврата. Параметр передается только для status или refStatus = "rejected". Описание возможных значений см. ниже.

Возможные значения параметра errorCode

1. Для сценария оплаты:

ЗначениеОписание

NOT_ENOUGH_LIMIT_TO_PAY

Превышен лимит для совершения операции.

TOTAL_AMOUNT_IS_TOO_SMALL

Сумма покупки ниже установленного лимита (составляет 4 рубля).

EXTERNAL_PROVIDER_ERROR

Общий код ошибки провайдера платежей.

SUBSCRIPTION_IS_NOT_FOUND

Привязанный счет пользователя не найден (платеж через СБП с привязанного счета пользователя).

PAYMENT_DECLINED_BY_EXTERNAL_PROVIDER

Платеж отклонен банком (платеж через СБП с привязанного счета пользователя).

2. Для сценария возврата:

ЗначениеОписание

PAYMENT_TRANSACTION_IS_NOT_PAID

Возврат отклонен, т.к. транзакция оплаты с данным transactionId не была завершена, списание средств не выполнялось.

TERMINAL_STATE_OF_PAYMENT_TRANSACTION

Возврат отклонен по одной из причин:

  • транзакция была отменена ранее, до списания средств;

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

  • уже был выполнен полный возврат средств.

PAYMENT_TRANSACTION_IS_BEING_REFUNDED_ALREADY

Возврат отклонен, т.к. есть незавершенная транзакция отмены. Дождитесь завершения процесса возврата по транзакции отмены с refTransactionId незавершенной предыдущей транзакции отмены.

REQUESTED_REFUND_AMOUNT_IS_GREATER_THAN_AVAILABLE

Возврат отклонен, т.к. запрошенная сумма к возврату превышает сумму оплаты по транзакции оплаты с данным transactionId.

EXTERNAL_PROVIDER_ERROR

Общий код ошибки провайдера платежей.

UNEXPECTED_REFUND_AMOUNT_LEFT_FROM_EXTERNAL_PROVIDER

Возврат отклонен, т.к. транзакция оплаты с данным transactionId не была завершена, списание средств не выполнялось.

PAYMENT_ORDER_IS_NOT_FOUND

Только для транзакций СБП. Не найдено платежное поручение в банке ТСП при выполнении операции возврата.

Пример тела ответа
{
    "requestId": "ab182f20-9c5a-11ea-ab12-0800200c9a66",
    "transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66",
    "status": "pending"
    "paymentGroup": "INSTALLMENT",
    "paymentProvider": "DOLYAME"
 }

HTTP Status Code: 422

Запрос не выполнен. Тело ответа — объект JSON, описывающий ошибку.

Отправка чека

HTTP-метод: POST

URL: /api/v1/merchant/transaction/receipt

Описание

ТСП передает Кошельку информацию о фискальном чеке для его отображения пользователю в Кошельке.

Параметры запроса

Тело запроса передается в виде объекта JSON следующей структуры:

ПолеТипОбязательноЗначение

requestId

String

Да

Уникальный идентификатор запроса

(GUID, не более 36 символов).

Если по каким-либо причинам ответ на запрос не получен от Кошелька, то можно отправить этот запрос повторно, используя то же самое значение параметра requestId (действует правило идемпотентности).

transactionId

String

Да

Идентификатор транзакции оплаты

(GUID, 36 символов).

storeId

String

Да

Идентификтор ТСП, выданный Cardsmobile при его подключении (GUID, 36 символов).

terminalId

String

Да

Идентификатор кассы (256 символов).

invoice

Object Invoice

Да

Информация о счете в формате "ключ-значение". См. объект Invoice.

meta

Object

Нет

Объект, содержащий дополнительные поля, например: скидки, бонусы и т.д. (набор пар "ключ-значение").

Пример тела запроса
{
    "requestId": "045b22e0-9c5b-11ea-ab12-0800200c9a66",
    "transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66",
    "invoice": {
                "orderId": "12345",
                "receiptId": "6789",
                "merchantName": "ООО Торговая сеть №1",
                "merchantAddress": "198000 г. Санкт-Петербург, ул.Ленина д.1 пом.123",
                "inn": "001234567891",
                "dateTime": "2020-05-20T20:50:00+03:00",
                "shift": "5",
                "cashier": "Иванов Иван Иванович",
                "taxation": "osn",
                "kktRegNumber": "0004147503041443",
                "fnNumber": "9280440300387752",
                "fdNumber": "0000010272",
                "fpd": "2374313442",
                "website": "nalog.ru",
                "receiptType": "debit",
                "qr": "t=20200520T2050&s=859.00&fn=9280440300387752&i=10272&fp=2374313442&n=1",
                "totalAmount": "14245",
                "currency": "RUB",
                "discountAmount": "100",
                "subTotalAmount": "14345",
                "items": [
                        {  
                            "name": "Товар 1",
                            "price": 1000,
                            "currency": "RUB",
                            "quantity": 2.0,
                            "measure": "GRAM",
                            "totalAmount": 1900,
                            "discountAmount": 100,
                            "subTotalAmount": 2000,
                            "tax": "vat10",
                             "article": "1111111" 
                        },
                        {  
                            "name": "товар 2",
                            "price": 12345,
                            "quantity": 1.0,
                            "totalAmount": 12345,
                            "tax": "vat20"
                        }
                        ]
                }
}

Параметры ответа

HTTP Status Code: 200

Запрос выполнен успешно. Тело ответа — пустое.

HTTP Status Code: 422

Запрос не выполнен. Тело ответа — объект JSON, описывающий ошибку.

Отмена оплаты

HTTP-метод: POST

URL: /api/v1/merchant/transaction/cancel

Описание

ТСП передает Кошельку запрос на отмену транзакции оплаты.

В запросе не указывается сумма отмены, т.к. операция отмены проводится на полную сумму, указанную в транзакции оплаты.

Параметры запроса

Тело запроса передается в виде объекта JSON следующей структуры:

ПолеТипОбязательноЗначение

requestId

String

Да

Уникальный идентификатор запроса

(GUID, не более 36 символов).

Если по каким-либо причинам ответ на запрос не получен от Кошелька, то можно отправить этот запрос повторно, используя то же самое значение параметра requestId (действует правило идемпотентности).

storeId

String

Да

Идентификтор ТСП, выданный Cardsmobile при его подключении (GUID, 36 символов).

terminalId

String

Да

Идентификатор кассы (256 символов).

transactionId

String

Да

Идентификатор транзакции оплаты

(GUID, 36 символов).

Пример тела запроса
{
    "requestId": "f1847360-b3c5-11ea-8b6e-0800200c9a66",
    "terminalId": "20210510T120700",
    "storeId": "KOSHELEK-42",   
    "transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66"
}

Параметры ответа

HTTP Status Code: 200

Запрос выполнен успешно.

Тело ответа — объект JSON следующей структуры:

ПолеТипОбязательноЗначение

requestId

String

Да

Уникальный идентификатор запроса.

refTransactionId

String

Да

Идентификатор транзакции отмены.

refStatus

Enum

Да

Статус транзакции отмены:

new

rejected — отмена отклонена (перечень причин указан в таблице в описании сценария отмены).

accepted — отмена одобрена.

transactionId

String

Да

Идентификатор транзакции оплаты.

status

Enum

Да

Статус транзакции оплаты, в который она перешла после вызова отмены (или в котором она осталась, если отмена была отклонена):

new

canceled

pending

rejected

accepted

refunding

refunded

partial_refunded

none

slip

Object Slip

Зависит от значения поля status

Объект Slip, содержащий данные о проведенной банковской операции. Будет возвращен, если операция оплаты была проведена через банк (статусы accepted и rejected), или если был проведен возврат оплаты (статусы refunded и partial_refunded).

Пример тела ответа
{
  "requestId": "requestId",
  "refTransactionId": "59ab316c-4de4-4e0d-8d07-448b2c7f25a7",
  "refStatus": "accepted",
  "transactionId": "6b66835f-a82a-4385-bd98-e9a5047e88fa",
  "status": "canceled",
  "slip": {
        "id": "d95d9f7d-cea2-47c0-b9b5-4e7ad3ee4c63",
        "paymentTransactionId": "48f62a99-50a2-4e0c-a883-4be0a7c62dd7",
        "paymentType": "DOLYAME",
        "terminalId": "20210510T120700",
        "storeId": "KOSHELEK-42",
        "orderId": "9d913e76-24d9-468d-6c6d-2a41bcfb8d81",
        "merchantId": "MA0000103685",
        "operationDateTime": "2022-01-19T11:56:34.323Z",
        "operationId": "e1df75fe-eb80-428e-96f6-032acefcb995",
        "totalAmount": 15000
        }
}

HTTP Status Code: 422

Запрос не выполнен. Тело ответа — объект JSON, описывающий ошибку.

Возврат оплаты

HTTP-метод: POST

URL: /api/v1/merchant/transaction/refund

Описание

ТСП передает Кошельку запрос на возврат покупателю средств, полученных в результате транзакции оплаты.

Параметры запроса

Параметры заголовка запроса

ПараметрТипОбязательноЗначение

token

String

Да

Состоит из значения параметраcashFingerPrint и парольной части TOTP. Значение получается от модуля Кошелёк TOTP, развернутого на кассовом сервере ТСП (см. Модуль Кошелёк TOTP).

Пример заголовка запроса
token: SW50ZWwoUikgQ29yZShUTSkgaTUtNzIwMFUgQ1BVIEAgMi41MEdIejtDUFUWO1RpbWk7TU1HNVMwMDAwMDEwNzc5TFAwMzFaOzE2MTcyNzYxNzk2MjA7MTkyLjE2OC4xLjEwMztVU0IgUm9vdCBIdWIgKFVTQiAzLjApI1VTQiBDb21wb3NpdGUgRGV2aWNlI1hpYW9NaSBVU0IgMi4wIFdlYmNhbSNJbnRLbChSKSBXaXJLbGVzcyBCbHVLdG9vdGgoUikjRUxBTiBXQkYgRmluZ2VycHJpbnQgU2Vuc29yI1VTQiBJbnB1dCBEZXZpY2UjSElELWNvbXBsaWFudCBtb3VzZQ==967

Параметры тела запроса

Тело запроса передается в виде объекта JSON следующей структуры:

ПолеТипОбязательноЗначение

requestId

String

Да

Уникальный идентификатор запроса

(GUID, не более 36 символов).

Если по каким-либо причинам ответ на запрос не получен от Кошелька, то можно отправить этот запрос повторно, используя то же самое значение параметра requestId (действует правило идемпотентности).

storeId

String

Да

Идентификатор ТСП, выданный Cardsmobile при его подключении (GUID, 36 символов).

terminalId

String

Да

Идентификатор кассы (256 символов).

transactionId

String

Да

Идентификатор транзакции оплаты

(GUID, 36 символов).

refundAmount

Number

Да

Сумма возврата в копейках. Не должна превышать сумму оплаты. Только положительное значение.

currency

String

Нет

Трехбуквенный код валюты в формате ISO-4217:

  • RUB — значение по умолчанию, если параметр отсутствует или значение пустое.

  • Если значение отлично от RUB, кассовое ПО получит отказ с сообщением о доступности только RUB.

items

Array of Item

Да

Массив товаров, включенных в возвращаемую покупку (каждый товар — объект Item).

Пример тела запроса
{
  "requestId": "f1847360-b3c5-11ea-8b6e-0800200c9a66",
  "transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66",
  "storeId": "ac99f4c8-1a8e-4b60-8aeb-fe20220f1b99",
  "terminalId": "mip9e26ay3z2s0oh",
  "refundAmount": 14245,
  "currency": "RUB",
  "items": [
    {
      "name": "Товар 1",
      "price": 10000,
      "currency": "RUB",
      "quantity": 1125.0,
      "measure": "GRAM",
      "totalAmount": 1900,
      "discountAmount": 100,
      "subTotalAmount": 2000,
      "tax": "vat10"
    },
    {
      "name": "Товар 2",
      "price": 12345,
      "quantity": 1.0,
      "totalAmount": 12345,
      "tax": "vat20"
    }
  ]
}

Параметры ответа

HTTP Status Code: 200

Запрос выполнен успешно.

Тело ответа — объект JSON следующей структуры:

ПолеТипОбязательноЗначение

requestId

String

Да

Уникальный идентификатор запроса.

refTransactionId

String

Да

Идентификатор транзакции возврата.

refStatus

Enum

Да

Статус транзакции возврата:

new

rejected — возврат отклонен.

accepted — возврат одобрен.

transactionId

String

Да

Идентификатор транзакции оплаты.

status

Enum

Да

Статус транзакции оплаты, в который она перешла после вызова отмены (или в котором она осталась, если отмена была отклонена):

new

canceled

pending

rejected

accepted

refunding

refunded

partial_refunded

none

slip

Object Slip

Нет

Объект Slip, содержащий данные о проведенной банковской операции. Будет возвращен, если операция оплаты уже была была проведена через банк (статусы accepted и rejected).

errorCode

Enum

Нет

Код ошибки, возникшей при выполнении операции возврата. Передается только для refStatus = "rejected". Возможные значения см. ниже.

Возможные значения параметра errorCode

ЗначениеОписание

PAYMENT_TRANSACTION_IS_NOT_PAID

Возврат отклонен, т.к. транзакция оплаты с данным transactionId не была завершена, списание средств не выполнялось.

TERMINAL_STATE_OF_PAYMENT_TRANSACTION

Возврат отклонен, т.к. транзакция:

  • была отменена ранее до списания средств;

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

  • уже был выполнен полный возврат оплаченных средств.

PAYMENT_TRANSACTION_IS_BEING_REFUNDED_ALREADY

Возврат отклонен, т.к. уже есть незавершенная транзакция отмены. Дождитесь завершения процесса возврата по транзакции отмены с refTransactionId незавершенной предыдущей транзакции отмены.

REQUESTED_REFUND_AMOUNT_IS_GREATER_THAN_AVAILABLE

Возврат отклонен, т.к. запрошенная сумма к возврату превышает сумму оплаты по транзакции оплаты с данным transactionId

EXTERNAL_PROVIDER_ERROR

Общий код ошибки провайдера платежей

UNEXPECTED_REFUND_AMOUNT_LEFT_FROM_EXTERNAL_PROVIDER

Возврат отклонен, т.к. транзакция оплаты с данным transactionId не была завершена, списание средств не выполнялось.

PAYMENT_ORDER_IS_NOT_FOUND

Только для транзакций СБП. Не найдено платежное поручение в банке ТСП при выполнении операции возврата.

Пример тела ответа
{
  "requestId": "314b0613-ae21-438c-b538-6b965e85d644",
  "refTransactionId": "665857e3-25ca-4bd2-b2ec-87c994eff47a",
  "refStatus": "accepted",
  "transactionId": "f9a59682-3d05-4af6-8308-2c1f1665d733",
  "status": "refunded",
  "slip": {
        "id": "d95d9f7d-cea2-47c0-b9b5-4e7ad3ee4c63",
        "paymentTransactionId": "48f62a99-50a2-4e0c-a883-4be0a7c62dd7",
        "paymentType": "DOLYAME",
        "terminalId": "20210510T120700",
        "storeId": "KOSHELEK-42",
        "orderId": "9d913e76-24d9-468d-6c6d-2a41bcfb8d81",
        "merchantId": "MA0000103685",
        "operationDateTime": "2022-01-19T11:56:34.323Z",
        "operationId": "e1df75fe-eb80-428e-96f6-032acefcb995",
        "totalAmount": 15000,
        "currency": "RUB"
        }
}

HTTP Status Code: 422

Запрос не выполнен. Тело ответа — объект JSON, описывающий ошибку.

Last updated