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

Регистрация и создание магазина через Tiyn Business

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

1. Зарегистрировать личный кабинет Tiyn Business по кнопке Подключиться на странице tiyn.io;
2. В личном кабинете создать магазин в разделе Магазины, перейти в настройки магазина и заполнить раздел Общие настройки;
3. Перейти в раздел настроек магазина Технические настройки и сгенерировать новый секретный ключ (secretPhrase) для формирования подписи;
4. Если требуется передача уведомлений об изменении статусов счета в одну из ваших систем (Callback), заполнить поле ResultURL адресом для получения уведомлений;
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#

Пример на языке PHP

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

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

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

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

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

1. Получить список доступных методов оплаты с помощью GET /merchant-api/api/v2/payment-methods;
2. Выбрать из ответа один или несколько методов, которые должны быть доступны плательщику;
3. Передать выбранные значения без изменений в параметре preferredPaymentMethods при создании счета.

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

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

Для запроса требуется только ключ доступа магазина. Заголовок x-sign передавать не требуется.

curl https://business.tiyn.io/merchant-api/api/v2/payment-methods \
  -X GET \
  -H 'x-api-key: <Ключ доступа>'

Пример успешного ответа на запрос на получение методов оплаты

{
  "success": true,
  "data": {
    "paymentMethods": [
      "BankCard",
      "google_pay",
      "sbp"
    ]
  }
}

Значения BankCard, google_pay и sbp приведены в качестве примера. Фактический состав массива определяется настройками магазина. Если для магазина нет доступных методов оплаты, API вернет пустой массив.

Описание параметров успешного ответа на запрос на получение методов оплаты

Описание параметров объекта data

Пример ответа при ошибке авторизации

{
  "success": false,
  "error": {
    "code": "-1",
    "message": "Unauthorized",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа при ошибке авторизации

Описание параметров объекта error

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

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

Чтобы ограничить выбор плательщика, передайте в preferredPaymentMethods один или несколько значений из актуального ответа GET /merchant-api/api/v2/payment-methods. На странице оплаты будут доступны только указанные методы.

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

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"
    ]
}'

Описание параметров запроса на создание счета

Пример успешного ответа на запрос на создание счета

{
  "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"
  }
}

Описание параметров успешного ответа при создании счета

Описание параметров объекта data

Пример ответа с ошибкой на запрос на создание счета

