Перейти к содержимому

Документация Merchant API

Создавайте счета, принимайте оплату, оформляйте возвраты и отправляйте выплаты из своей системы. Обмен — по HTTPS в формате JSON с подписью запросов.

Базовый адрес
https://business.tiyn.io/merchant-api/api/v2
Заголовки
x-api-key, x-sign
Подпись
HMAC-SHA512 от тела запроса, base64
Платёжная форма
Tiyn.js для сайта и React

Подготовка к интеграции#

Регистрация и создание точки продаж через Tiyn Business#

Для подготовки к интеграции необходимо:

  1. Зарегистрировать личный кабинет Tiyn Business на странице https://business.tiyn.io/cabinet/sign-up;
  2. В личном кабинете создать точку продаж в разделе Точки продаж;
  3. Нажать на карточку созданной точки продаж, перейти в Технические настройки и сгенерировать новый секретный ключ (secretPhrase) для формирования подписи;
  4. Если требуется передача уведомлений об изменении статусов счета в одну из ваших систем (Callback), заполнить поле Callback URL адресом для получения уведомлений;
  5. Активировать созданную точку продаж, связавшись с персональным менеджером.

HTTP-заголовки#

Взаимодействие с сервисом происходит посредством передачи HTTP-запросов.

Запросы могут включать следующие заголовки:

  • Content-Type: application/json; charset=utf-8
  • x-api-key: <API Key>
  • x-sign: <электронно-цифровая подпись> (кроме получения данных счета и данных точки продаж)

Алгоритм формирования ЭЦП#

ЭЦП формируется следующим образом:

  1. От сформированного тела запроса (body) вычисляется хеш по алгоритму HMAC-SHA512. В качестве ключа используется secretPhrase), кодировка UTF-8
  2. Полученное значение переводится в base64

Примеры реализации алгоритма формирования x-sign#

Пример на языке C#. Перед запуском задайте переменную окружения MERCHANT_API_URL со значением https://business.tiyn.io/merchant-api/api/v2.

Пример на языке PHP — по запросу в поддержке

Схема проведения запроса#

  1. Точка продаж отправляет в Tiyn Business запрос на создание счета;
  2. Tiyn Business обрабатывает запрос и, если счет создан корректно, возвращает данные, содержащие ссылку для перехода на оплату;
  3. Плательщик переходит по ссылке выбирает способ оплаты и вводит платежные данные;
  4. Tiyn Business отправляет запрос на списание денежных средств эквайеру;
  5. Tiyn Business получает ответ об успешной/неуспешной оплате счета от эквайера; происходит переадресация плательщика на страницу точки продаж
    1. В случае успешной оплаты счета плательщик перенаправляется на страницу, указанную при создании счета в параметре successUrl;
    2. В случае неуспешной оплаты происходит перенаправление на страницу, указанную при создании счета в параметре failUrl;
  6. Tiyn Business отправляет точке продаж уведомление об успешной/неуспешной оплате счета; Точка продаж возвращает ответ-подтверждение о проведенной операции.

Получение доступных методов оплаты#

GET
/payment-methods

Метод позволяет получить актуальный список методов оплаты, доступных для магазина. Полученные значения используются при создании счета в параметре preferredPaymentMethods. Список зависит от настроек магазина, поэтому для его получения и создания счета необходимо использовать один и тот же x-api-key.

Порядок использования#

  1. Получить список доступных методов оплаты с помощью GET /merchant-api/api/v2/payment-methods;
  2. Выбрать из ответа один или несколько методов, которые должны быть доступны плательщику;
  3. Передать выбранные значения без изменений в параметре 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ДаНепустая строкаИдентификатор корреляции запроса

Создание счета#

POST
/invoices

Метод позволяет создать счет на оплату и отправить его плательщику.

Чтобы ограничить выбор плательщика, передайте в 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ДаНепустая строкаИдентификатор корреляции запроса

Отмена счета#

PUT
/invoices/{uuid}/cancel

Метод позволяет отменить возможность оплаты счета. Доступен только для тех счетов, по которым еще не было переходов на платежную страницу, в обратном случае запрос будет отклонен.

Пример запроса на отмену счета#

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ДаНепустая строкаИдентификатор корреляции запроса

Возврат#

PUT
/invoices/{uuid}/refund

Используется для возврата денежных средств. Срок возврата зависит от банка, выпустившего карту плательщика.

Пример запроса на возврат#

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ДаНепустая строкаИдентификатор корреляции запроса

Получение данных счета#

GET
/invoices/{uuid}

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

Пример запроса на получение данных#

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.

Оплата счета#

PUT
/invoices/{uuid}/pay

Метод позволяет передать детали платежа для осуществления оплаты.

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ДаНепустая строкаИдентификатор корреляции запроса

Создание подписки#

POST
/subscriptions

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

