API

API — программный интерфейс системы для взаимодействия с системами ТСП.


Интерфейс работает по адресу https://api.cloudpayments.ru и поддерживает функции для выполнения платежа, отмены оплаты, возврата денег, завершения платежей, выполненных по двухстадийной схеме, создания и отмены подписок на рекуррентные платежи, а также отправки счетов по почте.

Архитектура

API использует REST архитектуру. Параметры передаются методом POST в теле запроса в формате «ключ=значение» либо в JSON.


Выбор формата передачи параметров определяется на стороне клиента и управляется через заголовок запроса Content-Type:

  • Для параметров «ключ=значение» Content-Type: application/x-www-form-urlencoded
  • Для параметров JSON Content-Type: application/json

Ответ система выдает в JSON формате, который как минимум включает в себя два параметра: Success и Message:

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

Аутентификация запросов

Для аутентификации запроса используется HTTP Basic Auth — отправка логина и пароля в заголовке HTTP запроса. В качестве логина используется Public ID, в качестве пароля — API Secret. Оба этих значения можно получить в личном кабинете.


Если в запросе не передан заголовок с данными аутентификации или переданы неверные данные, система вернет HTTP статус 401 – Unauthorized.

Идемпотентность API

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


Для включения идемпотентности необходимо в запросе к API передавать заголовок с ключом X-Request-ID, содержащий уникальный идентификатор. Формирование идентификатора запроса остается на вашей стороне — это может быть guid, комбинация из номера заказа, даты и суммы или любое другое значение на ваше усмотрение.


Каждый новый запрос, который необходимо обработать, должен включать новое значение X-Request-ID. Обработанный результат хранится в системе в течение 1 часа.

Тестовый метод [идемпотентный]

Для проверки взаимодействия с API можно вызвать тестовый метод по адресу https://api.cloudpayments.ru/test без передачи параметров. В ответ метод возвращает статус запроса.

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

Оплата по криптограмме [идемпотентный метод]

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

Параметры запроса:

Параметр Формат Применение Описание
Amount Numeric Обязательный Сумма платежа
Currency String Обязательный Валюта: RUB/USD/EUR/GBP (см. справочник)
IpAddress String Обязательный IP адрес плательщика
Name String Обязательный для всех платежей кроме Apple Pay Имя держателя карты в латинице
CardCryptogramPacket String Обязательный Криптограмма платежных данных
InvoiceId String Необязательный Номер счета или заказа
Description String Необязательный Описание оплаты в свободной форме
AccountId String Необязательный Идентификатор пользователя
Email String Необязательный E-mail плательщика на который будет отправлена квитанция об оплате
JsonData Json Необязательный Любые другие данные, которые будут связаны с транзакцией, в том числе инструкции для создания подписки или формирования онлайн-чека.
Мы зарезервировали названия следующих параметров и отображаем их содержимое в реестре операций, выгружаемом в Личном Кабинете: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate.


В ответ сервер возвращает JSON с тремя составляющими: поле success — результат запроса, поле message — описание ошибки, объект model — расширенная информация.


Возможные варианты:

  • Некорректно сформирован запрос:
    success — false
    message — описание ошибки
  • Требуется 3-D Secure аутентификация (неприменимо для Apple Pay):
    succes — false
    model — информация для проведения аутентификации
  • Транзакции отклонена:
    success — false
    model — информация о транзакции и код ошибки
  • Транзакции принята:
    success — true
    model — информация о транзакции

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

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

Пример ответа: требуется 3-D Secure аутентификация

Пример ответа: транзакция отклонена. В поле ReasonCode код ошибки (см. справочник)

Пример ответа: транзакция принята

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

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

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

Регистр букв в названии параметров имеет значение.

Пример формы:

После аутентификации, плательщик будет возвращен на TermUrl с параметрами MD и PaRes, переданными методом POST.


Для завершения оплаты необходимо вызвать метод по адресу https://api.cloudpayments.ru/payments/cards/post3ds с передачей следующих параметров:

Параметр Формат Применение Описание
TransactionId Int Обязательный Значение параметра MD
PaRes String Обязательный Значение одноименного параметра

В ответ на корректно сформированный запрос, сервер вернет либо информацию об успешной транзакции, либо — об отклоненной

Оплата по токену (рекарринг) [идемпотентный метод]

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

Параметры запроса:

