Платежный API
API позволяет разработчикам интегрировать свои приложения с системой Capitalist для загрузки платежей в систему в автоматическом режиме.
Требования
Для работы с API, вы должны иметь статус Проверенного бизнес-пользователя. Доступ к API включается после согласования со Службой поддержки.
Все финансовые операции, осуществляемые через API, подписываются при помощи «сертификата безопасности», поэтому для Вашего аккаунта должна быть активирована опция «Cертификат». Активировать опцию можно на странице Настроек безопасности в разделе Профиль.
Необходимые данные для работы с API
- Имя пользователя (не e-mail)
- Пароль
- Файл сертификата
- Пароль к файлу сертификата, если он зашифрован
- Данные массовых платежей в особом формате
Адрес для запросов
https://api.capitalist.net/
Формат запроса
Запрос к API представляет собой обычный HTTP 1.1 POST запрос, в теле которого передаются необходимые параметры. Тип содержимого может быть application/x-www-form-urlencoded либо multipart/form-data.
Обязательные параметры запроса
Запрос должен быть отправлен в кодировке UTF-8.
Для сумм в качестве разделителя целой и десятичной частей используется точка «.».
| Параметр | Описание |
|---|---|
| login | Имя пользователя |
| operation | Имя операции. Например, get_token. |
Работа с нешифрованным паролем
Доступно взаимодействие с API без использования операции get_token и шифрования пароля.
Для этого, в операциях, требующих авторизации, вместо параметров token и encrypted_password необходимо передать нешифрованный пароль в параметре plain_password.
Операции API
На данный момент в API поддерживаются следующие операции:
| Операция | Описание |
|---|---|
| Авторизация | |
| get_token | Получение атрибутов шифрования. |
| Проведение платежей | |
| import_batch_advanced | Загрузка массового платежа в систему с возможностью выбора способа подтверждения. |
| process_batch | Подтверждение массового платежа. |
| get_batch_info | Получение подробной информации по загруженному массовому платежу. |
| get_documents_history_ext | (АКТУАЛЬНОЕ) Получение истории операций. |
| documents_search | Поиск документов по номеру платежа из вашей системы. |
| is_verified_account | Проверка, верифицирован ли владелец счета. |
| Работа со счетами | |
| get_accounts | Получение списка ваших счетов (кошельков). |
| Другое | |
| currency_rates | Получение обменных курсов. |
Формат ответа
По-умолчанию, ответ возвращается в CSV формате(параметры, разделенные точкой с запятой и переносом строк) в кодировке UTF-8.
Выбор формата ответа
На данный момент поддерживается два формата ответа:json,CSV format.
Для получения ответа в более удобном формате, необходимо в запросе передать HTTP заголовок ‘x-response-format’ например:
| Заголовок | Выбранный формат |
|---|---|
| x-response-format: json | A Полноценный JSON с поименованными параметрами |
| x-response-format: csv | CSV выбирается по-умолчанию |
В HTTP заголовках ответа возвращается одноименный заголовок ‘x-response-format’, в котором указан реальный формат ответа. Во всех случаях они совпадают.
Обработка ошибок
По-умолчанию (т.е. для формата ответа CSV), первый параметр первой строки ответа всегда является целым числом (далее для удобства будем называть его Кодом ошибки). Если код ошибки равен нулю, значит операция прошла успешно. В противном случае вторым параметром первой строки идет Текст ошибки. Для формата ответа json Код и Текст ошибки передаются в атрибутах code и message.
Коды ошибок
| Код | Описание |
|---|---|
| 0 | Операция прошла успешно |
| 1 | Системная ошибка |
| 2 | Ошибка выполнения (Необходимо смотреть текст ошибки) |
| 5 | Пользователь не найден |
| 10 | Ошибка, при попытке расшифровать пароль |
| 15 | Передан неверный пароль |
| 16 | Превышено количество попыток входа. Повторите через 30 минут |
| 20 | Передан неверный токен аутентификации |
| 25 | Запрещены запросы информации по пакетным загрузкам с более 1000 записей без постраничной разбивки |
| 110 | Ошибка при проверке подписи |
| 111 | В данных перевода присутствуют недопустимые символы |
| 112 | Превышено ограничение на количество записей в одном массовом платеже |
| 125 | Невозможно разобрать переданный файл |
| 130 | Не найден счет |
| 131 | Нужно передать хотя бы один счет отправителя |
| 132 | Передан пустой массовый платеж |
| 135 | Недостаточно средств на счете для проведения операций |
| 150 | Получен не POST-запрос |
| 151 | Неизвестная операция |
| 152 | API недоступен пользователю |
| 170 | Ошибка создания кошелька |
| 180 | Неизвестный способ подтверждения |
| 181 | Выбранный способ подтверждения неактивен |
| 182 | Отсутствует цифровая подпись |
| 185 | Ошибка импорта массового платежа с несколькими записями (см. ошибку 188). Сумма платежа равна нулю. (см. операцию import_batch_advanced) |
| 186 | Ошибка импорта массового платежа. Детали необходимо уточнить у Службы поддержки. |
| 187 | Ошибка импорта массового платежа по причине временной недоступности одного из типов платежей. Второй строкой возвращается номер ошибочной записи в батче с нумерацией от нуля. |
| 188 | Ошибка импорта массового платежа с одной записью (см. ошибку 185). В качестве текста ошибки возвращается комментарий причины отклонения. |
| 190 – 210 | Ошибки на операции get_document_fee |
| 190 | Неизвестный тип документа |
| 191 | Неизвестный код провайдера услуг |
| 192 | Неизвестный тип банковского платежа (Wire) |
| 193 | Не указан получатель |
| 194 | Счет получателя должен быть вашим |
| 195 | Счет для списания должен быть вашим |
| 196 | Сумма перевода должна быть больше нуля |
| 197 | Не удалось отправить код подтверждения |
| 198 | Неверный код подтверждения |
| 200 | Счет не существует |
| 202 | Переданы неверные данные запроса |
Если вы не нашли описание Кода ошибки, пожалуйста, обратитесь в Службу поддержки.
Примеры работы на PHP
Файлы доступны для скачивания на гитхабе