Подготовка к интеграции# Регистрация и создание точки продаж через Tiyn Business# Для подготовки к интеграции необходимо:
Зарегистрировать личный кабинет Tiyn Business на
странице https://business.tiyn.io/cabinet/sign-up ; В личном кабинете создать точку продаж в разделе Точки продаж ; Нажать на карточку созданной точки продаж, перейти в Технические настройки и сгенерировать новый секретный ключ (secretPhrase)
для формирования подписи; Если требуется передача уведомлений об изменении статусов счета в одну из ваших систем (Callback), заполнить поле
Callback URL адресом для получения уведомлений; Активировать созданную точку продаж, связавшись с персональным менеджером. HTTP-заголовки# Взаимодействие с сервисом происходит посредством передачи HTTP-запросов.
Запросы могут включать следующие заголовки:
Content-Type: application/json; charset=utf-8x-api-key: <API Key>x-sign: <электронно-цифровая подпись> (кроме получения данных счета и данных точки продаж) Алгоритм формирования ЭЦП# ЭЦП формируется следующим образом:
От сформированного тела запроса (body) вычисляется хеш по алгоритму HMAC-SHA512. В качестве ключа используется
secretPhrase), кодировка UTF-8 Полученное значение переводится в base64 Примеры реализации алгоритма формирования x-sign# Пример на языке C#. Перед запуском задайте переменную окружения MERCHANT_API_URL со значением https://business.tiyn.io/merchant-api/api/v2.
Пример на языке PHP — по запросу в поддержке
Схема проведения запроса# Точка продаж отправляет в Tiyn Business запрос на создание счета; Tiyn Business обрабатывает запрос и, если счет создан корректно, возвращает данные, содержащие ссылку для
перехода на оплату;Плательщик переходит по ссылке выбирает способ оплаты и вводит платежные данные; Tiyn Business отправляет запрос на списание денежных средств эквайеру;Tiyn Business получает ответ об успешной/неуспешной оплате счета от эквайера;
происходит переадресация плательщика на страницу точки продаж
В случае успешной оплаты счета плательщик перенаправляется на страницу, указанную при создании счета в параметре
successUrl; В случае неуспешной оплаты происходит перенаправление на страницу, указанную при создании счета в параметре
failUrl; Tiyn Business отправляет точке продаж уведомление об успешной/неуспешной оплате счета;
Точка продаж возвращает ответ-подтверждение о проведенной операции. Получение доступных методов оплаты# Метод позволяет получить актуальный список методов оплаты, доступных для магазина. Полученные значения используются
при создании счета в параметре preferredPaymentMethods. Список зависит от настроек магазина, поэтому для его
получения и создания счета необходимо использовать один и тот же x-api-key.
Порядок использования# Получить список доступных методов оплаты с помощью GET /merchant-api/api/v2/payment-methods; Выбрать из ответа один или несколько методов, которые должны быть доступны плательщику; Передать выбранные значения без изменений в параметре preferredPaymentMethods при создании счета. Если параметр preferredPaymentMethods не передан, плательщику будут доступны все включенные для магазина методы
оплаты.
Пример запроса на получение методов оплаты# Для запроса требуется только ключ доступа магазина. Заголовок x-sign передавать не требуется.
cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/payment-methods \
-X GET \
-H 'x-api-key: <Ключ доступа>'
Пример успешного ответа на запрос на получение методов оплаты# JSON Копировать
{
"success" : true ,
"data" : {
"paymentMethods" : [
"BankCard" ,
"google_pay" ,
"sbp"
]
}
}
Значения BankCard, google_pay и sbp приведены в качестве примера. Фактический состав массива определяется настройками
магазина. Если для магазина нет доступных методов оплаты, API вернет пустой массив.
Описание параметров успешного ответа на запрос на получение методов оплаты Получение доступных методов оплаты — таблица 1 success Да Всегда true Признак успешности выполнения команды data Да Объект Доступные методы оплаты магазина
Описание параметров объекта data Получение доступных методов оплаты — таблица 2 paymentMethods Да Массив строк Методы оплаты, доступные для передачи в preferredPaymentMethods
Пример ответа при ошибке авторизации# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "-1" ,
"message" : "Unauthorized" ,
"correlationId" : "01ee1da0-a25b-476d-a290-5eda640e14b2"
}
}
Описание параметров ответа при ошибке авторизации Получение доступных методов оплаты — таблица 3 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Получение доступных методов оплаты — таблица 4 code Да Непустая строка Код ошибки message Да Непустая строка Описание ошибки correlationId Да Непустая строка Идентификатор корреляции запроса
Создание счета# Метод позволяет создать счет на оплату и отправить его плательщику.
Чтобы ограничить выбор плательщика, передайте в preferredPaymentMethods один или несколько значений из актуального
ответа GET /merchant-api/api/v2/payment-methods. На странице оплаты будут доступны только указанные методы.
Пример запроса на создание счета# cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/invoices \
-X POST \
-H 'x-api-key: <Ключ доступа>' \
-H 'x-sign: <ЭЦП>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
"amount": 105.05,
"currency": "KZT",
"description": "Оплата заказа №12080",
"customerPhone": "+74994550185",
"customerEmail": "support@tiyn.io",
"customerIp": "127.0.0.1",
"customData": {
"key1": "value1",
"key2": 5
},
"successUrl": "https://empty.com/successUrl",
"failUrl": "https://empty.com/failUrl",
"deliveryMethod": "URL",
"expirationDate": "2021-03-14 11:08:24.909150+03:00",
"ofdData": null,
"createToken": false,
"preferredPaymentMethods": [
"BankCard",
"google_pay",
"sbp"
]
}'
Описание параметров запроса на создание счета Создание счета — таблица 1 externalId Да Уникальный, непустая строка, максимум 100 символов Уникальный внутренний идентификатор счета в системе точки продаж amount Да Десятичное число с двумя знаками после запятой. Минимум - 0.01, максимум - 999999999999999.99 Сумма счета, разделитель дробной части - "." (точка) currency Нет KZT Валюта, в которой будет оплачен счет description Да Непустая строка, максимум 500 символов Описание счета customerPhone Нет Номер телефона в международном формате (+7xxxxxxxxxx) Номер телефона плательщика. Обязательный для способа доставки SMS customerEmail Нет Адрес электронной почты Адрес электронной почты плательщика. Обязательный для способа доставки EMAIL customerIp Нет IPv4 (xxx.xxx.xxx.xxx) IP-адрес плательщика customData Нет Различная служебная информация, поле будет возвращено в уведомлении об оплате счета. Поле любого типа, поддерживаемого форматом json successUrl Нет URL , максимум 500 символовURL-адрес страницы точки продаж, на которую будет переправлен плательщик в случае успешно оплаченного счета failUrl Нет URL , максимум 500 символовURL-адрес страницы точки продаж, на которую будет переправлен плательщик в случае неуспешно оплаченного счета deliveryMethod Нет EMAIL , SMS или URL (по умолчанию)Метод доставки счета клиенту. Метод EMAIL — доставка счета в письме по адресу электронной почты SMS — доставка счета в SMS-сообщении URL — получение ссылки на оплату в ответе на запрос на создание счета expirationDate Нет Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ, должна быть больше текущей даты Дата и время действия счета. Если в запросе указать данный параметр, то произвести оплату по данному счету можно будет только до момента наступления указанных даты и времени. Если по истечении заданного времени и даты оплата не была совершена, счет переходит в состояние 6 (InoiceCancelled), и при попытке его оплатить пользователь будет перенаправлен на страницу ошибки. Пример: 2022-04-28 17:42:30.220+03:00 ofdData Нет Данные для фискализации. В зависимости от настроек точки продаж отправляются тому или иному провайдеру фискальных данных. createToken Нет boolean, по умолчанию false Признак создания платежного токена preferredPaymentMethods Нет Непустой массив уникальных строк. Каждое значение должно присутствовать в ответе GET /merchant-api/api/v2/payment-methods Методы оплаты, которые будут доступны плательщику. Если параметр не передан, ограничение не применяется
Пример успешного ответа на запрос на создание счета# JSON Копировать
{
"success" : true ,
"data" : {
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a" ,
"externalId" : "3c5301df-d806-4fb0-9f96-f44d5d2d3827" ,
"paymentLink" : "https://business.tiyn.io/portal2/pay/i/cd422358-56dd-4039-9559-c1fb766dbbbd"
}
}
Описание параметров успешного ответа при создании счета Создание счета — таблица 2 success Да Всегда true Признак успешности выполнения команды data Да Объект Данные счета
Описание параметров объекта data Создание счета — таблица 3 uuid Да Непустая строка Идентификатор счета в Tiyn Business externalId Да Уникальный, непустая строка Уникальный внутренний идентификатор счета в системе точки продаж paymentLink Да Непустая строка Платежная ссылка для перенаправления
Пример ответа с ошибкой на запрос на создание счета# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "1" ,
"message" : "Ошибка создания счета" ,
"correlationId" : "01ee1da0-a25b-476d-a290-5eda640e14b2"
}
}
Описание параметров ответа с ошибкой создания счета Создание счета — таблица 4 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Создание счета — таблица 5 code Да Непустая строка Код ошибки (см. Описание кодов ошибок) message Да Непустая строка Описание ошибки correlationId Да Непустая строка Идентификатор корреляции запроса
Отмена счета# Метод позволяет отменить возможность оплаты счета. Доступен только для тех счетов, по которым
еще не было переходов на платежную страницу, в обратном случае запрос будет отклонен.
Пример запроса на отмену счета# cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/invoices/<uuid>/cancel \
-X PUT \
-H 'x-api-key: <Ключ доступа>' \
-H 'x-sign: <ЭЦП>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
"reason": "Отменен"
}'
uuid - идентификатор счета, полученный в успешном ответе при создании счета.
Описание параметров запроса на отмену счета Отмена счета — таблица 1 requestId Да Уникальный, непустая строка Идентификатор запроса reason Да Непустая строка Данные о причине отмены счета
Пример успешного ответа на запрос на отмену счета# JSON Копировать
{
"success" : true ,
"data" : {
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a" ,
"requestId" : "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
}
}
Описание параметров успешного ответа на запрос на отмену счета Отмена счета — таблица 2 success Да Всегда true Признак успешности выполнения команды data Да Объект Данные отменяемого счета
Описание параметров объекта data Отмена счета — таблица 3 uuid Да Непустая строка Идентификатор отменяемого счета requestId Да Уникальный, непустая строка Идентификатор запроса
Пример ответа с ошибкой на запрос на отмену счета# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "3" ,
"message" : "error" ,
"correlationId" : "01ee1da0-a25b-476d-a290-5eda640e14b2"
}
}
Описание параметров ответа с ошибкой на запрос на отмену счета Отмена счета — таблица 4 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Отмена счета — таблица 5 code Да Непустая строка Код ошибки (см. Описание кодов ошибок) message Да Непустая строка Описание ошибки correlationId Да Непустая строка Идентификатор корреляции запроса
Возврат# Используется для возврата денежных средств. Срок возврата зависит от банка, выпустившего карту плательщика.
Пример запроса на возврат# cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/invoices/<uuid>/refund \
-X PUT \
-H 'x-api-key: <Ключ доступа>' \
-H 'x-sign: <ЭЦП>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
"amount": 123.12,
"reason": "Возврат по счету №22530"
}'
uuid - идентификатор счета, полученный в успешном ответе при создании счета .
Описание параметров запроса на возврат Возврат — таблица 1 requestId Да Уникальный. Непустая строка Идентификатор запроса amount Да Десятичное число с двумя знаками после запятой Сумма возврата. Не может превышать сумму amount, указанную при создании счета. reason Да Непустая строка Данные о причине возврата
Пример успешного ответа на запрос на возврат# JSON Копировать
{
"success" : true ,
"data" : {
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a" ,
"requestId" : "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
}
}
Описание параметров успешного ответа на запрос на возврат Возврат — таблица 2 success Да Всегда true Признак успешности выполнения команды data Да Объект Данные счета
Описание параметров объекта data Возврат — таблица 3 uuid Да Непустая строка Идентификатор счета, по которому выполняется возврат requestId Да Уникальный. Непустая строка Идентификатор запроса
Пример ответа с ошибкой на запрос на возврат# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "6" ,
"message" : "error" ,
"correlationId" : "01ee1da0-a25b-476d-a290-5eda640e14b2"
}
}
Описание параметров ответа с ошибкой на запрос на возврат Возврат — таблица 4 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Возврат — таблица 5 code Да Непустая строка Код ошибки (см. Описание кодов ошибок) message Да Непустая строка Описание ошибки correlationId Да Непустая строка Идентификатор корреляции запроса
Получение данных счета# Метод позволяет запросить данные счета: статус счета, итоговая сумма счета, метод оплаты и др.
Пример запроса на получение данных# cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/invoices/<uuid> \
-X GET \
-H 'x-api-key: <Ключ доступа>' \
-H 'Content-Type: application/json; charset=utf-8' \
uuid - идентификатор счета, полученный в успешном ответе при создании счета.
Описание параметров запроса на получение данных Получение данных счета — таблица 1 uuid Да Непустая строка Идентификатор счета
Пример успешного ответа на запрос на получение данных# JSON Копировать
{
"externalId" : "3c5301df-d806-4fb0-9f96-f44d5d2d3827" ,
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a" ,
"amount" : 105.05 ,
"finalAmount" : 123.12 ,
"currency" : "KZT" ,
"description" : "Счет на оплату заказа №12080" ,
"customerPhone" : "+74994550185" ,
"customerEmail" : "support@tiyn.io" ,
"customData" : {
"key1" : "value1" ,
"key2" : 5
},
"successUrl" : "http://empty.com/successUrl" ,
"failUrl" : "http://empty.com/failUrl" ,
"deliveryMethod" : "URL" ,
"expirationDate" : "2021-03-14 11:08:24.0909150+03:00" ,
"ofdData" : null ,
"status" : {
"name" : "InvoicePaid" ,
"time" : "2020-03-14 11:08:24.0909150+03:00" ,
"message" : "message"
},
"payments" : [
{
"paymentMethod" : "BankCard" ,
"paymentDetails" : {
"account" : "411111******1111" ,
"paymentToken" : "837c06b4-b791-4f2c-89b1-a45f78cb1568"
},
"status" : {
"name" : "PaymentPaid"
}
}
]
}
Описание параметров успешного ответа на запрос на получение данных Получение данных счета — таблица 2 externalId Да Уникальный, непустая строка Уникальный внутренний идентификатор счета в системе точки продаж uuid Да Уникальный, непустая строка Идентификатор счета amount Да Десятичное число с двумя знаками после запятой Сумма счета, разделитель дробной части - "." (точка) finalAmount Да Десятичное число с двумя знаками после запятой Сумма счета с учетом возвратов и частичной авторизации currency Да KZT Валюта, в которой будет оплачен счет description Да Непустая строка Описание счета customerPhone Нет (Да для deliveryMethod = SMS ) Номер телефона в международном формате (+7xxxxxxxxxx) Номер телефона плательщика customerEmail Нет (Да для deliveryMethod = EMAIL ) Адрес электронной почты Адрес электронной почты плательщика customData Нет Объект json Дополнительные данные счета successUrl Нет URL Адрес для перенаправления плательщика в случае успешной оплаты failUrl Нет URL Адрес для перенаправления плательщика в случае неуспешной оплаты deliveryMethod Да EMAIL , SMS или URL Метод доставки счета expirationDate Нет Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ, должна быть больше текущей даты Дата, по истечении которой счет нужно отменить, например: 2021-03-14 11:08:24.0909150+00:00 ofdData Нет Объект json Данные для формирования фискального чека status Да Объект Данные о статусе заказа (см. Перечень возможных значений статусов счета) payments Нет Коллекция Данные о платежах по счету
Описание параметров объекта status Получение данных счета — таблица 3 name Да Непустая строка Название статуса time Да Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ Дата перехода в статус message Да Непустая строка Описание причины перехода в статус
Описание параметров объекта payments Получение данных счета — таблица 4 paymentMethod Да Непустая строка Метод оплаты, выбранный плательщиком в процессе оплаты paymentDetails Нет Объект Дополнительные данные платежа status Да Объект Статус платежа (см. Перечень возможных значений статусов платежа)
Описание параметров объекта details Получение данных счета — таблица 5 account Нет Непустая строка Данные об аккаунте плательщика paymentToken Нет Непустая строка Идентификатор платежного токена
Описание параметров объекта status Получение данных счета — таблица 6 name Да Непустая строка Статус платежа (см. Перечень возможных значений статусов платежа)
Пример ответа с ошибкой на запрос на получение данных# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "5" ,
"message" : "error" ,
"correlationId" : "01ee1da0-a25b-476d-a290-5eda640e14b2"
}
}
Описание параметров ответа с ошибкой на запрос на получение данных Получение данных счета — таблица 7 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Получение данных счета — таблица 8 code Да Непустая строка Код ошибки (см. Описание кодов ошибок) message Да Непустая строка Описание ошибки correlationId Да Непустая строка Идентификатор корреляции запроса
Оплата счета через Google Pay™# Google Pay™ доступен для оплаты счета только на платежной странице Tiyn Business . Точка продаж создает счет через API,
получает paymentLink и перенаправляет плательщика по этой ссылке. Если способ оплаты Google Pay активирован для
точки продаж, на платежной странице будет отображена кнопка Google Pay.
Для подключения Google Pay точке продаж необходимо связаться с менеджером Tiyn Business и предоставить:
наименование компании; домен интернет-ресурса, на котором размещена точка продаж. Точке продаж не требуется выполнять прямую интеграцию с Google Pay API или передавать данные Google Pay в API
Tiyn Business : обработка Google Pay выполняется на платежной странице Tiyn Business .
Поддерживаемые способы оплаты# При оплате через Google Pay поддерживаются платежные системы Visa и Mastercard.
Tiyn Business поддерживает два метода авторизации Google Pay:
PAN_ONLY - платеж по данным банковской карты, сохраненной в Google Pay; Tiyn Business может применить
стандартный card/3DS flow по правилам банка-эквайера;CRYPTOGRAM_3DS - платеж по токенизированной карте с криптограммой Google Pay; аутентификация выполняется через
Google Pay.Требования Google Pay# Если точка продаж упоминает Google Pay или использует материалы Google Pay в своих интерфейсах, необходимо соблюдать
Google Pay Web brand guidelines и использовать
официальные материалы Google Pay без изменения цветов, пропорций или внешнего вида.
Использование Google Pay регулируется
Google Pay and Wallet APIs Acceptable Use Policy и
Google Pay API Terms of Service .
Оплата счета# Метод позволяет передать детали платежа для осуществления оплаты.
Google Pay не принимается через метод PUT /merchant-api/api/v2/invoices/<uuid>/pay. Для оплаты через Google Pay
используйте paymentLink, полученный при создании счета, или платежную форму Tiyn.js .
Оплата счета возможна:
по реквизитам банковской карты; по платежному токену. Токен создается при создании счета, если был передан параметр createToken=true (см. Создание счета). Пример запроса оплаты счета# cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/invoices/<uuid>/pay \
-X PUT \
-H 'x-api-key: <Ключ доступа>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
"paymentMethod": "BankCard",
"details": {
"key1": "value1",
"key2": "value2"
}
}
}'
uuid - идентификатор счета, полученный в успешном ответе при создании счета.
Описание параметров запроса оплаты счета Оплата счета — таблица 1 requestId Да Уникальный. Непустая строка Идентификатор запроса paymentMethod Да Непустая строка Метод оплаты, выбранный плательщиком в процессе оплаты (см. Перечень возможных значений методов оплаты) details Да Объект Детали платежа
Описание параметров details для способа оплаты BankCard по реквизитам банковской карты Оплата счета — таблица 2 pan Да Непустая строка Номер банковской карты cardHolder Нет Непустая строка Имя и фамилия владельца банковской карты латинскими буквами cvc Да Непустая строка CVC банковской карты expYear Да Непустая строка Год окончания срока действия банковской карты expMonth Да Непустая строка Месяц окончания срока действия банковской карты
Описание параметров details для способа оплаты BankCard по токену Оплата счета — таблица 3 paymentToken Да Непустая строка Идентификатор платежного токена
Пример успешного ответа на запрос оплаты счета, если не требуется перенаправление пользователя# JSON Копировать
{
"success" : true ,
"data" : {
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a" ,
"requestId" : "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
}
}
Описание параметров успешного ответа на запрос оплаты счета Оплата счета — таблица 4 success Да Всегда true Признак успешности выполнения команды data Да Объект Данные счета
Описание параметров объекта data Оплата счета — таблица 5 uuid Да Непустая строка Идентификатор счета, для которого выполняется оплата счета requestId Да Уникальный. Непустая строка Идентификатор запроса
Пример успешного ответа на запрос оплаты счета, если требуется перенаправление пользователя# JSON Копировать
{
"success" : true ,
"data" : {
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a" ,
"requestId" : "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad" ,
"redirect" : {
"url" : "http://example.com" ,
"method" : "POST" ,
"params" : [
{
"name" : "name1" ,
"value" : "value1"
}
]
}
}
}
Перенаправление может потребоваться в случае необходимости ввода кода 3DS.
Описание параметров успешного ответа на запрос оплаты счета Оплата счета — таблица 6 success Да Всегда true Признак успешности выполнения команды data Да Объект Данные счета
Описание параметров объекта data Оплата счета — таблица 7 uuid Да Непустая строка Идентификатор счета, для которого выполняется оплата по счету requestId Да Уникальный. Непустая строка Идентификатор запроса redirect Да Объект Данные для перенаправления пользователя
Описание параметров объекта redirect Оплата счета — таблица 8 url Да URL Адрес для перенаправления плательщика method Да Непустая строка http метод params Нет Объект Дополнительные данные
Пример ответа с ошибкой на запрос оплаты счета# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "5" ,
"message" : "error" ,
"correlationId" : "01ee1da0-a25b-476d-a290-5eda640e14b2"
}
}
Описание параметров ответа с ошибкой на запрос оплаты счета Оплата счета — таблица 9 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Оплата счета — таблица 10 code Да Непустая строка Код ошибки (см. Описание кодов ошибок) message Да Непустая строка Описание ошибки correlationId Да Непустая строка Идентификатор корреляции запроса
Создание подписки# Метод позволяет создать подписку для проведения регулярных платежей, совершаемых без подтверждения клиентом.
Алгоритм работы с подпиской# Точка продаж отправляет в Tiyn Business запрос на создание счета, где указывает параметр createToken=true для создания платежного токена. Предварительно данную возможность необходимо согласовать с менеджером; Логика оплаты счета описана в "Схеме проведения запроса"; В случае если счет был успешно оплачен, то Tiyn Business отправляет точке продаж уведомление об успешной оплате, которое содержит идентификатор платежного токена;
Точка продаж возвращает ответ-подтверждение о проведенной операции. Точка продаж отправляет в Tiyn Business запрос на создание подписки, где указывает идентификатор платежного токена первого счета и данные подписки; Tiyn Business обрабатывает запрос и если подписка создана корректно, возвращает ответ, содержащий идентификатор подписки;В случае если наступил момент следующей оплаты счета Tiyn Business создает счет и проводит его аналогично первому платежу, но списание средств осуществляется уже без подтверждения клиентом; Tiyn Business отправляет точке продаж уведомление об успешной/неуспешной оплате счета, которое содержит идентификатор подписки, на основе которой создан счет;
Точка продаж возвращает ответ-подтверждение о проведенной операции.Пример запроса на создание подписки# cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/subscriptions \
-X POST \
-H 'x-api-key: <Ключ доступа>' \
-H 'x-sign: <ЭЦП>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
"paymentToken": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad",
"customerEmail": "email@gmail.com",
"name": "Подписка на сервис",
"amount": 444.44,
"startDate": "2026-02-11 00:00:00.000000+03:00",
"interval": "month",
"period": 1,
"maxPeriods": 12,
"currency": "KZT"
}'
paymentToken - идентификатор платежного токена, полученный в нотификации (callback), после оплаты счета.
Описание параметров запроса на создание подписки Создание подписки — таблица 1 requestId Да Уникальный, непустая строка, максимум 100 символов Идентификатор запроса paymentToken Да Непустая строка, максимум 100 символов Идентификатор платежного токена customerEmail Да Адрес электронной почты, максимум 100 символов Email плательщика name Да Непустая строка, максимум 100 символов Название подписки amount Да Десятичное число с двумя знаками после запятой Сумма периодического списания startDate Да Дата в формате yyyy-MM-dd HH:mm:ss.ffffffzzz Дата и время первого периодического списания interval Да day , week , month Интервал period Да Целое число Период. В комбинации с интервалом, 1 month - раз в месяц, 2 week - 1 раз в 2 недели. maxPeriods Да Целое число Максимальное количество платежей в подписке currency Нет KZT Валюта, в которой будет оформлена подписка
Пример успешного ответа на запрос на создание подписки# JSON Копировать
{
"success" : true ,
"data" : {
"uuid" : "5c91a9f9-984b-4ed5-818b-8136fdd551e2" ,
"requestId" : "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a"
}
}
Описание параметров успешного ответа на запрос на создания подписки Создание подписки — таблица 2 success Да Всегда true Признак успешности выполнения команды data Да Объект Данные подписки
Описание параметров объекта data Создание подписки — таблица 3 uuid Да Непустая строка Идентификатор подписки requestId Да Уникальный, непустая строка Идентификатор запроса
Пример ответа с ошибкой на запрос на создание подписки# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "7" ,
"message" : "Ошибка создания подписки"
}
}
Описание параметров ответа с ошибкой на запрос на создание подписки Создание подписки — таблица 4 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Создание подписки — таблица 5 code Да Непустая строка Код ошибки (см. Описание кодов ошибок) message Да Непустая строка Описание ошибки
Отмена подписки# Метод позволяет отменить активную подписку.
Пример запроса на отмену подписки# cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/subscriptions/<uuid> \
-X DELETE \
-H 'x-api-key: <Ключ доступа>' \
-H 'x-sign: <ЭЦП>' \
-H 'Content-Type: application/json; charset=utf-8' \
uuid - идентификатор подписки, полученный в ответе на ее создание.
Пример успешного ответа на запрос на отмены подписки# JSON Копировать
{
"success" : true ,
"data" : null
}
Описание параметров успешного ответа на запрос на отмены подписки Отмена подписки — таблица 1 success Да Всегда true Признак успешности выполнения команды data Да Объект Данные запроса
Получение баланса точки продаж# Пример запроса на получение данных# Метод позволяет по ключу доступа получить баланс данной точки продаж. Если точка продаж работает с несколькими валютами, то
баланс будет получен по каждой из валют.
cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/balance \
-X GET \
-H 'x-api-key: <Ключ доступа>' \
-H 'Content-Type: application/json; charset=utf-8' \
Пример успешного ответа на запрос на получение данных# JSON Копировать
{
"success" : true ,
"data" : [
{
"currency" : "KZT" ,
"balance" : 890.12
}
]
}
Описание параметров успешного ответа на запрос на получение данных Получение баланса точки продаж — таблица 1 success Да Всегда true Признак успешности выполнения команды data Да Коллекция Балансы точки продаж в разных валютах
Описание параметров элемента коллекции data
Получение баланса точки продаж — таблица 2 currency Да Непустая строка Валюта счёта balance Да Десятичное число с двумя знаками после запятой Баланс счёта
Пример ответа с ошибкой на запрос на получение данных# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "8" ,
"message" : "error" ,
"correlationId" : "01ee1da0-a25b-476d-a290-5eda640e14b2"
}
}
Описание параметров ответа с ошибкой на запрос на получение данных Получение баланса точки продаж — таблица 3 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Получение баланса точки продаж — таблица 4 code Да Непустая строка Код ошибки (см. Описание кодов ошибок) message Да Непустая строка Описание ошибки correlationId Да Непустая строка Идентификатор корреляции запроса
Создание выплаты# Метод позволяет осуществлять вывод средств на банковскую карту. Вывод средств на банковскую карту возможен путем передачи в запросе реквизитов банковской карты или платежного токена карты (см. "Сохранение банковской карты").
Для активации возможности создавать выплаты необходимо связаться с менеджером Tiyn Business.
Пример запроса на создание выплаты# cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/payouts \
-X POST \
-H 'x-api-key: <Ключ доступа>' \
-H 'x-sign: <ЭЦП>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
"amount": 10005.05,
"currency": "KZT",
"description": "Вывод себе на карту",
"destination": {
"pan": "41233543544386",
"cardholder": "Ivan Pupkin"
},
"payoutMethod": "BankCard"
}'
Описание параметров запроса на создание выплаты Создание выплаты — таблица 1 externalId Да Уникальный, непустая строка, максимум 100 символов Уникальный внутренний идентификатор выплаты в системе точки продаж amount Да Десятичное число с двумя знаками после запятой. Минимум - 0.01, максимум - 999999999999999.99 Сумма выплаты, разделитель дробной части - "." (точка) currency Нет KZT Валюта, в которой будет совершен вывод средств description Да Непустая строка, максимум 500 символов Описание выплаты destination Да Объект Реквизиты выплаты payoutMethod Да Непустая строка Способ вывода
Описание параметров объекта destination для способа вывода на банковскую карту по реквизитам cURL Копировать
{
...
"destination" : {
"pan" : "41233543544386" ,
"cardholder" : "Ivan Pupkin"
},
"payoutMethod" : "BankCard"
}
Создание выплаты — таблица 2 pan Да Непустая строка. 16-19 цифр Номер банковской карты cardholder Нет Непустая строка Имя и фамилия владельца банковской карты латинскими буквами
Описание параметров объекта destination для способа вывода на банковскую карту по платежному токену cURL Копировать
{
...
"destination" : {
"payoutToken" : "837c06b4-b791-4f2c-89b1-a45f78cb1568"
},
"payoutMethod" : "BankCard"
}
Создание выплаты — таблица 3 payoutToken Да Непустая строка Платежный токен банковской карты
Пример успешного ответа на запрос на создание выплаты# JSON Копировать
{
"success" : true ,
"data" : {
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a" ,
"externalId" : "3c5301df-d806-4fb0-9f96-f44d5d2d3827"
}
}
Описание параметров успешного ответа при создании выплаты Создание выплаты — таблица 4 success Да Всегда true Признак успешности выполнения команды data Да Объект Данные выплаты
Описание параметров объекта data Создание выплаты — таблица 5 uuid Да Непустая строка Идентификатор выплаты в Tiyn Business externalId Да Уникальный, непустая строка Уникальный внутренний идентификатор выплаты в системе точки продаж
Пример ответа с ошибкой на запрос на создание выплаты# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "9" ,
"message" : "Ошибка создания выплаты" ,
"correlationId" : "01ee1da0-a25b-476d-a290-5eda640e14b2"
}
}
Описание параметров ответа с ошибкой создания выплаты Создание выплаты — таблица 6 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Создание выплаты — таблица 7 code Да Непустая строка Код ошибки (см. Описание кодов ошибок) message Да Непустая строка Описание ошибки correlationId Да Непустая строка Идентификатор корреляции запроса
Получение данных выплаты# Метод позволяет запросить данные выплаты: статус выплаты, сумму, метод вывода и др.
Пример запроса на получение данных# cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/payouts/<uuid> \
-X GET \
-H 'x-api-key: <Ключ доступа>' \
-H 'Content-Type: application/json; charset=utf-8' \
uuid - идентификатор выплаты, полученный в успешном ответе при создании выплаты.
Описание параметров запроса на получение данных Получение данных выплаты — таблица 1 uuid Да Непустая строка Идентификатор выплаты
Пример успешного ответа на запрос на получение данных# JSON Копировать
{
"success" : true ,
"data" : {
"externalId" : "8041905d-c3cb-4c83-a232-1a98891023b8" ,
"uuid" : "8904c0ef-7667-4ec2-b63a-57c50faf0248" ,
"commission" : {
"amount" : "12.33" ,
"currency" : "KZT"
},
"payoutMethod" : "BankCard" ,
"amount" : 813.03 ,
"currency" : "KZT" ,
"description" : "some description" ,
"destination" : {
"masked_pan" : "411111******1111"
},
"status" : {
"name" : "PayoutSucceeded" ,
"time" : "2022-04-13 08:42:22.501903+00:00" ,
"message" : "Получено событие о удачном проведении транзакции на выплату"
}
}
}
Описание параметров успешного ответа на запрос на получение данных Получение данных выплаты — таблица 2 success Да Всегда true Признак успешности выполнения команды data Да Объект Данные выплаты
Описание параметров объекта data Получение данных выплаты — таблица 3 externalId Да Уникальный, непустая строка Уникальный внутренний идентификатор выплаты в системе точки продаж uuid Да Уникальный, непустая строка Идентификатор выплаты commission Да Объект Данные о комиссии выплаты payoutMethod Да Непустая строка Метод вывода amount Да Десятичное число с двумя знаками после запятой Сумма выплаты, разделитель дробной части - "." (точка) currency Да Непустая строка Валюта вывода description Да Непустая строка Описание выплаты destination Да Объект Реквизиты выплаты status Да Объект Данные о статусе выплаты (см. Перечень возможных значений статусов выплаты )
Описание параметров объекта commission Получение данных выплаты — таблица 4 amount Да Десятичное число с двумя знаками после запятой Сумма комиссии, разделитель дробной части - "." (точка) currency Да Непустая строка Валюта комиссии
Описание параметров объекта status Получение данных выплаты — таблица 5 name Да Непустая строка Название статуса time Да Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ Дата перехода в статус message Да Непустая строка Описание причины перехода в статус
Описание параметров объекта destination Получение данных выплаты — таблица 6 masked_pan Да, если способ вывода BankCard Непустая строка Маскированный номер банковской карты
Пример ответа с ошибкой на запрос на получение данных# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "10" ,
"message" : "error" ,
"correlationId" : "01ee1da0-a25b-476d-a290-5eda640e14b2"
}
}
Описание параметров ответа с ошибкой на запрос на получение данных Получение данных выплаты — таблица 7 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Получение данных выплаты — таблица 8 code Да Непустая строка Код ошибки (см. Описание кодов ошибок ) message Да Непустая строка Описание ошибки correlationId Да Непустая строка Идентификатор корреляции запроса
Подтверждение двухэтапной выплаты# Метод позволяет подтверждать двухэтапную выплату. Подтверждение выполняется для выплаты в статусе
PayoutWaitingConfirmation. Для активации возможности создавать двухэтапные выплаты необходимо связаться с менеджером
Tiyn Business.
Пример запроса на подтверждение выплаты# cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/payouts/<uuid>/confirm \
-X POST \
-H 'x-api-key: <Ключ доступа>' \
-H 'x-sign: <ЭЦП>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{}'
uuid - идентификатор выплаты, полученный в успешном ответе при создании выплаты.
Описание параметров запроса на подтверждение выплаты Подтверждение двухэтапной выплаты — таблица 1 uuid Да Непустая строка Идентификатор выплаты
Пример успешного ответа на запрос на подтверждения выплаты# JSON Копировать
{
"success" : true ,
"data" : {
"uuid" : "8904c0ef-7667-4ec2-b63a-57c50faf0248"
}
Описание параметров успешного ответа при создании выплаты Подтверждение двухэтапной выплаты — таблица 2 success Да Всегда true Признак успешности выполнения команды data Да Объект Данные выплаты
Описание параметров объекта data Подтверждение двухэтапной выплаты — таблица 3 uuid Да Непустая строка Идентификатор подтверждаемой выплаты
Пример ответа с ошибкой на запрос на подтверждения выплаты# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "13" ,
"message" : "Ошибка подтверждения выплаты" ,
"correlationId" : "01ee1da0-a25b-476d-a290-5eda640e14b2"
}
}
Описание параметров ответа с ошибкой подтверждения выплаты Подтверждение двухэтапной выплаты — таблица 4 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Подтверждение двухэтапной выплаты — таблица 5 code Да Непустая строка Код ошибки (см. Описание кодов ошибок) message Да Непустая строка Описание ошибки correlationId Да Непустая строка Идентификатор корреляции запроса
Отклонение двухэтапной выплаты# Метод позволяет отклонять двухэтапную выплату. Отклонение выполняется для выплаты в статусе PayoutWaitingConfirmation.
Для активации возможности создавать двухэтапные выплаты необходимо связаться с менеджером Tiyn Business.
Пример запроса на отклонение выплаты# cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/payouts/<uuid>/decline \
-X POST \
-H 'x-api-key: <Ключ доступа>' \
-H 'x-sign: <ЭЦП>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{}'
uuid - идентификатор выплаты, полученный в успешном ответе при создании выплаты.
Описание параметров запроса на отклонение выплаты Отклонение двухэтапной выплаты — таблица 1 uuid Да Непустая строка Идентификатор выплаты
Пример успешного ответа на запрос на отклонение выплаты# JSON Копировать
{
"success" : true ,
"data" : {
"uuid" : "8904c0ef-7667-4ec2-b63a-57c50faf0248"
}
Описание параметров успешного ответа при отклонении выплаты Отклонение двухэтапной выплаты — таблица 2 success Да Всегда true Признак успешности выполнения команды data Да Объект Данные выплаты
Описание параметров объекта data Отклонение двухэтапной выплаты — таблица 3 uuid Да Непустая строка Идентификатор отклоняемой выплаты
Пример ответа с ошибкой на запрос на отклонение выплаты# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "14" ,
"message" : "Ошибка отклонения выплаты" ,
"correlationId" : "01ee1da0-a25b-476d-a290-5eda640e14b2"
}
}
Описание параметров ответа с ошибкой отклонения выплаты Отклонение двухэтапной выплаты — таблица 4 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Отклонение двухэтапной выплаты — таблица 5 code Да Непустая строка Код ошибки (см. Описание кодов ошибок) message Да Непустая строка Описание ошибки correlationId Да Непустая строка Идентификатор корреляции запроса
Сохранение банковской карты# Метод позволяет сохранить реквизиты банковской карты и получить платежный токен, с помощью которого можно проводить выплаты.
Пример запроса на сохранение банковской карты# cURL Копировать
curl https://business.tiyn.io/merchant-api/api/v2/payout-cards \
-X POST \
-H 'x-api-key: <Ключ доступа>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"pan": "41233543544386"
}'
Описание параметров запроса на сохранение банковской карты Сохранение банковской карты — таблица 1 pan Да Непустая строка. 16-19 цифр Номер банковской карты
Пример успешного ответа на запрос сохранения банковской карты# JSON Копировать
{
"success" : true ,
"data" : {
"payoutToken" : "c6eae048-072c-44cb-aaa8-3822989cfb9c"
}
Описание параметров успешного ответа при сохранении банковской карты Сохранение банковской карты — таблица 2 success Да Всегда true Признак успешности выполнения команды data Да Объект Данные выплаты
Описание параметров объекта data Сохранение банковской карты — таблица 3 payoutToken Да Непустая строка Платежный токен банковской карты
Пример ответа с ошибкой на запрос сохранения банковской карты# JSON Копировать
{
"success" : false ,
"error" : {
"code" : "14" ,
"message" : "Ошибка сохранения банковкой карты" ,
"correlationId" : "01ee1da0-a25b-476d-a290-5eda640e14b2"
}
}
Описание параметров ответа с ошибкой отклонения выплаты Сохранение банковской карты — таблица 4 success Да Всегда false Признак успешности выполнения команды error Да Объект Данные об ошибке
Описание параметров объекта error Сохранение банковской карты — таблица 5 code Да Непустая строка Код ошибки (см. Описание кодов ошибок) message Да Непустая строка Описание ошибки correlationId Да Непустая строка Идентификатор корреляции запроса
Платежная форма Tiyn.js# Tiyn.js — это безопасная и кастомизируемая платёжная форма для приёма платежей на сайте, которая не требует от мерчанта сертификата PCI DSS. Карточные данные вводятся внутри защищённого iframe, загружаемого с PCI DSS совместимого CDN Tiyn.
Если для точки продаж активирован Google Pay, кнопка Google Pay может отображаться внутри платежной формы Tiyn.js .
Требования к подключению, ограничения и политики Google Pay такие же, как для оплаты по paymentLink.
Сценарий оплаты с помощью платежной формы# Точка продаж отправляет в Tiyn Business запрос на создание счета. Если счет создан корректно, то в ответ на запрос Tiyn Business вернет uuid счета. Точка продаж инициализирует платежную форму с передачей необходимых параметров, а именно uuid счета и параметрами кастомизации. Tiyn.js создаёт защищённый iframe, загружаемый с PCI DSS совместимого CDN Tiyn. Плательщик заполняет банковские реквизиты и нажимает кнопку оплаты внутри iframe. Данные карты передаются напрямую в Tiyn Business . Tiyn Business обрабатывает платеж.После завершения обработки Tiyn Business отправляет событие CHECKOUT_SUBMIT_RESULT в iframe с результатом оплаты счета. Точка продаж получает событие CHECKOUT_SUBMIT_RESULT.
В случае успешной оплаты счета плательщик перенаправляется на страницу, указанную при создании счета в параметре
successUrl; В случае неуспешной оплаты происходит перенаправление на страницу, указанную при создании счета в параметре
failUrl; Tiyn Business отправляет точке продаж уведомление об успешной/неуспешной оплате счета.Точка продаж возвращает ответ-подтверждение о проведенной операции. Интеграция# Подключение Tiyn.js возможно одним из перечисленных ниже способов.
Вариант 1. Подключение через script tag (Tilda, WordPress, любой HTML) Для подключения необходимо добавить на свою страницу следующий код:
HTML Копировать
<script src= "https://business.tiyn.io/tiynjs/tiyn.js" ></script>
<div id= "payment" ></div>
<script>
var checkout = Tiyn.createCheckout({
invoiceToken: 'YOUR_TOKEN' , // uuid счета
locale: 'ru'
});
checkout.mount( '#payment' );
checkout.on( 'CHECKOUT_SUBMIT_RESULT' , function (event) {
if (event.success) {
alert( 'Оплата прошла!' );
}
});
</script> Вариант 2. Подключение через npm (Vanilla JS) Установка пакета:
Код Копировать
npm install @tiynjs/sdk Использование в коде:
JavaScript Копировать
import { loadSDK } from '@tiynjs/sdk' ;
const sdk = loadSDK(); // по умолчанию CDN: https://business.tiyn.io/tiynjs
const checkout = sdk.createCheckout({
invoiceToken: 'YOUR_TOKEN' , // uuid счета
locale: 'ru' ,
});
checkout.mount( '#checkout-container' );
checkout.on( 'CHECKOUT_SUBMIT_RESULT' , (event) => {
console.log( 'Результат:' , event);
}); Вариант 3: Подключение через npm (React) Установка пакетов:
Код Копировать
npm install @tiynjs/sdk @tiynjs/react Использование компонента:
JavaScript Копировать
import { loadSDK } from '@tiynjs/sdk' ;
import { Checkout } from '@tiynjs/react' ;
const sdk = loadSDK();
function PaymentPage() {
return (
<Checkout
sdk={sdk}
invoiceToken= "YOUR_TOKEN"
locale= "ru"
onSubmitResult={(result) => console.log(result)}
/>
);
} Кастомизация формы# Есть возможность управлять внешним видом формы, передавая объект theme при создании экземпляра createCheckout. Это позволяет полностью адаптировать форму под дизайн сайта точки продаж.
JavaScript Копировать
sdk.createCheckout({
theme: {
colors: {
primary: '#4778F5' ,
text: '#1a1a2e' ,
border: '#e0e0e0' ,
buttonText: '#ffffff' ,
icon: '#666666' ,
inputBackground: '#ffffff' ,
containerBackground: '#ffffff' ,
},
typography: { fontFamily: 'Inter, sans-serif' , fontWeight: '400' },
borders: { radius: '12px' },
spacing: { fieldGap: '16px' , containerPadding: '24px' },
}
});
Описание параметров объекта theme Платежная форма Tiyn.js — таблица 1 colors Объект Цветовая схема typography Объект Стиль текста borders Объект Границы spacing Объект Отступы
Описание параметров объекта colors Платежная форма Tiyn.js — таблица 2 primary Строка Акцентный цвет — кнопка «Оплатить», ссылки, фокус полей text Строка Основной цвет текста — заголовки, лейблы, значения полей border Строка Цвет рамок полей ввода и разделителей buttonText Строка Цвет текста внутри основной кнопки icon Строка Цвет вспомогательных иконок и secondary-текста inputBackground Строка Фон полей ввода containerBackground Строка Фон всего виджета оплаты
Описание параметров объекта typography Платежная форма Tiyn.js — таблица 3 fontFamily Строка Шрифтовой стек — основной шрифт + fallback-цепочка fontWeight Строка Базовая насыщенность шрифта (400 = regular)
Описание параметров объекта borders Платежная форма Tiyn.js — таблица 4 radius Строка Скругление углов полей, кнопок, карточек
Описание параметров объекта spacing Платежная форма Tiyn.js — таблица 5 fieldGap Строка Отступ между полями формы containerPadding Строка Внутренний отступ контейнера виджета
API Tiyn.js# Методы SDK loadSDK(options?)Загружает SDK с CDN.
Платежная форма Tiyn.js — таблица 6 cdnUrlstringhttps://business.tiyn.io/tiynjsURL CDN с tiyn.js и checkout.html apiBaseUrlstringhttps://business.tiyn.io/payment-flow-bffURL API бэкенда (менять не нужно)
Возвращает: объект SDK с методом createCheckout.
createCheckout(options)Создаёт экземпляр платёжной формы.
Платежная форма Tiyn.js — таблица 7 invoiceTokenstringuuid счета, полученный при создании счета localestringЛокаль ('ru', 'en') themePartial<CheckoutTheme>Объект с параметрами темы
Возвращает: экземпляр Checkout с методами для управления формой.
Методы экземпляра checkout После создания экземпляра через createCheckout доступны следующие методы:
Платежная форма Tiyn.js — таблица 8 mount(selector)Монтирует платёжную форму в DOM-элемент. unmount()Удаляет форму из DOM. on(event, handler)Подписывается на событие. Возвращает функцию для отписки. updateTheme(theme)Динамически обновляет тему оформления. setLocale(locale)Динамически меняет язык формы ('ru', 'en'). setInvoiceToken(token)Меняет идентификатор инвойса для новой попытки платежа.
События События, на которые можно подписаться, используя метод on():
Платежная форма Tiyn.js — таблица 9 CHECKOUT_READY{}Форма полностью загружена и готова к работе. CHECKOUT_RESIZE{ height }Высота iframe изменилась (например, при появлении ошибки). Позволяет динамически подстраивать контейнер на сайте. CHECKOUT_SUBMIT_RESULT{ success, data?, error? }Возвращает результат попытки оплаты. CHECKOUT_STEP_CHANGE{ step }Изменился этап платежа (например, 'methodSelection', 'cardForm', 'processing', 'paid', ...).
Перечень возможных значений статусов счета# Перечень возможных значений статусов счета — таблица 1 InvoiceCreated Счет создан InvoicePaymentCreated Платеж по счету создан InvoicePaid Счет оплачен InvoiceFailed Ошибка при оплате счета InvoiceRefunded Выполнен возврат InvoiceCancelled Счет отменен InvoicePartlyRefunded Выполнен частичный возврат
Перечень возможных значений статусов платежа# Перечень возможных значений статусов платежа — таблица 1 PaymentCreated Платеж создан PaymentTransactionCreated Транзакция по платежу создана PaymentPaid Платеж успешен PaymentFailed Платеж отклонен PaymentRefunded Выполнен возврат PaymentCancelled Платеж отменен
Перечень возможных значений статусов выплаты# Перечень возможных значений статусов выплаты — таблица 1 PayoutSucceeded Выплата проведена успешно PayoutFailed Выплата отклонена PayoutWaitingConfirmation Двухэтапная выплата в ожидании подтверждения PayoutConfirmed Двухэтапная выплата подтверждена
Оповещение об изменении статуса счета# Оповещение об изменении статуса (Callback) происходит путем отправки POST-запроса по адресу, указанному в настройках
точки продаж (раздел Технические настройки , параметр Callback URL )
Если на оповещение получен невалидный ответ/валидный ответ с ошибкой, или же ответ не получен, система отправляет
повторное оповещение позднее. Оповещение отправляется повторно конечное число раз.
Пример оповещения от Tiyn Business# cURL Копировать
curl https://business.tiyn.io/resultUrl \
-X POST \
-H 'x-sign: <ЭЦП>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"externalId" : "3c5301df-d806-4fb0-9f96-f44d5d2d3827" ,
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a" ,
"amount" : 105.05 ,
"finalAmount" : 123.12 ,
"currency" : "KZT" ,
"description" : "Счет на оплату заказа №12080" ,
"customerPhone" : "+74994550185" ,
"customerEmail" : "support@tiyn.io" ,
"customData" : {
"key1" : "value1" ,
"key2" : 5
},
"successUrl" : "http://empty.com/successUrl" ,
"failUrl" : "http://empty.com/failUrl" ,
"deliveryMethod" : "URL" ,
"expirationDate" : "2021-03-14 11:08:24.909150+03:00" ,
"ofdData" : null ,
"status" : {
"name" : "InvoicePaid" ,
"time" : "2019 -03-14 11:08:24.0909150+03:00" ,
"message" : "message"
},
"payments" : [
{
"paymentMethod" : "BankCard" ,
"paymentDetails" : {
"account" : "411111******1111" ,
"paymentToken" : "837c06b4-b791-4f2c-89b1-a45f78cb1568"
},
"status" : {
"name" : "PaymentPaid"
}
}
]
}
Описание параметров оповещения от Tiyn Business Оповещение об изменении статуса счета — таблица 1 externalId Да Уникальный, непустая строка Уникальный внутренний идентификатор счета в системе точки продаж uuid Да Уникальный, непустая строка Идентификатор счета amount Да Десятичное число с двумя знаками после запятой Сумма счета, разделитель дробной части - "." (точка) finalAmount Да Десятичное число с двумя знаками после запятой Сумма счета с учетом возвратов и частичной авторизации, разделитель дробной части - "." (точка) currency Да KZT Валюта счета description Да Непустая строка Описание счета customerPhone Нет Номер телефона в международном формате (+7xxxxxxxxxx) Номер телефона плательщика. Обязателен для deliveryMethod = SMS customerEmail Нет Адрес электронной почты Адрес электронной почты плательщика. Обязателен для deliveryMethod = EMAIL customData Нет Объект json Дополнительные данные счета successUrl Нет URL Адрес для перенаправления плательщика в случае успешной оплаты failUrl Нет URL Адрес для перенаправления плательщика в случае неуспешной оплаты deliveryMethod Да EMAIL , SMS или URL Метод доставки счета subscriptionUuid Нет Непустая строка Идентификатор подписки, в случае если счет был создан по подписке expirationDate Нет Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ, должна быть больше текущей даты Дата, по истечении которой счет будет отменен (переведен в статус Cancelled), если не произошла оплата. Например: 2021-03-14 11:08:24.0909150+03:00 ofdData Нет Объект json Данные для формирования фискального чека (см. файл-приложение Отправка данных в налоговую.pdf status Да Объект Данные о статусе счета (см. Перечень возможных значений статусов счета) payments Да Коллекция Данные о платежах по счету
Описание параметров объекта status Оповещение об изменении статуса счета — таблица 2 name Да Непустая строка Название статуса time Да Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ Дата перехода в статус, например: 2021-03-14 11:08:24.0909150+03:00 message Да Непустая строка Описание причины перехода в статус
Описание параметров объекта payments Оповещение об изменении статуса счета — таблица 3 paymentMethod Да Непустая строка Метод оплаты, выбранный плательщиком в процессе оплаты (см. Перечень возможных значений статусов счета) paymentDetails Нет Объект Дополнительные данные платежа status Да Объект Статус платежа (см. Перечень возможных значений статусов платежа)
Описание параметров объекта details Оповещение об изменении статуса счета — таблица 4 account Нет Непустая строка Данные об аккаунте плательщика paymentToken Нет Непустая строка Идентификатор платежного токена
Описание параметров объекта status Оповещение об изменении статуса счета — таблица 5 name Да Непустая строка Статус платежа (см. Перечень возможных значений статусов платежа)
Пример ожидаемого успешного ответа от системы мерчанта на оповещение от Tiyn Business# JSON Копировать
{
"success" : true ,
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}
Пример ожидаемого ответа с ошибкой от системы мерчанта на оповещение от Tiyn Business# JSON Копировать
{
"success" : false ,
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}
Описание параметров ожидаемых ответов от системы мерчанта на оповещение от Tiyn Business Оповещение об изменении статуса счета — таблица 6 success Да true/ falseПризнак успешности выполнения команды uuid Да Непустая строка Идентификатор счета
Оповещение об изменении статуса выплаты# Оповещение об изменении статуса (Callback) происходит путем отправки POST-запроса по адресу, указанному в настройках
точки продаж (раздел Технические настройки , параметр Payout Callback URL )
Если на оповещение получен невалидный ответ/валидный ответ с ошибкой, или же ответ не получен, система отправляет
повторное оповещение позднее. Оповещение отправляется повторно конечное число раз.
Пример оповещения от Tiyn Business# cURL Копировать
curl https://business.tiyn.io/PayoutResultURL \
-X POST \
-H 'x-sign: <ЭЦП>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"externalId" : "3c5301df-d806-4fb0-9f96-f44d5d2d3827" ,
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a" ,
"commission" : {
"amount" : "12.33" ,
"currency" : "KZT"
},
"amount" : 10005.05 ,
"currency" : "KZT" ,
"description" : "Вывод себе на карту" ,
"destination" : {
"cardholder" : "Ivan Pupkin" ,
"masked_pan" : "412335******4386"
},
"status" : {
"name" : "PayoutSucceeded" ,
"time" : "2020-08-01 11:08:24.0909150+03:00" ,
"message" : "message"
},
"payoutMethod" : "BankCard"
}
Описание параметров оповещения от Tiyn Business Оповещение об изменении статуса выплаты — таблица 1 externalId Да Уникальный, непустая строка Уникальный внутренний идентификатор выплаты в системе точки продаж uuid Да Уникальный, непустая строка Идентификатор выплаты commission Да Объект Данные о комиссии выплаты amount Да Десятичное число с двумя знаками после запятой Сумма выплаты, разделитель дробной части - "." (точка) currency Да Непустая строка Валюта выплаты description Да Непустая строка Описание выплаты status Да Объект Данные о статусе выплаты (см. "Перечень возможных значений статусов выплаты ") payoutMethod Да Непустая строка Способ вывода
Описание параметров объекта commission Оповещение об изменении статуса выплаты — таблица 2 amount Да Десятичное число с двумя знаками после запятой Сумма комиссии, разделитель дробной части - "." (точка) currency Да Непустая строка Валюта комиссии
Описание параметров объекта status Оповещение об изменении статуса выплаты — таблица 3 name Да Непустая строка Название статуса time Да Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ Дата перехода в статус, например: 2021-03-14 11:08:24.0909150+03:00 message Да Непустая строка Описание причины перехода в статус
Описание параметров объекта destination для способа вывода на банковскую карту Оповещение об изменении статуса выплаты — таблица 4 masked_pan Да Непустая строка. 16-19 цифр Маскированый номер банковской карты cardholder Нет Непустая строка Имя и фамилия владельца банковской карты латинскими буквами
Пример ожидаемого успешного ответа от системы мерчанта на оповещение от Tiyn Business# JSON Копировать
{
"success" : true ,
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}
Пример ожидаемого ответа с ошибкой от системы мерчанта на оповещение от Tiyn Business# JSON Копировать
{
"success" : false ,
"uuid" : "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}
Описание параметров ожидаемых ответов от системы мерчанта на оповещение от Tiyn Business Оповещение об изменении статуса выплаты — таблица 5 success Да true/ falseПризнак успешности выполнения команды uuid Да Непустая строка Идентификатор выплаты
Описание кодов ошибок# Описание кодов ошибок — таблица 1 1 Ошибка создания счета 2 Ошибка авторизации платежа 3 Ошибка отмены платежа 5 Ошибка при получении данных счета 6 Ошибка выполнения возврата 7 Ошибка создания подписки 8 Ошибка при получении данных точки продаж 9 Ошибка создания выплаты 10 Ошибка при получении данных выплаты 13 Ошибка при подтверждении двухэтапной выплаты 14 Ошибка при отклонении двухэтапной выплаты -1 Системная ошибка
Тестирование# Тестовые карты для проведения платежей и осуществления выплат (для тестовых точек продаж Tiyn Business)
Платежи# Авторизационные данные:
expiration date = 12/30; сvc/cvv2 = 123; 3ds=123456. Тестирование — таблица 1 5555555555554477 Да, v1 Нет Успешно 4111111111111111 Да, v2 Нет Успешно 4311111111111119 Нет Нет Успешно 4111111111111160 Нет Нет Отклонен 4111111111111152 Да Да Успешно 5555555555554501 Нет Да Успешно 4111111111111137 Да Да Отклонен 5105105105105134 Нет Да Отклонен
Выплаты# Тестирование — таблица 2 4111111111111111 Успешно 5555555555555599 Ожидание 4222222222222222 Отклонена (Недостаточно средств)