Параметр Формат Применение Описание
Amount Numeric Обязательный Сумма платежа
Currency String Обязательный Валюта: RUB/USD/EUR/GBP (см. справочник)
AccountId String Обязательный Идентификатор пользователя
Token String Обязательный Токен
InvoiceId String Необязательный Номер счета или заказа
Description String Необязательный Назначение платежа в свободной форме
IpAddress String Необязательный IP адрес плательщика
Email String Необязательный E-mail плательщика на который будет отправлена квитанция об оплате
JsonData Json Необязательный Любые другие данные, которые будут связаны с транзакцией, в том числе инструкции для создания подписки или формирования онлайн-чека.
Мы зарезервировали названия следующих параметров и отображаем их содержимое в реестре операций, выгружаемом в Личном Кабинете: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate.


В ответ сервер возвращает JSON с тремя составляющими: поле success — результат запроса, поле message — описание ошибки, объект model — расширенная информация.


Возможные варианты:

  • Некорректно сформирован запрос:
    success — false
    message — описание ошибки
  • Транзакции отклонена:
    success — false
    model — информация о транзакции и код ошибки
  • Транзакции принята:
    success — true
    model — информация о транзакции

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

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

Пример ответа: транзакция отклонена. В поле ReasonCode код ошибки (см. справочник)

Пример ответа: транзакция принята

Подтверждение оплаты [идемпотентный метод]

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


Метод работает по адресу https://api.cloudpayments.ru/payments/confirm и принимает следующие параметры:

Параметр Формат Применение Описание
TransactionId Int Обязательный Номер транзакции в системе
Amount Numeric Обязательный Сумма подтверждения в валюте транзакции
JsonData Json Необязательный Любые другие данные, которые будут связаны с транзакцией, в том числе инструкции для формирования онлайн-чека.

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

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

Отмена оплаты

Отмену оплаты можно выполнить через личный кабинет либо через вызов метода API. Метод работает по адресу https://api.cloudpayments.ru/payments/void и принимает один параметр:

Параметр Формат Применение Описание
TransactionId Int Обязательный Номер транзакции в системе

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

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

Возврат денег [идемпотентный метод]

Возврат денег можно выполнить через личный кабинет либо через вызов метода API. Метод работает по адресу https://api.cloudpayments.ru/payments/refund и принимает следующие параметры:

Параметр Формат Применение Описание
TransactionId Int Обязательный Номер транзакции оплаты
Amount Numeric Обязательный Сумма возврата в валюте транзакции
JsonData Json Необязательный Любые другие данные, которые будут связаны с транзакцией, в том числе инструкции для формирования онлайн-чека.

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

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

Просмотр информации об операции

Для просмотра информации о транзакции необходимо отправить запрос на адрес https://api.cloudpayments.ru/payments/get с указанием номера интересующей транзакции:

Параметр Формат Применение Описание
TransactionId Int Обязательный Номер транзакции

Если транзакция с указанным номером была найдена, система отобразит информацию об ней.

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

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

Проверка статуса платежа

Для поиска платежа и проверки статуса (см. справочник) необходимо отправить запрос на адрес https://api.cloudpayments.ru/payments/find с указанием номера заказа, по которому была сформирована транзакция:

Параметр Формат Применение Описание
InvoiceId String Обязательный Номер заказа

Если платеж по указанному номеру заказа был найден, система отобразит либо информацию об успешной транзакции, либо — об отклоненной. Если будет найдено несколько платежей с указанным номером заказа, то система вернет информацию только о последней операции.

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

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

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

Выгрузка списка транзакций

Для выгрузки списка транзакций за день необходимо отправить запрос на адрес https://api.cloudpayments.ru/payments/list с указанием даты по которой будут отбираться операции:

Параметр Формат Применение Описание
Date Date Обязательный Дата создания операций
TimeZone String Необязательный Код временной зоны, по умолчанию — UTC

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

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

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

Создания подписки на рекуррентные платежи [идемпотентный метод]

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

Параметр Формат Применение Описание
Token String Обязательный Токен карты, выданный системой после первого платежа
AccountId String Обязательный Идентификатор пользователя
Description String Обязательный Назначение платежа в свободной форме
Email String Обязательный E-mail плательщика
Amount Numeric Обязательный Сумма платежа
Currency String Обязательный Валюта: RUB/USD/EUR/GBP (см. справочник)
RequireConfirmation Bool Обязательный Если значение true — платежи будут выполняться по двустадийной схеме
StartDate DateTime Обязательный Дата и время первого платежа по плану во временной зоне UTC
Interval String Обязательный Интервал. Возможные значения: Day, Week, Month
Period Int Обязательный Период. В комбинации с интервалом, 1 Month значит раз в месяц, а 2 Week — раз в две недели.
MaxPeriods Int Необязательный Максимальное количество платежей в подписке

В ответ на корректно сформированный запрос система возвращает сообщение об успешно выполненной операции и идентификатор подписки.

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

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

