Russian
Запросы API
Кошелёк Pay API
post
/api/v1/merchant/availability-info/task
Запрос списка возможных провайдеров платежей
В заголовке запроса передается значение token, полученное от модуля Кошелёк TOTP, развернутого на кассовом сервере ТСП (см. Модуль Кошелёк TOTP).
Пример значения token:
Пример token
Пример запроса:
1
{
2
"requestId": "1624931549080",
3
"cardsession": "123456",
4
"storeId": "ac99f4c8-1a8e-4b60-8aeb-fe20220f1b99",
5
"terminalId": "mip9e26ay3z2s0oh",
6
"checkoutInvoice": {
7
"orderId": "ac99e4c8-1a7e-4b60-8aeb-fe10110f1b99",
8
"totalAmount": 20,
9
"discountAmount": 5,
10
"subTotalAmount": 20,
11
"items": [
12
{
13
"name": "testName",
14
"price": null,
15
"quantity": 1,
16
"totalAmount": 20,
17
"discountAmount": 5,
18
"subTotalAmount": 100,
19
"tax": "none"
20
}
21
],
22
},
23
"user": {
24
"loyaltyId": "000022"
25
},
26
}
Copied!
Параметры ответа:
HTTP Status Code = 200
HTTP Status Code = 201
Используется синхронный режим, список доступных провайдеров платежей сформирован:
Параметр
Тип
Обязателен
Значение
koshelekPayIsDefault
Boolean
Да
Флаг автоматического выбора и запуска на кассе оплаты через Кошелёк Pay по умолчанию.
Если true, то в списке провайдеров платежей paymentTypeAvailabilityInfoList всегда будет хотя бы один доступный (available= true).
paymentTypeAvailabilityInfoList
Array of paymentTypeAvailabilityInfo
Да
Массив, содержащий в себе список доступных провайдеров платежей (объект paymentTypeAvailabilityInfo)
Используется асинхронный режим, список доступных провайдеров платежей не сформирован, его следует запросить отдельно:
Параметр
Тип
Обязателен
Значение
availabilityInfoId
String
Да
Идентификатор, по которому можно запросить информацию о списке доступных провайдеров платежей.
timeout
Integer
Да
Время, через которое необходимо осуществить первую проверку статуса готовности в запросе /availability-info/{availabilityInfoId}
get
/api/v1/merchant/availability-info/{availabilityInfoId}
Получение списка доступных провайдеров платежей
Параметры ответа:
Параметр
Тип
Обязателен
Значение
availabilityInfoId
String
Да
Идентификатор, полученный в запросе.
computationComplete
Boolean
Да
Готовность результата запроса:
true — готов;
false — не готов.
pollingTimeout
Long
Да
Инструкция от сервера: отправить повторный запрос через указанное время (в миллисекундах).
Передается, если computationComplete = false.
koshelekPayIsDefault
Boolean
Да
Флаг автоматического выбора и запуска на кассе оплаты через Кошелёк Pay по умолчанию.
Если true, то в списке провайдеров платежей paymentTypeAvailabilityInfoList всегда будет хотя бы один доступный (available= true).
paymentTypeAvailabilityInfoList
Array of paymentTypeAvailabilityInfo
Да
Массив, содержащий в себе список доступных провайдеров платежей (объект paymentTypeAvailabilityInfo)
Принципы получения списка доступных провайдеров платежей:
post
/api/v1/merchant/checkout
Инициализация платежа
В заголовке запроса передается значение token, полученное от модуля Кошелёк TOTP, развернутого на кассовом сервере ТСП (см. Модуль Кошелёк TOTP).
Пример запроса:
1
{
2
"requestId": "4ee64eb1-0012-4cd0-aefe-966d48ea7b71",
3
"cardSession": "A1G97N",
4
"storeId": "ac99f4c8-1a8e-4b60-8aeb-fe20220f1b99",
5
"terminalId": "mip9e26ay3z2s0oh",
6
"checkoutInvoice": {
7
"orderId": "12345",
8
"totalAmount": "14245",
9
"discountAmount": "100",
10
"subTotalAmount": "14345",
11
"items": [
12
{
13
"name": "Товар 1",
14
"price": 10000,
15
"quantity": 1,
16
"totalAmount": 1900,
17
"discountAmount": 100,
18
"subTotalAmount": 2000,
19
"tax": "vat10"
20
},
21
{
22
"name": "товар 2",
23
"price": 12345,
24
"quantity": 1,
25
"totalAmount": 12345,
26
"tax": "vat20"
27
}
28
]
29
},
30
"user": {
31
"loyaltyId": "1234567891011"
32
},
33
"paymentMethods": [
34
{
35
"type": "SBP"
36
}
37
]
38
}
Copied!
Параметры ответа:
Параметр
Тип
Обязателен
Значение
requestId
String
Да
Уникальный идентификатор запроса.
transactionId
String
Да
Идентификатор транзакции.
status
Enum
Да
Статус транзакции:
new
canceled
pending
rejected
accepted
refunding
refunded
partial_refunded
slip
Object Slip
Нет
Объект Slip, содержащий данные о проведенной банковской операции. Будет возвращен, если операция оплаты была проведена через банк (статусы accepted, rejected), или если был проведен возврат оплаты (статусы refunded, partial_refunded).
post
/api/v1/merchant/transaction/status
Получение статуса транзакции
Рекомендации по вызову метода
Статус транзакции необходимо запрашивать:
  1. 1.
    В первый раз: не раньше чем через 250 мс и не позже чем через 500 мс.
  2. 2.
    Дальнейшие вызовы должны быть не чаще чем раз в 250 мс.
  3. 3.
    Касса должна ожидать статус не дольше, чем 30 секунд, и вызывать отмену оплаты, если время ожидания превышено.
