Платежный 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_document_fee Подсчет комиссии на основе параметров документа.
get_documents_history (УСТАРЕВШЕЕ) Получение истории операций.
get_documents_history_ext (АКТУАЛЬНОЕ) Получение истории операций.
documents_search Поиск документов по номеру платежа из вашей системы.
add_payment_notification Отправка получателю уведомления о платеже.
is_verified_account Проверка, верифицирован ли владелец счета.
Работа со счетами
get_accounts Получение списка ваших счетов (кошельков).
get_cashin_requisites Получение реквизитов пополнения счета.
Другое
currency_rates Получение обменных курсов.

Формат ответа

По-умолчанию, ответ возвращается в CSV формате (параметры, разделенные точкой с запятой и переносом строк) в кодировке UTF-8.

Выбор формата ответа

На данный момент поддерживается два формата ответа: json, csv.

Для получения ответа в более удобном формате, необходимо в запросе передать HTTP заголовок 'x-response-format', например

Заголовок Выбранный формат
x-response-format: json Полноценный 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 недоступен пользователю
155 – 160 Ошибки, связанные с регистрацией нового пользователя (операция register_invitee)
155 Пользователь с таким логином уже существует
156 Пользователь с таким адресом электронной почты уже существует
157 Неверный формат логина (логин должен быть длиной от 3 до 16 латинских букв или цифр)
158 Неверный формат адреса электронной почты
159 Неверный формат никнейма (никнейм должкен быть от 3 до 50 латинских букв, цифр, дефисов или знаков подчеркивания)
160 Ошибка в номере телефона (опциональный параметр, должен состоять минимум из 7 цифр, включая международный код страны и населенного пункта)
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

Файлы доступны для скачивания на гитхабе

API Capitalist