Версия – 1.0

Оплата с помощью Tinkoff Pay доступна всем клиентам банка Tinkoff, у которых установлено мобильное приложение.

Принцип работы Tinkoff Pay

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

В десктопной версии сайта оплата производится по QR коду с подтверждением в мобильном банке.

Интеграция

Авторизация

Для начала работы с API вам необходимо авторизоваться в системе, для этого необходимо получить логин и пароль у вашего менеджера.

POST https://identity.cloudtips.ru/connect/token

Content-Type application/x-www-form-urlencoded
Grant_type=password
Client_id=Partner
UserName=partner@email.com
Password=partner_password

В ответе придет access_token, refresh_token и expires_in.

access_token необходимо отправлять при каждом запросе в https://api.cloudtips.ru/ в Authorization Bearer хедере.

expires_in - это время жизни access_token в секундах, после того как время жизни закончилось, необходимо использовать refresh_token для получения новой пары access_token/refresh_token

Для получения нового access_token необходимо использовать refresh_token полученный при авторизации.
POST https://identity.cloudtips.ru/connect/token

Content-Type application/x-www-form-urlencoded
Grant_type=refresh_token
Client_id=Partner
refresh_token=refreshToken

Оплата комиссии за счет отправителя

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

Вам обязательно необходимо отобразить эту информацию на вашей форме оплаты и у платящего должна быть возможность отказаться. Для получения суммы чаевых с учетом комиссии с платящего необходимо использовать Расчет комиссии с платящего.

Если платящий согласен оплатить комиссию за получателя, необходимо в Авторизацию платежа передать параметр “feeFromPayer”: true, в противном случае false.

Пример реализации у нас:

Расчет комиссии с платящего

Адрес: https://api.cloudtips.ru/api/payment/fee

Тип: GET

Запрос:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
amount	Integer	Да	Сумма чаевых
layoutId	String	Да	Уникальный идентификатор страницы оплаты получателя

Пример запроса:

{
  "amount": 0;
  "layoutId": "string"
}

Ответ:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
amount	Integer	Да	Сумма чаевых
feeAmount	Integer	Да	Комиссия с платящего в %
amountFromPayer	Integer	Да	Сумма с платящего с учетом комиссии с платящего
succeed	Boolean	Да	Стату запроса, значение true и false
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

{
  "data": {
    "amount": 0,
    "feeAmount": 0,
    "amountFromPayer": 0
  },
  "succeed": true,
  "statusCode": 0,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}

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

Описание: Получение информации о платежной странице получателя

Адрес: https://api.cloudtips.ru/api/paymentpages/{layoutId}

Тип: GET

Запрос:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
layoutId	String	Да	Уникальный идентификатор страницы оплаты получателя

Пример запроса:

-

Ответ:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
url	String	Да	Ссылка на страницу оплаты
title	String	Да	Название
backgroundUrl	String	Да	Ссылка на обложку
avatarUrl	String	Да	Ссылка на аватарку получателя
logoUrl	String	Да	Ссылка на логотип
nameText	String	Да	Имя получателя
backgroundColor	String	Да	Цвет бэкграунда страницы оплаты
linksColor	String	Да	Цвет ссылок
buttonsColor	String	Да	Цвет кнопок
applePayEnabled	Boolean	Да	Оплата по apple pay доступна, значения true и false
googlePayEnabled	Boolean	Да	Оплата по Google Pay доступна, значения true и false
tinkoffPayEnabled	Boolean	Да	Оплата по Tinkoff Pay доступна, значения true и false
userAgreementText	String	Да	Текст пользовательского соглашения
userAgreementUrl	String	Да	Ссылка на пользовательское соглашение
hideReCaptchaHint	Boolean	Да	Скрывать иконку капчи
paymentMessage	String	Да	Текст на странице оплаты
successMessage	String	Да	Текст на странице успешной оплаты
failMessage	String	Да	Не используется
amount		Да	Блок для управления полем сумма
amountPresetSettings		Да	Блок с предустановленными суммами
enabled	Boolean	Да	Включен, значения true и false
amounts	Array of integer	Да	Варианты сумм
constraints		Да	Не используется
range		Да	Ограничение на сумму платежа
minimal	Integer	Да	минимальная сумма платежа
maximal	Integer	Да	максимальная сумма платежа
fixed	Integer	Да	фиксированная сумма платежа
target		Да	Блок цель
startDate	Date	Да	Дата начала сбора денег
finishDate	Date	Да	Дата окончания сбора денег
targetAmount	Integer	Да	Сумма цели
currentAmount	Integer	Да	Текущая сумма
rating		Да	Блок рейтинг
enabled	Boolean	Да	Включен, значения true и false
components		Да	Компоненты рейтинга
id	String	Да	Уникальный идентификатор компоненты
title	String	Да	Название компоненты
imageUrl	String	Да	Ссылка на изображение
availableFields		Да	Блок полей для заполнения
comment		Да	Комментарий
title	String	Да	Название поля
enabled	Boolean	Да	Включен, значения true и false
required	Boolean	Да	Обязательно, значения true и false
email		Да	Почта платящего
title	String	Да	Название поля
enabled	Boolean	Да	Включен, значения true и false
required	Boolean	Да	Обязательно, значения true и false
name		Да	Имя платящего
title	String	Да	Название поля
enabled	Boolean	Да	Включен, значения true и false
required	Boolean	Да	Обязательно, значения true и false
phoneNumber		Да	Телефон платящего
title	String	Да	Название поля
enabled	Boolean	Да	Включен, значения true и false
required	Boolean	Да	Обязательно, значения true и false
payerCity		Да	Город платящего
title	String	Да	Название поля
enabled	Boolean	Да	Включен, значения true и false
required	Boolean	Да	Обязательно, значения true и false
afterPaymentActions		Да	Действие после оплаты
emailSending	Boolean	Да	Отправить email, значения true и false. Если выбран true, то поле email обязательно для заполнения
payerFee		Да	Блок комиссия за счет платящего
enabled	Boolean	Да	Включен, значения true и false
initialState	String	Да	Положение по умолчанию, значения: Disabled - отключена, Enabled - включена
buttonPosition	String	Да	Не используется
feedback		Да	Не используется
succeed	Boolean	Да	Стату запроса, значение true и false
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

