API
API — программный интерфейс системы для взаимодействия с системами ТСП.
Интерфейс работает по адресу https://api.cloudpayments.kz и поддерживает функции для выполнения платежа, отмены оплаты, возврата денег, завершения платежей, выполненных по двухстадийной схеме, создания и отмены подписок на рекуррентные платежи, а также отправки счетов по почте.
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 передавать заголовок с ключом X-Request-ID, содержащий уникальный идентификатор. Формирование идентификатора запроса остается на вашей стороне — это может быть guid, комбинация из номера заказа, даты и суммы или любое другое значение на ваше усмотрение.
Каждый новый запрос, который необходимо обработать, должен включать новое значение X-Request-ID. Обработанный результат хранится в системе в течение 1 часа.
Система сохраняет только успешные результаты запросов.
Для проверки взаимодействия с API можно вызвать тестовый метод по адресу https://api.cloudpayments.kz/test без передачи параметров. В ответ метод возвращает статус запроса.
Пример ответа:
Для оплаты по криптограмме карточных данных необходимо выполнить вызов метода по одному из следующих адресов:
- https://api.cloudpayments.kz/payments/cards/charge — для одностадийного платежа или
- https://api.cloudpayments.kz/payments/cards/auth — для двухстадийного.
Параметры запроса:
Параметр | Формат | Применение | Описание |
Amount | Numeric | Обязательный | Сумма платежа |
Currency | String | Обязательный | Валюта: KZT/RUB/USD/EUR/GBP (см. справочник) |
IpAddress | String | Обязательный | IP адрес плательщика |
Name | String | Обязательный | Имя держателя карты в латинице |
CardCryptogramPacket | String | Обязательный | Криптограмма карточных данных |
InvoiceId | String | Необязательный | Номер счета или заказа |
Description | String | Необязательный | Описание оплаты в свободной форме |
AccountId | String | Необязательный | Идентификатор пользователя |
String | Необязательный | E-mail плательщика на который будет отправлена квитанция об оплате | |
JsonData | Json | Необязательный | Произвольные данные |
В ответ сервер возвращает JSON с тремя составляющими: поле success — результат запроса, поле message — описание ошибки, объект model — расширенная информация.
Возможные варианты:
-
Некорректно сформирован запрос:
success — false
message — описание ошибки -
Требуется 3-D Secure аутентификация:
succes — false
model — информация для проведения аутентификации -
Транзакции отклонена:
success — false
model — информация о транзакции и код ошибки -
Транзакции принята:
success — true
model — информация о транзакции
Пример запроса на оплату по криптограмме:
Пример ответа: некорректный запрос
Пример ответа: требуется 3-D Secure аутентификация
Пример ответа: транзакция отклонена. В поле ReasonCode код ошибки (см. справочник)
Пример ответа: транзакция принята
Для проведения 3-D Secure аутентификации, нужно отправить плательщика на адрес, указанный в параметре AcsUrl ответа сервера с передачей следующих параметров:
- MD — параметр TransactionId из ответа сервера
- PaReq — одноименный параметр из ответа сервера
- TermUrl — адрес на вашем сайте для возврата плательщика после аутентификации
Регистр букв в названии параметров имеет значение.
Пример формы:
После аутентификации, плательщик будет возвращен на TermUrl с параметрами MD и PaRes, переданными методом POST.
Для завершения оплаты необходимо вызвать метод по адресу https://api.cloudpayments.kz/payments/cards/post3ds с передачей следующих параметров:
Параметр | Формат | Применение | Описание |
TransactionId | Int | Обязательный | Значение параметра MD |
PaRes | String | Обязательный | Значение одноименного параметра |
В ответ на корректно сформированный запрос, сервер вернет либо информацию об успешной транзакции, либо — об отклоненной
Для оплаты по токену необходимо выполнить вызов метода по одному из следующих адресов:
- https://api.cloudpayments.kz/payments/tokens/charge — для одностадийного платежа или
- https://api.cloudpayments.kz/payments/tokens/auth — для двухстадийного.
Параметры запроса:
Параметр | Формат | Применение | Описание |
Amount | Numeric | Обязательный | Сумма платежа |
Currency | String | Обязательный | Валюта: KZT/RUB/USD/EUR/GBP (см. справочник) |
AccountId | String | Обязательный | Идентификатор пользователя |
Token | String | Обязательный | Токен |
InvoiceId | String | Необязательный | Номер счета или заказа |
Description | String | Необязательный | Назначение платежа в свободной форме |
IpAddress | String | Необязательный | IP адрес плательщика |
String | Необязательный | E-mail плательщика на который будет отправлена квитанция об оплате | |
JsonData | Json | Необязательный | Произвольные данные |
В ответ сервер возвращает JSON с тремя составляющими: поле success — результат запроса, поле message — описание ошибки, объект model — расширенная информация.
Возможные варианты:
-
Некорректно сформирован запрос:
success — false
message — описание ошибки -
Транзакции отклонена:
success — false
model — информация о транзакции и код ошибки -
Транзакции принята:
success — true
model — информация о транзакции
Пример запроса на оплату по токену:
Пример ответа: некорректный запрос
Пример ответа: транзакция отклонена. В поле ReasonCode код ошибки (см. справочник)
Пример ответа: транзакция принята
Для платежей, проведенных по двухстадийной схеме, необходимо подтверждение оплаты, которое можно выполнить через личный кабинет либо через вызов метода API.
Метод работает по адресу https://api.cloudpayments.kz/payments/confirm и принимает следующие параметры:
Параметр | Формат | Применение | Описание |
TransactionId | Int | Обязательный | Номер транзакции в системе |
Amount | Numeric | Обязательный | Сумма подтверждения в валюте транзакции |
Пример запроса:
Пример ответа:
Отмену оплаты можно выполнить через личный кабинет либо через вызов метода API. Метод работает по адресу https://api.cloudpayments.kz/payments/void и принимает один параметр:
Параметр | Формат | Применение | Описание |
TransactionId | Int | Обязательный | Номер транзакции в системе |
Пример запроса:
Пример ответа:
Возврат денег можно выполнить через личный кабинет либо через вызов метода API. Метод работает по адресу https://api.cloudpayments.kz/payments/refund и принимает следующие параметры:
Параметр | Формат | Применение | Описание |
TransactionId | Int | Обязательный | Номер транзакции оплаты |
Amount | Numeric | Обязательный | Сумма возврата в валюте транзакции |
Пример запроса:
Пример ответа:
Для просмотра информации о транзакции необходимо отправить запрос на адрес https://api.cloudpayments.kz/payments/get с указанием номера интересующей транзакции:
Параметр | Формат | Применение | Описание |
TransactionId | Int | Обязательный | Номер транзакции |
Если транзакция с указанным номером была найдена, система отобразит информацию об ней.
Пример запроса:
Пример ответа:
Для поиска платежа и проверки статуса (см. справочник) необходимо отправить запрос на адрес https://api.cloudpayments.kz/payments/find с указанием номера заказа, по которому была сформирована транзакция:
Параметр | Формат | Применение | Описание |
InvoiceId | String | Обязательный | Номер заказа |
Если платеж по указанному номеру заказа был найден, система отобразит либо информацию об успешной транзакции, либо — об отклоненной. Если будет найдено несколько платежей с указанным номером заказа, то система вернет информацию только о последней операции.
Пример запроса:
Пример ответа:
Проверка статуса платежа является избыточной и имеет смысл только в случае, если при проведении оплаты возник сбой, который привел к потере информации.
Для выгрузки списка транзакций за день необходимо отправить запрос на адрес https://api.cloudpayments.kz/payments/list с указанием даты по которой будут отбираться операции:
Параметр | Формат | Применение | Описание |
Date | Date | Обязательный | Дата создания операций |
TimeZone | String | Необязательный | Код временной зоны, по умолчанию — UTC |
В выгрузку транзакций попадают все операции, зарегистрированные за указанный день. Для удобства учета вы можете указать код временной зоны (см. справочник)
Пример запроса:
Пример ответа:
Для выгрузки списка платежных токенов необходимо отправить запрос на адрес https://api.cloudpayments.kz/payments/tokens/list.
Пример ответ на запрос https://api.cloudpayments.kz/payments/tokens/list:
Для подписки пользователя на рекуррентные платежи, необходимо отправить запрос на адрес https://api.cloudpayments.kz/subscriptions/create с передачей следующих параметров:
Параметр | Формат | Применение | Описание |
Token | String | Обязательный | Токен карты, выданный системой после первого платежа |
AccountId | String | Обязательный | Идентификатор пользователя |
Description | String | Обязательный | Назначение платежа в свободной форме |
String | Обязательный | E-mail плательщика | |
Amount | Numeric | Обязательный | Сумма платежа |
Currency | String | Обязательный | Валюта: KZT/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.kz/subscriptions/get с передачей единственного параметра:
Параметр | Формат | Применение | Описание |
Id | String | Обязательный | Идентификатор подписки |
Пример запроса:
Пример ответа:
Для получения списка подписок для определенного аккаунта, нужно сделать запрос на адрес https://api.cloudpayments.kz/subscriptions/find с передачей единственного параметра:
Параметр | Формат | Применение | Описание |
accountId | String | Обязательный | Идентификатор аккаунта |
Пример запроса:
Пример ответа:
Для изменения ранее созданной подписки, необходимо отправить запрос на адрес https://api.cloudpayments.kz/subscriptions/update с передачей следующих параметров:
Параметр | Формат | Применение | Описание |
Id | String | Обязательный | Идентификатор подписки |
Description | String | Необязательный | Для изменения назначение платежа |
Amount | Numeric | Необязательный | Для изменения суммы платежа |
Currency | String | Необязательный | Для изменения валюты: KZT/RUB/USD/EUR/GBP (см. справочник) |
RequireConfirmation | Bool | Необязательный | Для изменения схемы проведения платежей |
StartDate | DateTime | Необязательный | Для изменения даты и времени первого (или следующего) платежа во временной зоне UTC |
Interval | String | Необязательный | Для изменения интервала. Возможные значения: Week, Month |
Period | Int | Необязательный | Для изменения периода. В комбинации с интервалом, 1 Month значит раз в месяц, а 2 Week — раз в две недели. |
MaxPeriods | Int | Необязательный | Для изменения максимального количества платежей в подписке |
В ответ на корректно сформированный запрос система возвращает сообщение об успешно выполненной операции и параметры подписки.
Пример запроса:
Пример ответа:
Для отмены подписки на рекуррентные платежи, необходимо отправить запрос на адрес https://api.cloudpayments.kz/subscriptions/cancel с передачей следующих параметров:
Параметр | Формат | Применение | Описание |
Id | String | Обязательный | Идентификатор подписки |
В ответ на корректно сформированный запрос система возвращает сообщение об успешно выполненной операции.
Пример запроса:
Пример ответа:
Для формирования ссылки на оплату и последующей отправки уведомления на e-mail адрес плательщика, можно воспользоваться методом https://api.cloudpayments.kz/orders/create с передачей следующих параметров:
Параметр | Формат | Применение | Описание |
Amount | Numeric | Обязательный | Сумма платежа |
Currency | String | Обязательный | Валюта: KZT/RUB/USD/EUR/GBP (см. справочник) |
Description | String | Обязательный | Назначение платежа в свободной форме |
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.kz/site/notifications/{Type}/get с указанием типа уведомления:
Параметр | Формат | Применение | Описание |
Type | String | Обязательный | Тип уведомления: Check/Pay/Fail и т.д. (см. справочник) |
Пример ответа на запрос для Pay уведомления на адрес https://api.cloudpayments.kz/site/notifications/pay/get:
Для изменения настроек уведомлений необходимо отправить запрос на адрес https://api.cloudpayments.kz/site/notifications/{Type}/update с передачей следующих параметров:
Параметр | Формат | Применение | Описание |
Type | String | Обязательный | Тип уведомления: Pay/Fail и т.д. (см. справочник) |
IsEnabled | Bool | Необязательный | Если значение true — то уведомление включено. Значение по умолчанию — false. |
Address | String | Необязательный, если IsEnabled=false, в противном случае обязательный | Адрес для отправки уведомлений (для HTTPS схемы необходим валидный SSL сертификат). |
HttpMethod | String | Необязательный | HTTP метод для отправки уведомлений. Возможные значения: GET, POST. Значение по умолчанию — GET. |
Encoding | String | Необязательный | Кодировка уведомлений. Возможные значения: UTF8, Windows1251. Значение по умолчанию — UTF8. |
Format | String | Необязательный | Формат уведомлений. Возможные значения: CloudPayments, QIWI, RT. Значение по умолчанию — CloudPayments. |
Пример запроса для Pay уведомления на адрес https://api.cloudpayments.kz/site/notifications/pay/update:
Пример ответа:
По умолчанию API выдает сообщения для пользователей на русском языке. Для получения ответов, локализованных для других языков, передайте в параметрах запроса CultureName.
Список поддерживаемых языков:
Язык | Часовой пояс | Код |
Русский | MSK | ru-RU |
Английский | CET | en-US |
Азербайджанский | AZT | az |
Русский | ALMT | kk |