Версия – 1.0

Регистрация сайтов и приложений

Для подключения Yandex Pay на сайте необходимо выполнить следующие шаги:

Оставить заявку на подключение в Yandex
Получить от службы поддержки Yandex Yandex MerchantId.
Выполнить интеграцию с Yandex Pay на своем сайте. Подробная инструкция от Yandex. Используйте следующие параметры при взаимодействии с Yandex:
- gateway: cloudpayments
- gatewayMerchantId: publiсId из метода Получение publicId
- merchant.id: полученный от службы поддержки Yandex, для передачи информации данных Продавца
Реализовать необходимые сценарии выполнения платежей в CloudTips.
Провести интеграционное тестирование.
Получить от менеджеров Yandex merchant_id и доступ в продакшн.
Выполнить переход в боевое окружение.

Интеграция

Платежи через API CloudTips

Для выполнения оплаты через API, необходимо:

Передать в CloudTips токен, полученный на сайте с помощью Yandex Pay Web SDK в параметре cardCryptogramPacket метода Авторизация платежа.
Yandex Pay формирует токен в Base64. Токен необходимо декодировать и передавать в API.

Пример:

"CardCryptogramPacket": “{\“type\“:\“Yandex\“,\“signedMessage\“:\“{\\\“encryptedMessage\\\“:\\\“aM8CPnekFJZlzzCBIAhPXCBBkyG0OZI+VtNLd10+mmtmyEEYVzQripGPoG2QkDd9zhzV0YOIJFMQoMmiVnR+f/Kbv79gOKdJTrt8mILb7zLvDR/MD1ULwO4l1Ldp97ThgQiJOAamBxbELGkImCIr4ZGQ7XysXENO2PVpxau6Wn67p/GfmZcH2e2fEbGXzT4cLUMVi6d5EO0OkWbJKaIL5wS5Y7/ZHvvcONVT8ynJVrZ4x5i+410MhNCeVp+XKOvHy4G+OLtr2BocGOvSj+siJJMbGLnb1rSmzx/zQCzQatXNGx6vffDbDIYC73+X54Fpe9ZA8YqCdx7JZCsKET/IyBW0lGN3QF/AU/QwoaxS6+uDmbbLGNiUTAv834K1My/sPqXreD93Xt5jUs1NCHAP/3BEyzzjmzzWhbKZ6tWgUWu2fD/aD/eceBZedQV1zfTCpjUfNLyQFDjJeakTmSp7gaCH9PMIaXsTVCi+rPha9++Mg2kyJJW1UO3Vf1znKGGvWil7tZJTHujO1F611qKBDcLNfxXM1EHsml30vCnhfmczIobDC/7w32WWy50xLQN78kC1haDtd2xoDvF7\\\“,\\\“tag\\\“:\\\“RkOZGONlcd13E8BLBnUKWTHjRMBrZFYAdICeZJvucd0=\\\“,\\\“ephemeralPublicKey\\\“:\\\“BLo6EnK+gcw6nAnuaNjvt7F9+9fb0y5lCPmFsRtfYpuHwSkdxvTRZyZHPYW3XNf6gK1ACfPBWQ96pVYGlul5G4I=\\\“}\“,\“protocolVersion\“:\“ECv2\“,\“signature\“:\“MEUCIQC0Hsrv7G1Neg1pVcvmL0AQWWMGI+H/++t+bjrdEr75jQIgXqywfhx+nVJSU/ExsdWRv8I2t1wBXI89up1cfNi3aiM=\“,\“intermediateSigningKey\“:{\“signedKey\“:\“{\\\“keyValue\\\“:\\\“MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqYNePt6BPgCv5JxfO9dF2vrSqmnp4Mhe/vF+XO+Devbs6/KVpVVoTD8LLcAo4TZh6IuODVnVpHrTObhg3HJVJA==\\\“,\\\“keyExpiration\\\“:\\\“1764950892000\\\“}\“,\“signatures\“:[\“MEQCIDRslMW7wNZbpqVw/dD7hDQh30hGhqfjfWTBvc7zAYJSAiAGAvjAslA2AxwdAEuOfacFr6DaE5yiiUuUtM6DUreZYg==\“]}}”

Авторизация

Для начала работы с 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
yandexPayEnabled	Boolean	Да	Оплата по yandex pay доступна, значения true и false
userAgreementText	String	Да	Текст пользовательского соглашения
userAgreementUrl	String	Да	Ссылка на пользовательское соглашение
hideReCaptchaHint	Boolean	Да	Скрывать иконку капчи
excludeCharityBanner	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,
    "yandexPayEnabled": true,
    "userAgreementText": "string",
    "userAgreementUrl": "string",
    "hideReCaptchaHint": true,
    "excludeCharityBanner": 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"
    ]
  }
}

Получение publicId

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

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