{
  "data": {
    "url": "string",
    "title": "string",
    "backgroundUrl": "string",
    "avatarUrl": "string",
    "logoUrl": "string",
    "nameText": "string",
    "backgroundColor": "string",
    "linksColor": "string",
    "buttonsColor": "string",
    "applePayEnabled": true,
    "googlePayEnabled": true,
    "tinkoffPayEnabled": true,
    "userAgreementText": "string",
    "userAgreementUrl": "string",
    "hideReCaptchaHint": true,
    "paymentMessage": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "successMessage": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "failMessage": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "amount": {
      "amountPresetSettings": {
        "enabled": true,
        "amounts": [
          0
        ]
      },
      "constraints": [
        {
          "type": "string",
          "currency": "string",
          "value": 0
        }
      ]
    },
    "target": {
      "startDate": "2021-08-24T10:06:46.874Z",
      "finishDate": "2021-08-24T10:06:46.874Z",
      "targetAmount": 0,
      "currentAmount": 0
    },
    "rating": {
      "enabled": true,
      "components": [
        {
          "id": "string",
          "title": "string",
          "imageUrl": "string"
        }
      ]
    },
    "availableFields": {
      "comment": {
        "title": "string",
        "enabled": true,
        "required": true
      },
      "email": {
        "title": "string",
        "enabled": true,
        "required": true
      },
      "name": {
        "title": "string",
        "enabled": true,
        "required": true
      },
      "phoneNumber": {
        "title": "string",
        "enabled": true,
        "required": true
      },
      "payerCity": {
        "title": "string",
        "enabled": true,
        "required": true
      }
    },
    "afterPaymentActions": {
      "emailSending": true
    },
    "payerFee": {
      "enabled": true,
      "initialState": "string",
      "buttonPosition": "string"
    },
    "feedback": {
      "enabled": true,
      "rating": {
        "enabled": true,
        "components": [
          {
            "id": "string",
            "title": "string",
            "imageUrl": "string"
          }
        ]
      },
      "availableFields": {
        "comment": {
          "title": "string",
          "enabled": true,
          "required": true
        },
        "email": {
          "title": "string",
          "enabled": true,
          "required": true
        },
        "name": {
          "title": "string",
          "enabled": true,
          "required": true
        },
        "phoneNumber": {
          "title": "string",
          "enabled": true,
          "required": true
        },
        "payerCity": {
          "title": "string",
          "enabled": true,
          "required": true
        }
      }
    }
  },
  "succeed": true,
  "statusCode": 0,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}

Авторизация платежа

Описание: Позволяет начать процедуру оплаты чаевых

Если платящий согласен оплатить комиссию за получателя и передается параметр “feeFromPayer”: true, то сумма amount должна учитывать рассчитанную комиссию

Адрес: https://api.cloudtips.ru/api/payment/tpay

Тип: POST

Запрос:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
amount	Integer	Да	Сумма платежа Число с плавающей запятой, округление до 2 знаков после запятой
feeFromPayer	Boolean	Да	Комиссия с платящего, значения true и false
currency	String	Да	Валюта платежа, константа RUB
name	String	Нет	Имя платящего
comment	String	Нет	Комментарий платящего
layoutId	String	Да	Уникальный идентификатор страницы оплаты получателя
ipSource	String	Да	Ip адрес плательщика
invoiceId	String	Нет	Внешний идентификатор партнера, например внутренний номер заказа
payerEmail	String	Нет	email платящего
receiverSubscriptionSettingId	String	Нет	Не используется
payerPhoneNumber	String	Нет	Телефон платящего
payerCity	String	Нет	Город платящего
rating		Нет	Компоненты рейтинга
score	Integer	Нет	Оценка, значение от 0 до 5
selectedComponents	Array of string	Нет	Выбранные компоненты полученные при запросе данных Страницы оплаты, передается список id выбранных компонентов
externalId	String	Нет	Внешний идентификатор получателя
routeId	String	Нет	Не используется
successRedirectUrl	String	Нет	Url для редиректа при успешной оплате
failRedirectUrl	String	Нет	Url для редиректа при НЕуспешной оплате
Device		Да	Данные устройства
Type	enum	Да	Тип платформы MobileApp = 1, MobileWeb = 2, DesktopWeb = 3
Os	String	Да	Операционная система
Webview	Boolean	Да	Наличие WebView, значения true и false
Browser	String	Да	Используемое имя браузера, без версии