Алгоритм работы с подпиской#

  1. Точка продаж отправляет в Tiyn Business запрос на создание счета, где указывает параметр createToken=true для создания платежного токена. Предварительно данную возможность необходимо согласовать с менеджером;
  2. Логика оплаты счета описана в "Схеме проведения запроса";
  3. В случае если счет был успешно оплачен, то Tiyn Business отправляет точке продаж уведомление об успешной оплате, которое содержит идентификатор платежного токена; Точка продаж возвращает ответ-подтверждение о проведенной операции.
  4. Точка продаж отправляет в Tiyn Business запрос на создание подписки, где указывает идентификатор платежного токена первого счета и данные подписки;
  5. Tiyn Business обрабатывает запрос и если подписка создана корректно, возвращает ответ, содержащий идентификатор подписки;
  6. В случае если наступил момент следующей оплаты счета Tiyn Business создает счет и проводит его аналогично первому платежу, но списание средств осуществляется уже без подтверждения клиентом;
  7. 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ДаНепустая строкаОписание ошибки

Отмена подписки#

DELETE
/subscriptions/{uuid}

Метод позволяет отменить активную подписку.

Пример запроса на отмену подписки#

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ДаОбъектДанные запроса

Получение баланса точки продаж#

GET
/balance

Пример запроса на получение данных#

Метод позволяет по ключу доступа получить баланс данной точки продаж. Если точка продаж работает с несколькими валютами, то баланс будет получен по каждой из валют.

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ДаНепустая строкаИдентификатор корреляции запроса

Создание выплаты#

POST
/payouts

Метод позволяет осуществлять вывод средств на банковскую карту. Вывод средств на банковскую карту возможен путем передачи в запросе реквизитов банковской карты или платежного токена карты (см. "Сохранение банковской карты").

Для активации возможности создавать выплаты необходимо связаться с менеджером 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ДаНепустая строкаИдентификатор корреляции запроса

Получение данных выплаты#

GET
/payouts/{uuid}

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

Пример запроса на получение данных#

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ДаНепустая строкаИдентификатор корреляции запроса

Подтверждение двухэтапной выплаты#

POST
/payouts/{uuid}/confirm

Метод позволяет подтверждать двухэтапную выплату. Подтверждение выполняется для выплаты в статусе 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ДаНепустая строкаИдентификатор корреляции запроса

Отклонение двухэтапной выплаты#

POST
/payouts/{uuid}/decline

Метод позволяет отклонять двухэтапную выплату. Отклонение выполняется для выплаты в статусе 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ДаНепустая строкаИдентификатор корреляции запроса

Сохранение банковской карты#

POST
/payout-cards

Метод позволяет сохранить реквизиты банковской карты и получить платежный токен, с помощью которого можно проводить выплаты.

Пример запроса на сохранение банковской карты#

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.

Сценарий оплаты с помощью платежной формы#

  1. Точка продаж отправляет в Tiyn Business запрос на создание счета.
  2. Если счет создан корректно, то в ответ на запрос Tiyn Business вернет uuid счета.
  3. Точка продаж инициализирует платежную форму с передачей необходимых параметров, а именно uuid счета и параметрами кастомизации.
  4. Tiyn.js создаёт защищённый iframe, загружаемый с PCI DSS совместимого CDN Tiyn.
  5. Плательщик заполняет банковские реквизиты и нажимает кнопку оплаты внутри iframe. Данные карты передаются напрямую в Tiyn Business.
  6. Tiyn Business обрабатывает платеж.
  7. После завершения обработки Tiyn Business отправляет событие CHECKOUT_SUBMIT_RESULT в iframe с результатом оплаты счета.
  8. Точка продаж получает событие CHECKOUT_SUBMIT_RESULT.
    • В случае успешной оплаты счета плательщик перенаправляется на страницу, указанную при создании счета в параметре successUrl;
    • В случае неуспешной оплаты происходит перенаправление на страницу, указанную при создании счета в параметре failUrl;
  9. Tiyn Business отправляет точке продаж уведомление об успешной/неуспешной оплате счета.
  10. Точка продаж возвращает ответ-подтверждение о проведенной операции.

Интеграция#

Подключение 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. Это позволяет полностью адаптировать форму под дизайн сайта точки продаж.

Платёжная форма Tiyn.js

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
СобытиеДанные в eventОписание
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
Номер карты (PAN)3dsПоддержка токенаРезультат
5555555555554477Да, v1НетУспешно
4111111111111111Да, v2НетУспешно
4311111111111119НетНетУспешно
4111111111111160НетНетОтклонен
4111111111111152ДаДаУспешно
5555555555554501НетДаУспешно
4111111111111137ДаДаОтклонен
5105105105105134НетДаОтклонен

Выплаты#

Тестирование — таблица 2
Номер карты (PAN)Результат
4111111111111111Успешно
5555555555555599Ожидание
4222222222222222Отклонена (Недостаточно средств)

Нужна помощь с интеграцией?

Ответы о ключах, Webhook и тестовой среде собраны в справке для бизнеса. Если вопрос остался — напишите в поддержку.