Тип: POST

Запрос:

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

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

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

{
  "layoutId": "string"
}

Ответ:

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

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

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

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

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

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

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

Тип: POST

Запрос:

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

Наименование	Тип	Обязательность	Описание
cardholderName	String	Да	Уникальный идентификатор страницы оплаты получателя
cardCryptogramPacket	String	Да	Криптограмма карты
amount	Integer	Да	Сумма платежа
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	Нет	Город платящего
routeId	String	Нет	Не используется
captchaVerificationToken	String	Нет	Не используется
rating		Нет	Компоненты рейтинга
score	Integer	Нет	Оценка, значение от 0 до 5
selectedComponents	Array of string	Нет	Выбранные компоненты полученные при запросе данных Страницы оплаты, передается список id выбранных компонентов

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

{
  "cardholderName": "string",
  "cardCryptogramPacket": "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",
  "routeId": "string",
  "captchaVerificationToken": "string",
  "rating": {
    "score": 0,
    "selectedComponents": [
      "string"
    ]
  }
}

Ответ:

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

Наименование	Тип	Обязательность	Описание
transactionId	String	Да	Уникальный идентификатор оплаты
md	String	Да
paReq	String	Да
acsUrl	String	Да	URL банка для прохождения 3DS
message	String	Да	Текстовый статус платежа
statusCode	String	Да	Статус код платежа
cardToken	String	Да	Токен карты платящего
partnerRedirectUrl	String	Да	URL редиректа на страницу партнера
cardIssuerBankCountry	String	Да	Страна банка эмитента карты
cardLastFour	String	Да	Последние 4 цифры карты
cardExpDate	String	Да	Дата окончания действия карты
issuerCode	String	Да	Код эмитента
succeed	Boolean	Да	Стату запроса, значение true и false
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

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

{
  "data": {
    "transactionId": 0,
    "md": "string",
    "paReq": "string",
    "acsUrl": "string",
    "message": "string",
    "statusCode": "string",
    "cardToken": "string",
    "partnerRedirectUrl": "string",
    "cardIssuerBankCountry": "string",
    "cardLastFour": "string",
    "cardExpDate": "string",
    "issuerCode": "string"
  },
  "succeed": true,
  "statusCode": 0,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}

Обработка 3-D Secure

Описание: Если при Авторизации платежа вернулся статус Success, то оплата прошла успешна и проходить 3DS не требуется.

Если при Авторизации платежа вернулся статус Need3DS, то необходимо перенаправить получателя на AcsUrl банка для прохождения 3ds.

Для проведения 3-D Secure аутентификации нужно отправить плательщика на адрес, указанный в параметре AcsUrl из метода Авторизация платежа с передачей следующих параметров:

MD — параметр TransactionId из ответа сервера;
PaReq — одноименный параметр из ответа сервера;
TermUrl — адрес на вашем сайте для возврата плательщика после аутентификации.

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

Описания: После возвращения платящего на ваш сайт необходимо завершить оплату.

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

Тип: POST

Запрос:

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

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

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

{
  "paRes": "string",
  "md": "string"
}

Ответ:

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

Наименование	Тип	Обязательность	Описание
transactionId	String	Да	Уникальный идентификатор оплаты
md	String	Да
paReq	String	Да
acsUrl	String	Да	URL банка для прохождения 3DS
message	String	Да	Текстовый статус платежа
statusCode	String	Да	Статус код платежа
cardToken	String	Да	Токен карты платящего
partnerRedirectUrl	String	Да	URL редиректа на страницу партнера
cardIssuerBankCountry	String	Да	Страна банка эмитента карты
cardLastFour	String	Да	Последние 4 цифры карты
cardExpDate	String	Да	Дата окончания действия карты
issuerCode	String	Да	Код эмитента
succeed	Boolean	Да	Стату запроса, значение true и false
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

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

{
  "data": {
    "transactionId": 0,
    "md": "string",
    "paReq": "string",
    "acsUrl": "string",
    "message": "string",
    "statusCode": "string",
    "cardToken": "string",
    "partnerRedirectUrl": "string",
    "cardIssuerBankCountry": "string",
    "cardLastFour": "string",
    "cardExpDate": "string",
    "issuerCode": "string"
  },
  "succeed": true,
  "statusCode": 0,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}

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

При использовании Yandex Pay необходимо соблюдать:

CloudTips API

Оплата Yandex Pay

Analytics

Регистрация сайтов и приложений

Интеграция

Платежи через API CloudTips

Авторизация

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

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

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

Получение publicId

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

Обработка 3-D Secure

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

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

Оплата Yandex Pay

Регистрация сайтов и приложений

Интеграция

Платежи через API CloudTips

Авторизация

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

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

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

Получение publicId​

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

Обработка 3-D Secure

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

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

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

Получение publicId