Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 10 Next »

Версия – 1.0

С помощью Системы быстрых платежей от Центробанка можно перевести деньги клиенту другого банка по номеру телефона.

Принцип работы оплаты через СБП

Если покупатель производит оплату на сайте с мобильного устройства, используя способ оплаты - СБП, то ему необходимо будет выбрать банк для подтверждения оплаты.

В мобильном банке ему будет предложено выбрать сохраненную карту из его аккаунта и подтвердить оплату.

В десктопной версии сайта оплата производится по 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

sbpPayEnabled

Boolean

Да

Оплата по СБП доступна, значения 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,
    "sbpPayEnabled": 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/sbp

Тип: POST

Запрос:

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

Тип

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

Описание

amount

Integer

Да

Сумма платежа

Число с плавающей запятой, округление до 2 знаков после запятой

currency

String

Да

Валюта платежа, константа RUB

feeFromPayer

Boolean

Да

Комиссия с платящего, значения true и false

name

String

Нет

Имя платящего

comment

String

Нет

Комментарий платящего

layoutId

String

Да

Уникальный идентификатор страницы оплаты получателя

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

Нет

Не используется

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

Ответ:

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

Тип

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

Описание

succeed

Boolean

Да

Стату запроса, значение true и false

errors

Array of string

Да

Возвращатеся список ошибок, относящихся целиком к запросу

validationErrors

Array of string

Да

Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

transactionId

Long

Да

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

universalLinkUrl

String

Да

Url для редиректа в мобильное приложение

qrImage

String

Да

Картинка с qr кодом для оплаты, возвращается в формате Base64

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

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

Получение списка банков, доступных для оплаты

В мобильной версии СБП необходима поддержка выбора банка для проведения оплаты. Для получения списка банков, необходимо обращаться по эндпойнту https://qr.nspk.ru/proxyapp/c2bmembers.json, в нем возвращается массив банков доступных для оплаты. Описание возвращаемых полей:

Поле

Тип

Описание

bankName

string

Имя банка

logoURL

string

Логотип банка

schema

string

Deeplink выбранного приложения

package_name

string

имя пакета приложения

webClientUrl

string

url веб-клиента

isWebClientActive

bool

Есть ли веб версия приложения

Для формирования ссылки после выбора банка, необходимо идти по следующему алгоритму:

в ссылке universalLinkUrl, полученной по методу https://api.cloudtips.ru/api/payment/sbp, необходимо выполнить замену строки https на значение schema выбранного банка и произвести редирект в мобильное приложение банка. Если редирект был неуспешен и переменная выбранного банка isWebClientActive в значении true, то необходимо для universalLinkUrl выполнить замену строки https://qr.nspk.ru на значение webClientUrl выбранного банка.

Опрос статуса транзакции при оплате по QR коду

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

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

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

Тип: GET

Запрос:

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

Тип

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

Описание

transactionId

Long

Да

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

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

{
  "transactionId": 0,
}

Ответ:

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

Тип

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

Описание

transactionId

Long

Да

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

status

enum

Да

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

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

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

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

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

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

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

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

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

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

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

Условия использования СБП

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

  • No labels