Пример запроса:

{
  "amount": 0,
  "feeFromPayer": true,
  "currency": "string",
  "name": "string",
  "comment": "string",
  "layoutId": "string",
  "ipSource" : "string",
  "invoiceId": "string",
  "payerEmail": "user@example.com",
  "receiverSubscriptionSettingId": "string",
  "payerPhoneNumber": "string",
  "payerCity": "string",
  "rating": {
    "score": 0,
    "selectedComponents": [
      "string"
    ]
  },
  "externalId": "string",
  "routeId": "string",
  "Device" : 
   { "Type" : 0, //enum MobileApp = 1,MobileWeb = 2,DesktopWeb = 3
   "Os" : "string",
   "Webview" : bool,
   "Browser" : "string"
   }
   "successRedirectUrl": "string",
   "failRedirectUrl": "string"
  }
}

Ответ:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
succeed	Boolean	Да	Стату запроса, значение true и false
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса
transactionId	Long	Да	Уникальный идентификатор оплаты
universalLinkUrl	String	Да	Url для редиректа в мобильное приложение
qrUrl	String	Да	Url для открытия pop up c qr кодом для оплаты

Пример ответа:

{
  "succeed": true,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  },
  "data": {
    "transactionId": 0,
    "universalLinkUrl" : "string",
    "qrUrl" : "string"
  }
}

Опрос статуса транзакции при оплате по Tinkoff Pay

Описание: Позволяет получить статус транзакции для последующих действий.

Алгоритм опроса статуса:

Опрос статуса необходимо проводить раз в минуту, максимальное число попыток – 5.

При открытии вызываем метод GET api/payment/tpay/status?transactionId={transactionId} (выполняется ~ 1 минуту, нужно учесть, чтобы не было таймаутов) и ждем результат до тех пор, пока не придет Status=Wait

В зависимости от значения поля Status, делаем следующие действия:

Status=Wait. Статус обозначает, что транзакция либо была не оплачена, либо находится в обработке. После получения этого статуса отправляем повторный запрос (5 раз).

В случае превышения количества попыток(5), текущий QR код становится недоступен для оплаты, модальное окно закрывается. Страница оплаты со всеми введенными данными остается и при повторном запросе оплаты по QR коду описанный сценарий повторяется.

2. Status=Success. Редиректим на страницу успешной оплаты

3. Status=Failed. Редиректим на страницу неуспешной оплаты

Адрес: https://api/payment/tpay/status?transactionId={transactionId}

Тип: GET

Запрос:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
transactionId	Long	Да	Уникальный идентификатор оплаты

Пример запроса:

{
  "transactionId": 0,
}

Ответ:

Наименование	Тип	Обязательность	Описание

Наименование

Тип

Обязательность

Описание

transactionId

Long

Да

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

status

enum

Да

Статус платежа:

Status=Wait. Статус обозначает, что транзакция либо была не оплачена, либо находится в обработке. После получения этого статуса отправляем повторный запрос (5 раз). Если по истечению всех попыток, статус остается все тот же, то закрываем QR код и оставляем страницу со всеми введенными параметрами.
Status=Success. Редирект на страницу успешной оплаты
Status=Failed. Редирект на страницу неуспешной оплаты

Пример ответ:

{
  "transactionId": 0,
  "status" : 0, //enum Wait = 1,Success = 2,Failed = 3
}

Завершение оплаты

Завершение оплаты происходит при получении одного из финальных статусов.

Финальные статусы:

Success. Редирект на страницу успешной оплаты
Failed. Редирект на страницу неуспешной оплаты

Условия использования Tinkoff Pay

Вы можете применять технологию Tinkoff Pay с системой CloudPayments на сайтах и в мобильных приложениях при соблюдении следующий требований:

Правила оформления бренда Tinkoff Pay

CloudTips API

Оплата Tinkoff Pay

Analytics

Принцип работы Tinkoff Pay

Интеграция

Авторизация

Оплата комиссии за счет отправителя

Расчет комиссии с платящего

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

Авторизация платежа

Опрос статуса транзакции при оплате по Tinkoff Pay

Алгоритм опроса статуса:

Завершение оплаты

Условия использования Tinkoff Pay

Related content