Обзор протокола

Платежные сервисы на российском рынке

Недавно платежи с помощью банковских карт или платежных сервисов на смартфонах стали все более популярными в России. Сервисы такие как Tinkoff Pay, Samsung Pay, Mi Pay, Mir Pay и другие предлагают удобный и быстрый способ совершать покупки без использования наличных денег.

Как работает платеж с помощью смартфона?

Клиенту достаточно приложить карту или смартфон с активированным платежным сервисом к устройству с функцией NFC (бесконтактной оплаты), которое находится на кассе.

Шаги процесса:

1. На главном экране выберите сумму покупки и нажмите кнопку Карта.
2. Покажите экран смартфона кассиру для проверки суммы покупки.
3. Приложите физическую или виртуальную банковскую карту к модулю NFC смартфона.

Если покупка превышает 1000 ₽, клиент должен будет ввести ПИН-код от банковской карты и нажать Подтвердить.

Решение возможных проблем

Если оплата не прошла, это может быть вызвано разными причинами:

• Недостаточно средств на карте: предложите клиенту проверить баланс или использовать другую карту.
• Проблема на стороне устройства: убедитесь, что NFC включен и интернет-соединение стабильно.
• Режим разработчика: при необходимости отключите его в настройках смартфона.

Безопасность таких платежей обеспечивается введением ПИН-кода и другими методами аутентификации.

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

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