Запрос информации о подписке

Для получения информации о статусе подписки, необходимо отправить запрос на адрес https://api.cloudpayments.ru/subscriptions/get с передачей единственного параметра:

Параметр Формат Применение Описание
Id String Обязательный Идентификатор подписки

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

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

Поиск подписок

Для получения списка подписок для определенного аккаунта, нужно сделать запрос на адрес https://api.cloudpayments.ru/subscriptions/find с передачей единственного параметра:

Параметр Формат Применение Описание
accountId String Обязательный Идентификатор аккаунта

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

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

Изменение подписки на рекуррентные платежи

Для изменения ранее созданной подписки, необходимо отправить запрос на адрес https://api.cloudpayments.ru/subscriptions/update с передачей следующих параметров:

Параметр Формат Применение Описание
Id String Обязательный Идентификатор подписки
Description String Необязательный Для изменения назначение платежа
Amount Numeric Необязательный Для изменения суммы платежа
Currency String Необязательный Для изменения валюты: RUB/USD/EUR/GBP (см. справочник)
RequireConfirmation Bool Необязательный Для изменения схемы проведения платежей
StartDate DateTime Необязательный Для изменения даты и времени первого (или следующего) платежа во временной зоне UTC
Interval String Необязательный Для изменения интервала. Возможные значения: Week, Month
Period Int Необязательный Для изменения периода. В комбинации с интервалом, 1 Month значит раз в месяц, а 2 Week — раз в две недели.
MaxPeriods Int Необязательный Для изменения максимального количества платежей в подписке

В ответ на корректно сформированный запрос система возвращает сообщение об успешно выполненной операции и параметры подписки.

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

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

Отмена подписки на рекуррентные платежи

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

Параметр Формат Применение Описание
Id String Обязательный Идентификатор подписки

В ответ на корректно сформированный запрос система возвращает сообщение об успешно выполненной операции.

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

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

Вы также можете предоставить покупателю ссылку на сайт системы — https://my.cloudpayments.ru/unsubscribe, где он самостоятельно сможет найти и отменить свои регулярные платежи.
Создание счета для отправки по почте [идемпотентный метод]

Для формирования ссылки на оплату и последующей отправки уведомления на e-mail адрес плательщика, можно воспользоваться методом https://api.cloudpayments.ru/orders/create с передачей следующих параметров:

Параметр Формат Применение Описание
Amount Numeric Обязательный Сумма платежа
Currency String Обязательный Валюта: RUB/USD/EUR/GBP (см. справочник)
Description String Обязательный Назначение платежа в свободной форме
Email String Необязательный E-mail плательщика
RequireConfirmation Bool Необязательный Есть значение true — платеж будет выполнен по двустадийной схеме
SendEmail Bool Необязательный Если значение true — плательщик получит письмо со ссылкой на оплату
InvoiceId String Необязательный Номер заказа в вашей системе
AccountId String Необязательный Идентификатор пользователя в вашей системе
Phone String Необязательный Номер телефона плательщика в произвольном формате
SendSms Bool Необязательный Если значение true — плательщик получит СМС со ссылкой на оплату
SendViber Bool Необязательный Если значение true — плательщик получит сообщение в Viber со ссылкой на оплату
CultureInfo String Необязательный Язык уведомлений. Возможные значения: "ru-RU", "en-US"
SubscriptionBehavior String Необязательный Для создания платежа с подпиской. Возможножные значения: CreateWeekly, CreateMonthly

В ответ на корректно сформированный запрос система возвращает параметры запроса и ссылку на оплату.

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

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

Сообщение на телефон плательщика может быть отправлено только одним выбранным способом: СМС или Viber.

Отмена созданного счета

Для отмены созданного счета необходимо отправить запрос на адрес https://api.cloudpayments.ru/orders/cancel с передачей следующих параметров:

Параметр Формат Применение Описание
Id String Обязательный Идентификатор счета

В ответ на корректно сформированный запрос система возвращает сообщение об успешно выполненной операции.

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

Пример ответа:
Запуск сессии для оплаты через Apple Pay

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

Метод работает по адресу https://api.cloudpayments.ru/applepay/startsession и принимает следующие параметры:

Параметр Формат Применение Описание
ValidationUrl Строка Обязательный Адрес, полученный из Apple JS

В ответ на корректно сформированный запрос система возвращает ответ, где в объекте Model содержится сессия для оплаты Apple Pay в формате JSON.

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

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

Смена локализации

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

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

Язык Часовой пояс Код
Русский MSK ru-RU
Английский CET en-US
Латышский CET lv
Азербайджанский AZT az
Русский ALMT kk
Украинский EET uk
Польский CET pl