{
  "success": false,
  "error": {
    "code": "1",
    "message": "Ошибка создания счета",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой создания счета

Описание параметров объекта error

Отмена счета

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

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

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 - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса на отмену счета

Пример успешного ответа на запрос на отмену счета

{
  "success": true,
  "data": {
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
  }
}

Описание параметров успешного ответа на запрос на отмену счета

Описание параметров объекта data

Пример ответа с ошибкой на запрос на отмену счета

{
  "success": false,
  "error": {
    "code": "3",
    "message": "error",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой на запрос на отмену счета

Описание параметров объекта error

Возврат

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

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

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 - идентификатор счета, полученный в успешном ответе при создании счета.

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

Пример успешного ответа на запрос на возврат

{
  "success": true,
  "data": {
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
  }
}

Описание параметров успешного ответа на запрос на возврат

Описание параметров объекта data

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

{
  "success": false,
  "error": {
    "code": "6",
    "message": "error",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой на запрос на возврат

Описание параметров объекта error

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

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

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

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 - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса на получение данных

Пример успешного ответа на запрос на получение данных

{
  "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"
      }
    }
  ]
}

Описание параметров успешного ответа на запрос на получение данных

Описание параметров объекта status

Описание параметров объекта payments

Описание параметров объекта details

Описание параметров объекта status

Пример ответа с ошибкой на запрос на получение данных

{
  "success": false,
  "error": {
    "code": "5",
    "message": "error",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой на запрос на получение данных

Описание параметров объекта error

Оплата счета через 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 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 - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса оплаты счета

Описание параметров details для способа оплаты BankCard по реквизитам банковской карты

Описание параметров details для способа оплаты BankCard по токену

Пример успешного ответа на запрос оплаты счета, если не требуется перенаправление пользователя

{
  "success": true,
  "data": {
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
  }
}

Описание параметров успешного ответа на запрос оплаты счета

Описание параметров объекта data

Пример успешного ответа на запрос оплаты счета, если требуется перенаправление пользователя

{
  "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.

Описание параметров успешного ответа на запрос оплаты счета

Описание параметров объекта data

Описание параметров объекта redirect

Пример ответа с ошибкой на запрос оплаты счета

{
  "success": false,
  "error": {
    "code": "5",
    "message": "error",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой на запрос оплаты счета

Описание параметров объекта error

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

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

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

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

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

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), после оплаты счета.

Описание параметров запроса на создание подписки

Пример успешного ответа на запрос на создание подписки

{
    "success": true,
    "data": {
        "uuid": "5c91a9f9-984b-4ed5-818b-8136fdd551e2",
        "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a"
    }
}

Описание параметров успешного ответа на запрос на создания подписки

Описание параметров объекта data

Пример ответа с ошибкой на запрос на создание подписки

{
    "success": false,
    "error": {
        "code": "7",
        "message": "Ошибка создания подписки"
    }
}

Описание параметров ответа с ошибкой на запрос на создание подписки

Описание параметров объекта error

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

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

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

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 - идентификатор подписки, полученный в ответе на ее создание.

Пример успешного ответа на запрос на отмены подписки

{
    "success": true,
    "data": null
}

Описание параметров успешного ответа на запрос на отмены подписки

Получение баланса магазина

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

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

curl https://business.tiyn.io/merchant-api/api/v2/balance \
  -X GET \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'Content-Type: application/json; charset=utf-8' \

Пример успешного ответа на запрос на получение данных

{
  "success": true,
  "data": [
    {
      "currency": "KZT",
      "balance": 890.12
    }
  ]
}

Описание параметров успешного ответа на запрос на получение данных

Описание параметров элемента коллекции data

Пример ответа с ошибкой на запрос на получение данных

{
  "success": false,
  "error": {
    "code": "8",
    "message": "error",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой на запрос на получение данных

Описание параметров объекта error

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

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

Для активации возможности создавать выплаты необходимо связаться с менеджером Tiyn Business.

Пример запроса на создание выплаты

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"
}'

Описание параметров запроса на создание выплаты

Описание параметров объекта destination для способа вывода на банковскую карту по реквизитам

{
    ...
    "destination": {
        "pan": "41233543544386", 
        "cardholder": "Ivan Pupkin"
    },
    "payoutMethod": "BankCard"
}

Описание параметров объекта destination для способа вывода на банковскую карту по платежному токену

{
    ...
    "destination": {
        "payoutToken": "837c06b4-b791-4f2c-89b1-a45f78cb1568"
    },
    "payoutMethod": "BankCard"
}

Пример успешного ответа на запрос на создание выплаты

{
  "success": true,
  "data": {
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827"
  }
}

Описание параметров успешного ответа при создании выплаты

Описание параметров объекта data

Пример ответа с ошибкой на запрос на создание выплаты

{
  "success": false,
  "error": {
    "code": "9",
    "message": "Ошибка создания выплаты",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой создания выплаты

Описание параметров объекта error

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

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

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

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 - идентификатор выплаты, полученный в успешном ответе при создании выплаты.

Описание параметров запроса на получение данных

Пример успешного ответа на запрос на получение данных

{
  "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": "Получено событие о удачном проведении транзакции на выплату"
    }
  }
}

Описание параметров успешного ответа на запрос на получение данных

Описание параметров объекта data

Описание параметров объекта commission

Описание параметров объекта status

Описание параметров объекта destination

Пример ответа с ошибкой на запрос на получение данных

{
  "success": false,
  "error": {
    "code": "10",
    "message": "error",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой на запрос на получение данных

Описание параметров объекта error

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

Метод позволяет подтверждать двухэтапную выплату. Подтверждение выполняется для выплаты в статусе PayoutWaitingConfirmation. Для активации возможности создавать двухэтапные выплаты необходимо связаться с менеджером Tiyn Business.

Пример запроса на подтверждение выплаты

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 - идентификатор выплаты, полученный в успешном ответе при создании выплаты.

Описание параметров запроса на подтверждение выплаты

Пример успешного ответа на запрос на подтверждения выплаты

{
  "success": true,
  "data": {
    "uuid": "8904c0ef-7667-4ec2-b63a-57c50faf0248"
  }

Описание параметров успешного ответа при создании выплаты

Описание параметров объекта data

Пример ответа с ошибкой на запрос на подтверждения выплаты

{
  "success": false,
  "error": {
    "code": "13",
    "message": "Ошибка подтверждения выплаты",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой подтверждения выплаты

Описание параметров объекта error

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

Метод позволяет отклонять двухэтапную выплату. Отклонение выполняется для выплаты в статусе PayoutWaitingConfirmation. Для активации возможности создавать двухэтапные выплаты необходимо связаться с менеджером Tiyn Business.

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

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 - идентификатор выплаты, полученный в успешном ответе при создании выплаты.

Описание параметров запроса на отклонение выплаты

Пример успешного ответа на запрос на отклонение выплаты

{
  "success": true,
  "data": {
    "uuid": "8904c0ef-7667-4ec2-b63a-57c50faf0248"
  }

Описание параметров успешного ответа при отклонении выплаты

Описание параметров объекта data

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

{
  "success": false,
  "error": {
    "code": "14",
    "message": "Ошибка отклонения выплаты",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой отклонения выплаты

Описание параметров объекта error

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

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

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

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"
}'

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

Пример успешного ответа на запрос сохранения банковской карты

{
  "success": true,
  "data": {
    "payoutToken": "c6eae048-072c-44cb-aaa8-3822989cfb9c"
  }

Описание параметров успешного ответа при сохранении банковской карты

Описание параметров объекта data

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

{
  "success": false,
  "error": {
    "code": "14",
    "message": "Ошибка сохранения банковкой карты",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой отклонения выплаты

Описание параметров объекта error

Платежная форма 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)

Для подключения необходимо добавить на свою страницу следующий код:

<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

Использование в коде:

   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

Использование компонента:

import { loadSDK } from '@tiynjs/sdk';
import { Checkout } from '@tiynjs/react';

const sdk = loadSDK();

function PaymentPage() {
  return (
     console.log(result)}
    />
  );
}

Кастомизация формы

Есть возможность управлять внешним видом формы, передавая объект theme при создании экземпляра createCheckout. Это позволяет полностью адаптировать форму под дизайн сайта магазина.

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

Описание параметров объекта colors

Описание параметров объекта typography

Описание параметров объекта borders

Описание параметров объекта spacing

API Tiyn.js

Методы SDK

loadSDK(options?)

Загружает SDK с CDN.

Возвращает: объект SDK с методом createCheckout.

createCheckout(options)

Создаёт экземпляр платёжной формы.

Возвращает: экземпляр Checkout с методами для управления формой.

Методы экземпляра checkout

После создания экземпляра через createCheckout доступны следующие методы:

События

События, на которые можно подписаться, используя метод on():

Перечень возможных значений статусов счета

Перечень возможных значений статусов платежа

Перечень возможных значений статусов выплаты

Оповещение об изменении статуса счета

Оповещение об изменении статуса (Callback) происходит путем отправки POST-запроса по адресу, указанному в настройках магазина (раздел Технические настройки , параметр Result url)

Если на оповещение получен невалидный ответ/валидный ответ с ошибкой, или же ответ не получен, система отправляет повторное оповещение позднее. Оповещение отправляется повторно конечное число раз.

Пример оповещения от Tiyn Business

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

Описание параметров объекта status

Описание параметров объекта payments

Описание параметров объекта details

Описание параметров объекта status

Пример ожидаемого успешного ответа от системы мерчанта на оповещение от Tiyn Business

{
  "success": true,
  "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Пример ожидаемого ответа с ошибкой от системы мерчанта на оповещение от Tiyn Business

{
  "success": false,
  "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Описание параметров ожидаемых ответов от системы мерчанта на оповещение от Tiyn Business

Оповещение об изменении статуса выплаты

Оповещение об изменении статуса (Callback) происходит путем отправки POST-запроса по адресу, указанному в настройках магазина (раздел Технические настройки , параметр Payout Result URL)

Если на оповещение получен невалидный ответ/валидный ответ с ошибкой, или же ответ не получен, система отправляет повторное оповещение позднее. Оповещение отправляется повторно конечное число раз.

Пример оповещения от Tiyn Business

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

Описание параметров объекта commission

Описание параметров объекта status

Описание параметров объекта destination для способа вывода на банковскую карту

Пример ожидаемого успешного ответа от системы мерчанта на оповещение от Tiyn Business

{
  "success": true,
  "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Пример ожидаемого ответа с ошибкой от системы мерчанта на оповещение от Tiyn Business

{
  "success": false,
  "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Описание параметров ожидаемых ответов от системы мерчанта на оповещение от Tiyn Business

Описание кодов ошибок

Тестирование

Тестовые карты для проведения платежей и осуществления выплат (для тестовых магазинов Tiyn Business)

Платежи

Авторизационные данные:

• expiration date = 12/30;
• сvc/cvv2 = 123;
• 3ds=123456.

Выплаты