При оплате по QR‑коду приложение генерирует QR‑код, клиент сканирует его камерой смартфона и оплачивает покупку в своем онлайн-банке.
Пошагово процесс выглядит так:
1. На главном экране введите сумму покупки и нажмите кнопку QR‑код.
2. ![QR-код](https://imgproxy.cdn-tinkoff.ru/compressed95:help_question_card_body_image_desktop_col_9/aHR0cHM6Ly9vcGlzLWNkbi50aW5rb2Zmam91cm5hbC5ydS9wbHV0by1iYWNrZW5kLWltYWdlcy9iZjM3OWQxNS5kZXNrdG9wXzA2LnBuZw==)
Покажите QR-код покупателю и попросите проверить сумму покупки до проведения оплаты
3. Если сумма верна, покупатель сканирует QR‑код в своем онлайн-банке или камерой смартфона и оплачивает покупку.
4. Если оплата прошла успешно, вы увидите экран с сообщением об этом. Нажмите Понятно, если хотите завершить прием платежа, или Отправить квитанцию, если клиент просит эл. квитанцию об оплате.
Вы увидите сообщение Оплата не прошла — недостаточно денег, если у покупателя не хватает денег на счете.
![Проверка баланса](https://imgproxy.cdn-tinkoff.ru/compressed95:help_question_card_body_image_desktop_col_9/aHR0cHM6Ly9vcGlzLWNkbi50aW5rb2Zmam91cm5hbC5ydS9wbHV0by1iYWNrZW5kLWltYWdlcy9mMzk4ZDhlOS4wMl9kZXNrLnBuZw==)
Предложите покупателю проверить баланс и лимиты или использовать другую карту
Если не увидели экран об успешной оплате и на вкладке Операции нет информации о проведенном платеже, значит, оплата не прошла. Попросите покупателя еще раз оплатить покупку и объясните, что в первый раз деньги с его счета не списались.
## Как работает виджет?
### Адаптация под любой сайт и приложение
Адаптивная форма виджета оплаты очень удобна и проста в установке для сайта или приложения. Она работает во всех браузерах и мобильных устройствах.
### Платежи без редиректа
Платежная форма обеспечивает возможность принимать оплату непосредственно на сайте, не перенаправляя клиентов на другие страницы для завершения покупки.
### Все платежные методы в одном месте
Виджет для онлайн-оплаты умеет самостоятельно распознавать тип платежной системы Visa, Mastercard, Мир и другие, а также банк-эмитент при оплате банковской картой. Кроме того, он работает с pay-сервисами, позволяющими осуществлять оплату в один клик для ещё большего удобства.
### Увеличение импульсных покупок
Используя платежный виджет для оплаты от CloudPayments, вы можете увеличить количество импульсных покупок и легко подключать для своих клиентов подписки (рекуррентные платежи). Это позволит эффективно управлять платежами без дополнительных технических доработок.
### Удобные технологии
При использовании виджета для приема платежей на вашем сайте он автоматически проведет проверку правильности заполнения карточных данных. В случае неудачного платежа виджет точно указывает причину, например недостаток средств на карте или истечение срока действия карты. Благодаря этому можно связаться с клиентом и и указать ему конкретную причину того, почему транзакция не прошла, и предложить повторить оплату.
## Какому бизнесу подойдет платежный виджет?

Использование NFC-стикеров для платежей

По данным Известий, в Росбанке, банке Дом.РФ и Экспобанке намерены выпустить NFC-стикеры в апреле-июле текущего года, а всего над внедрением технологии работает 16 отечественных кредитных организаций. Все банки выпускают платёжные стикеры на базе платёжной системы Мир.

Как работает NFC-стикер?

Наклейка с чипом помогает избежать конфликта между NFC-модулем смартфона и чипом на карте: его крепят на такое место в смартфоне, где сигналы друг друга не перебивают — как правило, в нижней части чехла. Это преимущественное отличие от пластика, который приходится доставать из чехла смартфона.

Где можно использовать NFC-стикер?

Стикер работает везде, где обслуживают платёжную систему Мир, а терминалы имеют NFC-модуль для бесконтактной оплаты. Даже в банкоматах с NFC-модулем можно использовать стикер для снятия наличных средств. При оплате стикером кэшбэк продолжает начисляться по правилам кредитной организации.

Безопасность и управление NFC-стикером

Национальная система платежных карт (НСПК) установила лимит операций на сумму до 3 тыс. рублей без введения пин-кода по платёжным стикерам. Для покупок, превышающих эту сумму, требуется подтверждение.

Безопасность NFC-стикера схожа с обычной картой: через мобильное приложение банка можно устанавливать пин-код, лимиты по операциям, пополнять баланс. В случае потери стикера его можно заблокировать в приложении или обратиться в кредитную организацию.

Выпуск нескольких NFC-стикеров

Банки предлагают выпустить несколько платёжных стикеров, привязанных к одному счёту. Максимальное количество стикеров зависит от банка-эмитента. Например, клиенты Тинькофф могут выпустить до 10 наклеек к одному счёту (20 для Premium). Банки также предлагают дополнительные клейкие ленты для замены стикера в случае смены телефона или чехла.

Новые ювелирные платежные аксессуары для бесконтактной оплаты

В ассортименте банков уже есть готовые аксессуары для бесконтактной оплаты, такие как браслеты, брелоки, кольца и подвески. У смарт-колец есть защита от ударов и влагозащитные функции. Накануне Нового года в рамках коллаборации между Тинькофф и Artpayments были выпущены ювелирные платежные аксессуары.

Сводка изменений

Версия 3.6.6 от 01.03.2024

| 3.6.0 | API Оплата по токену | В запросе метода оплаты по токену добавлен обязательный параметр TrInitiatorCode | 24.08.2023 |

| 3.5.9 | MIR PAY | Добавлено описание нового способа оплаты MIR Pay и его подключение | 02.08.2023 |

| 3.5.8 | Справочники | Обновлен справочник кодов ошибок, добавлены новые коды: 5017 — Customer Cancellation, 5055 — Invalid PIN. Добавлены рекомендации на отправку повторных запросов, если были получены определенные коды ошибок. | 19.07.2023 |

| 3.5.7 | API Отмена оплаты | Исключили из описания условие отмены операции до истечения 24 часов | 13.06.2023 |

| 3.5.6 | Уведомления. Проверка уведомлений | Обновлен список адресов, с которых система отправляет уведомления | 01.06.2023 |

| 3.5.5 | Tinkoff PayYandex PayСценарии интеграции | Добавлено описание способов подключения Tinkoff PayВ схеме выполнения платежа обновили используемые методыДобавлены рекомендации по интеграции с платежным решением CloudPayments | 31.05.2023 |

| 3.5.4 | Виджет Параметры | Добавлен пример реализации запуска виджета без библиотеки jquery | 10.05.2023 |

| 3.5.3 | API Оплата по токену, Виджет Параметры | Добавили параметр Payer в метод для оплаты по токену и новый пареметр виджета payer | 17.03.2023 |

| 3.5.2 | Справочники | Обновлен справочник кодов ошибок, добавлены новые коды: 5761 — No Phone, 5762 — Invalid Phone, 5763 — Different Phones | 16.03.2023 |

| 3.5.1 | Справочники | Обновлен справочник кодов ошибок, добавлен новый код ошибки | 29.12.2022 |

| 3.5.0 | Безопасная сделка | Добавлено описание нового протокола + изменения в текущем | 12.12.2022 |

| 3.4.0 | Платежный конструктор | Добавлен новый платежный конструктор | 28.10.2022 |

| 3.3.3 | Виджет Параметры | В виджет добавлен новый параметр autoClose | 25.08.2022 |

| 3.3.2 | API Выгрузка списка транзакций | Добавлено описание нового метода выгрузки списка транзакций | 17.06.2022 |

| 3.3.1 | Тестирование | Обновлен список карт для тестирования | 20.04.2022 |

| 3.3.0 | Yandex Pay | Добавлено описание способов подключения Yandex Pay | 25.03.2022 |

| 3.2.0 | Безопасная сделка | Добавлено описание метода по безопасной сделки | 24.01.2022 |

| 3.1.3 | API Отмена оплаты | Добавлено описание отмены до 24 часов | 20.07.2021 |

| 3.1.2 | API Принцип работы | Добавлено ограничение на количество одновременных запросов для терминалов | 11.05.2021 |

| 3.1.1 | API Оплата по криптограмме | В метод оплаты по криптограмме добавлен параметр Payer | 18.10.2021 |

Термины и определения

• Система — платежный шлюз CloudPayments.

• ТСП — торгово-сервисное предприятие, работающее с системой.

• API — программный интерфейс для взаимодействия с системой, расположенный по адресу https://api.cloudpayments.ru

• ЛК — личный кабинет ТСП в системе, расположенный по адресу https://merchant.cloudpayments.ru

• Карта — банковская карта платежных систем Visa, MasterCard или МИР.

• Эквайер — расчетный банк.

• Эмитент — банк, выпустивший карту.

• Держатель — физическое лицо, которому эмитент выдал карту в пользование.

• Виджет — платежная форма, предоставленная системой для ввода реквизитов карты держателем и последующей авторизации.

• 3-D Secure — протокол проверки держателя эмитентом.

Виды операций

Система предполагает два вида операций: оплата и возврат.

• При оплате деньги перечисляются со счета держателя в пользу ТСП. В случае возврата — наоборот.

• Возврат выполняет ТСП, если покупатель хочет вернуть товар.

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

• Операцию оплаты, в отличие от возврата, можно отменить.

• Отмену оплаты выполняет ТСП в случае, если платеж был совершен с ошибкой: неверная сумма, технический сбой и т.д. Есть ограничение — отменить операцию можно только в случае использования двухстадийной схемы оплаты. Деньги при этом будут разблокированы на карте держателя практически мгновенно.

Схемы проведения платежа

Существует два варианта проведения операции оплаты: одностадийная и двухстадийная, их также называют single message system (SMS) и dual message system (DMS).

Одностадийная оплата выполняется одной командой, по результатам которой проходит авторизация и последующее списание средств в пользу ТСП.

Двухстадийная оплата использует две команды: отдельно на авторизацию и списание. После успешной авторизации сумма операции будет блокирована на счету держателя, то есть он не сможет ей воспользоваться. Далее у ТСП есть до 7 дней, в зависимости от типа карты, для подтверждения операции, после чего произойдет списание денег. Если операцию не подтвердить в течение этого времени — она будет автоматически отменена. Подтверждать можно как всю сумму авторизации, так и ее часть.

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

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

Способы оплаты

Оплату можно проводить следующими способами:

• Через платежную форму — виджет. На вашем сайте прописывается скрипт, который открывает защищенную платежную форму — iframe для ввода карточных данных.

• Через API по криптограмме карты. На вашем сайте прописывается скрипт checkout, который собирает карточные данные из любой формы на сайте, шифрует и создает криптограмму для безопасной передачи через межсерверное взаимодействие.

• Через SDK для мобильных приложений. Интегрируйте мобильный SDK в ваше приложение для iOS или Android и принимайте карты к оплате с телефона или планшета ваших покупателей.

• Через Apple Pay и Google Pay на сайтах и в мобильных приложениях.

• Через API по токену карты — рекарринг. После первой оплаты через виджет или криптограмму система присваивает карточным данным идентификатор — токен, который можно безопасно хранить и использовать для безакцептных платежей — pay per click. Токен возвращается в Pay-уведомлении и в ответе системы на запрос по API.

• С помощью настроенного плана периодических платежей (рекуррент).

После первой оплаты или авторизации на 1 рубль для проверки карты система присваивает карточным данным токен, который далее используется для создания плана подписки на рекуррентные платежи. Оплата производится системой автоматически, без подтверждения плательщика, в соответствии с настроенным периодом, который может быть один раз в день (один раз в несколько дней), один раз в неделю (один раз в несколько недель) или один раз в месяц (один раз в несколько месяцев). Если очередная попытка оплаты не удалась, система отправляет уведомление и повторяет попытку через сутки. После трех неудачных попыток подряд система отменяет подписку.

При создании плана можно указать максимальное количество периодов, например, 12 месяцев при ежемесячной оплате, после чего подписка будет автоматически завершена.

• Кастомизируемые формы приема платежей.

Платежные формы позволяют фондам и другим организациям принимать пожертвования на свой счет с помощью настраиваемой, кастомизируемой платежной формы, которая может быть представлена в виде ссылки _c.cloudpayments.ru/payments/_и в виде QR-кода, который можно разместить, как в онлайн-трансляции, так и в офлайн-материалах (листовки, буклеты и т.д.). Форма значительно упрощает прием пожертвований. Доступна оплата картой, а также Apple Pay и Google Pay. В новом разделе личного кабинета «Платежные формы» можно создавать и кастомизировать до 5 платежных форм. Ссылку и QR-код для отправки плательщикам можно получить после сохранения формы.

D Secure

3-D Secure — общее название программ Verified By Visa и Mastercard Secure Code от платежных систем Visa и MasterCard. Суть программы — в проверке подлинности держателя защита от несанкционированного использования карты эмитентом перед оплатой. На практике это выглядит так: держатель указывает реквизиты карты, далее открывается сайт эмитента, где держателю предлагается ввести пароль или секретный код. Как правило, код отправляется в СМС-сообщении. Если код указан правильно, оплата будет проведена. Если нет — отклонена.

3-D Secure в процессе оплаты появляется не на всех картах, а только тех, банки-эмитенты которых поддерживают данную технологию. Проведение оплаты без 3-D Secure является менее безопасным вариантом.

Платежный виджет

Платежный виджет — всплывающая форма для ввода реквизитов карты и e-mail адреса плательщика. Виджет автоматически определяет тип платежной системы: Visa, MasterCard, Maestro или "МИР", а также банк-эмитент карты и показывает соответствующие логотипы. Форма оптимизирована для использования в любых браузерах и мобильных устройствах. Внутри виджета открывается iframe, который гарантирует безопасность передачи карточных данных и не требует от ТСП сертификации для использования.

Подробная документация для разработчиков.

Демо платежного конструктора.

Демонстрация работы виджета Widget представлена в нашем демо-магазине.

Для тестирования можно использовать как тестовые карточные данные, так и реальные. Списания денежных средств не произойдет.

Установка виджета

Для установки виджета необходимо прописать на сайте скрипт в раздел head:

<script </script>

Для появления платежной формы необходимо зарегистрировать функцию для вызова метода pay, передав в него параметр auth или charge:

 // или 'charge' //id из личного кабинета Оплата товаров в example.com //идентификатор плательщика (необязательно) //номер заказа (необязательно) //email плательщика (необязательно) //дизайн виджета (необязательно) //время в секундах до авто-закрытия виджета (необязательный) // адреса для перенаправления // при оплате по Tinkoff Pay тестовый проезд дом тест //действие при успешной оплате //действие при неуспешной оплате //Вызывается как только виджет получает от api.cloudpayments ответ с результатом транзакции. //например вызов вашей аналитики

И прописать вызов функции на событие, например, нажатие кнопки «Оплатить»:

Демонстрация работы виджета представлена в нашем демо-магазине.

Пример реализации запуска виджета без библиотеки jquery:

Для тестирования можно использовать как тестовые карточные данные, так и реальные. Списания денежных средств не произойдет.

Параметры

Вызов функции pay c аргументом auth или charge определяет схему проведения оплаты:

• charge для одностадийной оплаты

• auth — для двухстадийной оплаты

| Параметр | Формат | Применение | Описание |

| ————————————— | —— | ———————————- | —————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————- |

| publicId | String | Обязательный | Идентификатор сайта, который находится в ЛК |

| amount | Float | Обязательный | Сумма оплаты |

| currency | String | Обязательный | Валюта: RUB/USD/EUR/GBP (см. справочник) |

| accountId | String | Обязательный для создания подписки | Идентификатор пользователя |

| description | String | Необязательный | Описание назначения оплаты в произвольном формате |

| invoiceId | String | Необязательный | Номер заказа или счета |

| email | String | Необязательный | E-mail адрес пользователя |

| requireEmail | bool | Необязательный | Требование указать e-mail адрес пользователя в виджете |

| data | Json | Необязательный | Любые другие данные, которые будут связаны с транзакцией, в том числе инструкции для создания подписки или формирования онлайн-чека должны обёртываться в объект cloudpayments. Мы зарезервировали названия следующих параметров и отображаем их содержимое в транзакционной выгрузке в Личном Кабинете: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate |

| skin | String | Необязательный | Выбор дизайна виджета. Возможные варианты: classic, modern, mini. По умолчанию стоит — classic |

| retryPayment | bool | Необязательный | Появление кнопки «Повторить платеж» при неудачном платеже. По умолчанию стоит true |

| autoClose | number | Необязательный | Автоматическое закрытие виджета после успешной оплаты через указанное количество секунд (минимум 3 секунды, максимум 10 секунд). Дальнейшее поведение задается параметром onSuccess. Если параметр не передан, значение не определено — виджет автоматически не будет закрыт. |

| payer | Object | Необязательный | Доп. поле, куда передается информация о плательщике. Используйте следующие параметры: firstName, lastName, middleName, birth, street, address, city, country, phone, postcode |

| configuration.common.successRedirectUrl | String | Необязательный | Url для перенаправления клиента из мобильного приложения банка после успешной оплаты по Tinkoff Pay |

| configuration.common.failRedirectUrl | String | Необязательный | Url для перенаправления клиента из мобильного приложения банка после неуспешной оплаты по Tinkoff Pay |

В случае успешной или неуспешной оплаты, можно определить поведение формы следующими параметрами:

| Параметр | Формат | Применение | Описание |

| ———- | ——————- | ————— | ———————————————————————————————————————————————————————————————————————————————————- |

| onSuccess | Function или String | Необязательный | Указывается либо функция, либо адрес страницы сайта. В случае указания функции — она будет вызвана после успешного завершения оплаты и закрытия пользователем окна виджета. В случае указания адреса — пользователь будет направлен на указанную страницу. |

| onFail | Function или String | Необязательный | Указывается либо функция, либо адрес страницы сайта. В случае указания функции — она будет вызвана после неуспешного завершения платежа. В случае указания адреса — пользователь будет направлен на указанную страницу. |

| onComplete | Function | Необязательный | Указывается функция, которая будет вызвана, как только виджет получит ответ с результатом транзакции. Редиректы в этом методе делать нельзя. |

Локализация виджета

По умолчанию мы отображаем виджет на русском языке. Для вызова виджета на других языках передайте в параметрах инициализации виджета параметр language.

Список поддерживаемых языков:

| Язык | Часовой пояс | Код |

| ————— | ———— | —— |

| Русский | MSK | ru-RU |

| Английский | CET | en-US |

| Немецкий | CET | de-DE |

| Латышский | CET | lv |

| Азербайджанский | AZT | az |

| Русский | ALMT | kk |

| Казахский | ALMT | kk-KZ |

| Украинский | EET | uk |

| Польский | CET | pl |

| Португальский | CET | pt |

| Чешский | CET | cs-CZ |

| Вьетнамский | ICT | vi-VN |

| Турецкий | TRT | tr-TR |

| Испанский | CET | es-ES |

| Итальянский | CET | it |

| Узбекский | UZT | uz |

Рекуррентные платежи (подписка)

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

| Параметр | Формат | Применение | Описание |

| ————— | ——— | ————— | —————————————————————————————————————————————————————————————————— |

| Interval | String | Обязательный | Интервал. Возможные значения: Day, Week, Month |

| Period | Int | Обязательный | Период. В комбинации с интервалом, 1 Month значит раз в месяц, а 2 Week — раз в две недели. Должен быть больше 0 |

| MaxPeriods | Int | Необязательный | Максимальное количество платежей в подписке. По умолчанию стоит без ограничений. Если задаете количество, проверьте, чтобы оно было больше 0 |

| Amount | Number | Необязательный | Сумма регулярного платежа. По умолчанию совпадает с суммой первого, установочного платежа. Если указываете другую сумму, проверьте, чтобы она была больше 0 |

| StartDate | DateTime | Необязательный | Дата и время первого регулярного платежа. По умолчанию запуск произойдет через указанный интервал и период, например через месяц. Если указываете другую дату, то она должна стоять в будущем времени |

| CustomerReceipt | String | Необязательный | Данные для формирования онлайн-чека в регулярных платежах |

Параметры для запуска регулярных платежей необходимо добавить в объект data.CloudPayments.recurrent как в примере ниже::

 Наименование товара 3 // тег-1214 признак способа расчета - признак способа расчета // тег-1212 признак предмета расчета - признак предмета товара, работы, услуги, платежа, выплаты, иного предмета расчета //система налогообложения; необязательный, если у вас одна система налогообложения //e-mail покупателя, если нужно отправить письмо с чеком //телефон покупателя в любом формате, если нужно отправить сообщение со ссылкой на чек //чек является бланком строгой отчетности // Сумма оплаты электронными деньгами // Сумма из предоплаты (зачетом аванса) (2 знака после точки) // Сумма постоплатой(в кредит) (2 знака после точки) // Сумма оплаты встречным предоставлением (сертификаты, др. мат.ценности) (2 знака после точки) //чек для первого платежа //чек для регулярных платежей //создание ежемесячной подписки //id из личного кабинета Подписка на ежемесячный доступ к сайту example.com //номер заказа (необязательно) //идентификатор плательщика (обязательно для создания подписки) //действие при успешной оплате //действие при неуспешной оплате

Обратите внимание, что создать подписку можно, указав параметр accountId, который может быть e-mail адресом, номером телефона или любым другим идентификатором плательщика.

Больше примеров создания рекуррентных платежей из виджета — в разделе "Сценарии интеграции".

Для отмены рекуррентных платежей используйте возможности личного кабинета, API или предоставьте покупателю ссылку на сайт системы — https://my.cloudpayments.ru/, где он самостоятельно сможет найти и отменить свои подписки.

Мобильный виджет

Скрипт автоматически определяет устройство пользователя и запускает наиболее подходящий вариант виджета: обычный либо оптимизированный для мобильных устройств. Для удобства покупателей мобильная версия виджета занимает весь экран и предлагает провести оплату либо картой, либо по технологии Apple Pay или Google Pay.

Возможность оплаты в виджете через Apple Pay и Google Pay появляется при соблюдении следующих условий:

1. Сайт работает по схеме HTTPS и поддерживает протокол TLS версии 1.2.

2. На сайте отсутствует "mixed content", когда часть ресурсов загружается по HTTPS, а часть — по HTTP.

3. Проведена упрощенная (только для веб-сайтов) или классическая интеграция функции Apple Pay.

4. Клиент открыл страницу оплаты на сайте в браузере, который поддерживает Apple или Google Pay. Для Apple Pay это Apple Safari, для Google Pay — Google Chrome, Mozilla Firefox, Apple Safari, Microsoft Edge, Opera или UCWeb UC. Другие браузеры не поддерживают возможность оплаты с помощью Apple или Google Pay.

Платежный конструктор

Первый блок — содержит форму для ввода реквизитов карты и электронной почты плательщика со всеми доступными способами оплаты, интегрируемая в DOM элемент. Блок автоматически определяет тип платежной системы (Visa, MasterCard, Maestro, UnionPay или «МИР»), банк-эмитент карты, а также показывает соответствующие логотипы.

Форма оптимизирована для использования в любых браузерах и мобильных устройствах. Внутри блока открывается iframe, который гарантирует безопасность передачи карточных данных и не требует от ТСП сертификации для использования.

Подробная документация для разработчиков.

Скрипт checkout

Checkout — скрипт, который прописывается на вашем сайте, собирает из указанной формы карточные данные и составляет из них криптограмму для оплаты через наш API.

Криптограмма формируется алгоритмом RSA с длиной ключа в 2048 бит и удовлетворяет стандарту по защите карточных данных. При соблюдении описанных ниже требований карточные данные к вам не попадают, но ваш сервер всё равно влияет на их безопасность.

Demo checkout

Демонстрация работы скрипта Checkout представлена в нашем демо-магазине.

Для тестирования можно использовать как тестовые карточные данные, так и реальные. Списания денежных средств не произойдет.

Требования

Требования к форме:

• Должна работать по HTTPS-соединению с валидным SSL-сертификатом.

• На полях не должно быть атрибута "name" — это предотвращает попадание карточных данных на сервер при отправке формы.

• Поле для ввода номера карты должно поддерживать ввод от 16 до 19 цифр.

Требования к криптограмме:

• Должна формироваться только оригинальным скриптом checkout, загруженным с адресов системы.

• Криптограмму нельзя хранить после оплаты и использовать повторно.

Требования к безопасности по PCI DSS:

С точки зрения PCI DSS, подобный способ подключения классифицируется как "E-commerce merchants who outsource all payment processing to PCI DSS validated third parties, and who have a website(s) that doesn’t directly receive cardholder data but that can impact the security of the payment transaction. No electronic storage, processing, or transmission of any cardholder data on the merchant’s systems or premises.", то есть обработка платежных данных выполняется третьей стороной, но сайт влияет на безопасность карточных данных.

Для соблюдения требований стандарта, необходимо заполнять лист самооценки SAQ-EP и ежеквартально проходить ASV-тестирование.

Подробнее про соответствие требованиям PCI читайте в разделе PCI DSS.

Установка

Для создания криптограммы необходимо прописать на странице с платежной формой скрипт checkout:

<script </script>

Выбрать удобный для вас вариант передачи карточных данных:

• Передача в скрипт

• Форма для ввода

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

Вариант с передачей карточных данных напрямую в скрипт

1. Инициализировать скрипт checkout

2. Вызвать метод генерации криптограммы, передав в него карточные данные

 4242 4242 4242 4242 

Вариант с использованием формы:

1. Создать форму для ввода карточных данных:

<form <input data-cp <input data-cp <input data-cp <input data-cp <input data-cp <button Оплатить 100 р.</button>
</form>

Поля ввода карточных данных должны быть помечены атрибутами:

• data-cp="cardNumber" — поле с номером карты;

• data-cp="expDateMonth" — поле с месяцем срока действия;

• data-cp="expDateYear" — поле с годом срока действия;

• data-cp="cvv" — поле с кодом CVV;

• data-cp="name" — поле с именем и фамилией держателя карты.

2. Инициализировать скрипт checkout

3. Вызвать метод генерации криптограммы

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

• длина номера карты составляет от 16 (15 для карт AMEX) до 19 цифр. Подробнее тут;

• скрипт checkout не работает в устаревших, небезопасных браузерах, которые не поддерживают протоколы шифрования TLS версии 1.1 или выше. Например, в Internet Explorer 7;

• окно 3DS можно показывать как в новом окне, так и во фрейме поверх страницы. Размер окна должен быть не менее 500х500 пикселей.

Методы

Асинхронный метод для генерации криптограммы.

В данном методе при ошибке валидации карточных данных — вместо локализованного сообщения будет выдан код ошибки пример см. ниже.

async createPaymentCryptogram(fieldValues: CardData): Promise<string>

Метод возвращает Promise содержащий криптограмму. В случае если переданы некорректные данные Promise будет отклонен с ошибкой содержащей объект со списком ошибок.

 4242 4242 4242 4242 

Описание объекта CardData:

 // CVV/CVC код // Номер карты, наличие пробелов не имеет значения // Срок действия карты - месяц // Срок дейcтвия карты - год // Срок действия карты, все символы за исключением цифр игнорируются, //Если длина строки 2,3 или 5 символов то первая цифра воспринимается как месяц, оставшиеся как год. //Если длина строки 4 или 6 символов то первые два трактуются как месяц, а оставшиеся как год.

| Параметр | Описание | Тип | Обязательный * |

| —————- | ——————————————————————————————————————————————————————————————————————————————————————- | —— | —————————————————————————————— |

| cvv | CVV/CVC код | string | Нет * |

| cardNumber | Номер карты, наличие пробелов не имеет значения | string | Не обязательный, если поле привязано в форме |

| expDateMonth | Срок действия карты — месяц | string | Не обязательный, если поле привязано в форме или передано поле expDateMonthYear |

| expDateYear | Срок дейcтвия карты — год | string | Не обязательный, если поле привязано в форме или переданы поля expDateMonth и expDateYear |

| expDateMonthYear | Срок действия карты, все символы за исключением цифр игнорируются. Если длина строки 2, 3 или 5 символов то первая цифра воспринимается как месяц, оставшиеся как год. Если длина строки 4 или 6 символов то первые два трактуются как месяц, а оставшиеся как год. | string | Не обязательный, если поле привязано в форме или переданы поля expDateMonth и expDateYear |

| name | Имя владельца карты | string | Нет |

Обработка ошибок валидации карточных данных:

 // Невалидный CVV 4242 4242 4242 424 // Невалидный номер карты

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

| ————————- | ———————— |

| CardNumber_Empty | Пустой номер карты |

| CardNumber_Invalid | Некорректный номер карты |

| Cvv_Empty | Пустой CVV |

| Cvv_Invalid | Некорректный CVV |

| ExpDateMonthYear_Empty | Пустой год и месяц |

| ExpDateMonthYear_Invalid | Некорректный год и месяц |

| ExpDateMonth_Empty | Пустой месяц |

| ExpDateMonth_Invalid | Некорректный месяц |

| ExpDateYear_Empty | Пустой год |

| ExpDateYear_Invalid | Некорректный год |

| Name_Empty | Пустое имя * |

| Name_Invalid | Некорректное имя * |

| Name_TooLong | Слишком длинное имя * |

| Name_TooShort | Слишком короткое имя * |

Метод для генерации криптограммы

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

Метод может принимать на вход объект с карточными данными и может использоваться в устаревшей схеме с привязкой к HTML-форме. В случае если используется и привязка формы и этот же параметр найден в объекте CardData при попытке сформировать криптограмму будет выброшена ошибка.

Cкрипт для создания криптограммы:

 // сформирована криптограмма // найдены ошибки в введённых данных, объект `result.messages` формата: /* Создание checkout */ // public id из личного кабинета // тег, содержащий поля данных карты

Рекуррентные платежи

Рекуррентные платежи, также известные как платежи по подписке или «автоплатежи» — возможность выполнять регулярные списания денег с банковской карты покупателя без повторного ввода реквизитов карты и без участия плательщика для инициации очередного платежа.

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

Есть распространенное мнение, что задача рекуррентного биллинга сводится к тому, чтобы установить сумму, которая будет каждый месяц списываться с карты клиента. Выбор системы регулярных платежей при этом основан только на стоимости предоставляемых услуг. В действительности — ситуация более сложная, потому как для качественного сервиса требуется намного больше функций и возможностей. Мы сделали все, чтобы в системе CloudPayments процедура запуска и обработки рекуррентных платежей стала максимально простой и гибкой.

Запуск и остановка регулярных платежей

Запуск рекуррентных платежей возможен в любое время после выполнения установочного платежа: в тот же момент, через неделю или через месяц. Ограничение только одно — интервал между регулярными платежами, а также между установочным и первым регулярным платежом не может превышать один год.

Пример: покупатель оплачивает первый месяц предоставления услуг через установочный платеж и дает согласие на ежемесячное списание с его карты начиная со второго месяца.

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

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

Также плательщик может самостоятельно найти и отменить свои регулярные платежи на сайте системы CloudPayments.

Возможность настройки графика платежей

Выбор периода и интервала списания

Система может выполнять регулярные платежи каждые 2 недели, 1 раз в месяц, каждые 3 месяца и так далее: вы можете указать любой период.

Выбор даты начала списаний

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

Пример: покупатель подписывается на вашу услугу в середине месяца, вы создаете план ежемесячных рекуррентных платежей начиная со следующего месяца по 15-м числам.

Ограничение на количество платежей

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

Пример: покупатель приобретает товар стоимостью 12 000 рублей в рассрочку на год — оплачивает 1000 рублей установочным платежом и подписывается на план рекуррентных платежей по 1000 рублей ежемесячно, но не более 11 списаний.

Заморозка плана

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

Пример: покупатель просит приостановить предоставление услуг на пару месяцев, вы сдвигаете дату следующего платежа на соответствующий срок.

Возможность смены суммы платежа

Сумма установочного платежа

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

Пример: покупатель регистрируется в вашем сервисе, вы просите его выполнить установочный платеж на 1 рубль для проверки карты. Далее, с согласия пользователя, запускаете рекуррентные платежи на любую сумму.

Сумма рекуррентных платежей

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

Пример: вы предоставляете покупателю скидку на первые 2 месяца использования сервиса, далее повышаете сумму подписки.

Автоматическая коррекция ошибок

Ошибки, которые возникают при выполнении рекуррентных платежей, можно разделить на: поправимые и непоправимые.

В первую категорию относятся ошибки, связанные с недостатком средств на карте покупателя, с временными техническими проблемами или недоступностью банка-эмитента карты. Как правило, данные проблемы может исправить держатель карты.

Во вторую категорию попадают ошибки, исправление которых невозможно: истек срок действия карты, карта утеряна, у банка-эмитента отозвана лицензия.

В зависимости от категории система по-разному реагирует и обрабатывает ошибки рекуррентных платежей.

Взаимодействие с держателем карты

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

Повторные попытки

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

Обновление карты

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

Оповещение покупателя

Важная функция рекуррентных платежей — это своевременное информирование держателя карты о наступлении даты очередного платежа. Некоторым покупателям свойственна забывчивость, поэтому предупреждение о предстоящем списании убирает эффект внезапности и существенно снижает вероятность отсутствия денег на карте. Система CloudPayments всегда напоминает плательщикам дату очередного платежа с указанием суммы, назначения и получателя оплаты.

Описание продукта

Сервис "Безопасная сделка" позволяет организовать взаиморасчеты между двумя физическими лицами при продаже услуг или товаров. При этом, взаимодействие между физическими лицами происходит не напрямую между собой, а при участии Площадки — юридического лица, которое организует размещение Товара на своей витрине, помогает Продавцу найти покупателя, а также организует арбитраж, в случае такой необходимости. Площадка контролирует ход выполнения сделки, и дает команду CloudPayments на списание с карты в момент покупки, а после успешного выполнение продавцом своих обязанностей (например, после исполнения оговоренных услуг или работ, либо после успешной доставки товара), инициирует выплату на карту продавцу.

Определения и термины

Плательщик — физическое лицо, которое отправляет денежные средства.

Получатель — физическое лицо, которое получает денежные средства.

Площадка — посредник, который выступает гарантом безопасности сделки, принимает решение о выполнении сторонами своих обязательств. В спорных случаях выступает Арбитром в спорах и несет финансовую ответственность.

Сделка — процесс приобретения товара/услуги одним физическим лицом у другого.

Оплата — приобретение товара/услуги у физического лица.

Выплата — получение вознаграждения физического лица, оказавшего услугу/продавцу товара.

Widget — всплывающая форма для ввода реквизитов карты и e-mail адреса плательщика.

Checkout — скрипт, который прописывается на сайте, собирает из указанной формы карточные данные и составляет из них криптограмму для оплаты через API.

AccumulationId — уникальный идентификатор сделки, присваиваемый во время первой операции.TransactionId — уникальный идентификатор транзакции.

Настройка подключения

Для подключения продукта"Безопасная сделка" необходимо подать заявку своему персональному менеджеру или указать это на этапе подключения выделенному менеджеру.

Cхемы работы

1. Накопление нескольких платежей и проведение единой выплаты (N:1)

2. Разделение одного платежа на несколько выплат (1:N)

Статусная модель сделки

N

Схема интеграции для Widget:

Переменная содержащая тип сделки, которая содержится в объекте cp.constant.escrow. Она отвечает за схему проведения сделки:

1. Множество оплат и одна выплата;

2. Одна оплата и множество выплат.

Если данная переменная не передается, система автоматически считает, что сделка производится по протоколу N:1.

cp.constant.escrow.NToOne // переменная для типа сделки =
cp.constant.escrow.OneToN // переменная для типа сделки = 

Оплата (первичное создание накопления)

 // 'charge' //id из личного кабинета //валюта (единственная поддерживаемая валюта) //идентификатор плательщика (необязательно) //номер заказа (необязательно) //email плательщика (необязательно) //дизайн виджета (необязательно) // объект описывающий безопасную сделку // - Используется для первой оплаты - для создания накопления // - Оплата по уже созданному накоплению. // Объект escrow требует наличия поля startAccumulation со значением true, либо поля AccumulationId с id накопления, но не обоих одновременно // действие при успешной оплате // действие при неуспешной оплате // Вызывается как только виджет получает от api.cloudpayments ответ с результатом транзакции.

В ответ на запрос, в Pay уведомлении будет получен уникальный EscrowAccumulationId.

Также, при условии успешной транзакции, EscrowAccumulationId будет содержаться во всех вебхуках, кроме Check вебхука.

Оплата (по созданному накоплению)

Для последующих запросов (оплат), в рамках созданной безопасной сделки, необходимо добавить поля accumulationId, startAccumulation, escrowType в объект escrow.

 // - Оплата по уже созданному накоплению.

Схема интеграции для API Checkout:

Оплата (первичное создание накопления)

Необходимо использовать запрос payments/cards/charge (либо auth), где в теле в теле запроса в объекте escrow нужно передать "StartAccumulation": true и тип сделки "EscrowType":0 или "EscrowType": “NToOne" . То есть для EscrowType значения можно передавать как целочисленное значение (0/1), так и строковым представлением (NToOne/OneToN).

В ответ на запрос будет получен уникальный EscrowAccumulationId.

"Сибирский федеральный округ""Visa Signature (Signature)""Оплата успешно проведена"

В ответ на запрос, в Pay уведомлении будет получен уникальный EscrowAccumulationId.

Также, при условии успешной транзакции, EscrowAccumulationId будет содержаться во всех вебхуках, кроме Check вебхука.

Оплата (по созданному накоплению)

Для последующих запросов (оплат), в рамках созданной безопасной сделки, необходимо добавить в запрос payments/cards/charge AccumulationId в объект Escrow с указанием "StartAccumulation": false и тип сделки "EscrowType":0 или "EscrowType": “NToOne":

"Сибирский федеральный округ""Visa Signature (Signature)""Оплата успешно проведена"

Для завершения сделки необходимо отправить запрос payments/token/topup с указанием AccumulationId и массива транзакций к выплате:

Массив транзакций оплаты для выплаты должен должен содержать только транзакции, которые проводились по терминалу оплаты с текущим AccumulationId. Выплата будет осуществлена только по тем TransactionId, которые были указаны в TransactionIds в запросе payments/token/topup. По неуказанным транзакциям, провести выплату не возможно, т.к. сделка будет уже закрытой. Т.е. по закрытой сделке невозможно сделать как оплату, так и выплату.

Ограничения

Сумма выплат должна быть меньше, либо равна сумме оплат.

Ни по одной из транзакций, указанных в массиве транзакций для выплаты не должно быть отмен/полных возвратов (частичные возвраты производить можно).

Если запрос на оплату приходит с AccumulationId, а по нему уже есть выплата — оплата будет отклонена.

Все транзакции для выплаты должны быть:

• с одинаковым AccumulationId

• не выплачены

• в валюте "рубль"

• типа Payment

• в статусе Completed