Конкретная реализация остается на усмотрение ТСП, но важно убедиться, что не остается никакого потока, который продолжает опрашивать серверы Кошелька.
Пример запроса:
1
{
2
"requestId": "ab182f20-9c5a-11ea-ab12-0800200c9a66",
3
"transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66"
4
}
Copied!
Параметры ответа:
Параметр
Тип
Обязателен
Значение
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 — "Тинькофф Долями".
slip
Object Slip
Нет
Объект Slip, содержащий данные о проведенной банковской операции. Будет возвращен, если операция оплаты была проведена через банк (статусы accepted и rejected), или если был проведен возврат оплаты (статусы refunded и partial_refunded).
refStatus
Enum
Да
Статус транзакции отмены:
new
rejected — отмена отклонена, оплата не возвращена покупателю.
accepted — отмена одобрена.
post
/api/v1/merchant/transaction/receipt
Отправка чека
Пример запроса:
1
{
2
"requestId": "045b22e0-9c5b-11ea-ab12-0800200c9a66",
3
"transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66",
4
"storeId": "ac99f4c8-1a8e-4b60-8aeb-fe20220f1b99",
5
"terminalId": "mip9e26ay3z2s0oh",
6
"invoice": {
7
"orderId": "12345",
8
"receiptId": "6789",
9
"merchantName": "ООО Торговая сеть №1",
10
"merchantAddress": "198000 г. Санкт-Петербург, ул.Ленина д.1 пом.123",
11
"inn": "001234567891",
12
"dateTime": "2020-05-20T20:50:00+03:00",
13
"shift": "5",
14
"cashier": "Иванов Иван Иванович",
15
"taxation": "osn",
16
"kktRegNumber": "0004147503041443",
17
"fnNumber": "9280440300387752",
18
"fdNumber": "0000010272",
19
"fpd": "2374313442",
20
"website": "nalog.ru",
21
"receiptType": "debit",
22
"QR": "t=20200520T2050&s=859.00&fn=9280440300387752&i=10272&fp=2374313442&n=1",
23
"totalAmount": "14245",
24
"discountAmount": "100",
25
"subTotalAmount": "14345",
26
"items": [
27
{
28
"name": "Товар 1",
29
"price": 10000,
30
"quantity": 1,
31
"totalAmount": 1900,
32
"discount": 100,
33
"subTotalAmount": 2000,
34
"tax": "vat10"
35
},
36
{
37
"name": "товар 2",
38
"price": 12345,
39
"quantity": 1,
40
"totalAmount": 12345,
41
"tax": "vat20"
42
}
43
]
44
}
45
}
Copied!
post
/api/v1/merchant/transaction/cancel
Отмена оплаты
В запросе не указывается сумма отмены, т.к. операция отмены проводится на полную сумму, указанную в транзакции оплаты.
Пример запроса:
1
{
2
"requestId": "f1847360-b3c5-11ea-8b6e-0800200c9a66",
3
"storeId": "ac99f4c8-1a8e-4b60-8aeb-fe20220f1b99",
4
"terminalId": "mip9e26ay3z2s0oh",
5
"transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66",
6
}
Copied!
Параметры ответа:
Параметр
Тип
Обязателен
Значение
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), или если был проведен возврат оплаты (статусы refunded и partial_refunded).
post
/api/v1/merchant/transaction/refund
Возврат оплаты
Пример запроса:
1
{
2
"requestId": "f1847360-b3c5-11ea-8b6e-0800200c9a66",
3
"transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66",
4
"storeId": "ac99f4c8-1a8e-4b60-8aeb-fe20220f1b99",
5
"terminalId": "mip9e26ay3z2s0oh",
6
"refundAmount": 14245,
7
"items": [
8
{
9
"name": "Товар 1",
10
"price": 10000,
11
"quantity": 1,
12
"totalAmount": 1900,
13
"discount": 100,
14
"subTotalAmount": 2000,
15
"tax": "vat10"
16
},
17
{
18
"name": "Товар 2",
19
"price": 12345,
20
"quantity": 1,
21
"totalAmount": 12345,
22
"tax": "vat20"
23
}
24
]
25
}
Copied!
Параметры ответа:
Параметр
Тип
Обязателен
Значение
requestId
String
Да
Уникальный идентификатор запроса.
refTransactionId
String
Да
Идентификатор транзакции возврата.
refStatus
String
Да
Статус транзакции возврата:
new
rejected — возврат отклонен.
accepted — возврат одобрен.
transactionId
String
Да
Идентификатор транзакции оплаты.
status
Enum
Да
Статус транзакции оплаты, в который она перешла после вызова отмены (или в котором она осталась, если отмена была отклонена):
new
canceled
pending
rejected
accepted
refunding
refunded
partial_refunded
none
slip
Object Slip
Нет
Объект Slip, содержащий данные о проведенной банковской операции. Будет возвращен, если операция оплаты уже была была проведена через банк (статусы accepted и rejected).
Last modified 3h ago