API для поставщика общие принципы

API построено на основе протокола удаленного вызова процедур JSON-RPC 2.0.

Авторизация и безопасность

Для обеспечения безопасности используется криптографический протокол TLS v1, TLS v1.1 или TLS v1.2.
Для того чтобы авторизоваться, платежный инструмент должен отправить HTTP заголовок Auth.

Структура заголовка Auth

HTTP заголовок: Auth: service_id-hash-timestamp

• hash – sha1(secret_key + timestamp)
  
• timestamp - UTC Время подписания запроса в миллисекундах
  
• service_id – Идентификатор платежного инструмента в системе PaySys. (Выдается при регистрации платежного инструмента)
• secret_key – Ключ платежного инструмента. (Выдается при регистрации платежного инструмента)

Пример HTTP заголовка:
Auth: 05e3bab097f42yu0a62ced0b-7f420a62c22fbe3bab09ed0b57874898-1399114284039

Структура заголовка токена карты

HTTP заголовок Card-Token: token

• token – Токен карты. Выдается при регистрации карты.

Пример HTTP заголовка:
Card-Token: reethaa7ae2jooqee90t2neiloh8wai2jo

RPC Request

RPC Запрос - это JSON объект со следующими полями:

• id - Идентификатор запроса
• method - Имя метода на удаленном сервисе
• params - Необязательный объект с параметрами метода. Если в вызываемом методе нет параметров, поле можно пропустить или присвоить ему значение NULL

ВНИМАНИЕ! В отличие от оригинального стандарта JSON-RPC, поле "params" содержит только именованные параметры.

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

{
  "method": "method.name",
  "params": {
    "param1": "Any String",
    "param2": [
      "list",
      "of",
      "items"
    ]
  },
  "id": "744a0a7a-f33b-4aa6-a609-a8d44206b2d4"
}

RPC Response

RPC Ответ - это JSON объект со следующими полями:

• error - Объект с информацией об ошибке. Если метод выполнился без ошибок праметр будет равен NULL
• result - Объект с результатом выполнения метода
• id - Идентификатор ответа. Значение должно быть то же, что и в запросе

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

{
  "id": "744a0a7a-f33b-4aa6-a609-a8d44206b2d4",
  "error": null,
  "result": {
    "param1": "Any String",
    "param2": [
      {
        "id": 123,
        "title": "item 123"
      },
      {
        "id": 124,
        "title": "item 124"
      }
    ]
  }
}

Пример RPC Request завершенного ошибкой

Ответ содержит:

• code - Код ошибки
• message - Описание ошибки
• data - Дополнительное поле с данными об ошибке. Может не отправляться или содержать объект с произвольными данными

{
  "id": 202,
  "error": {
    "code": -32400,
    "message": "Системная (внутренняя ошибка)",
    "data": {
      "error": 504,
      "message": "Gateway Time Out"
    }
  },
  "result": null
}

Справочные материалы

Таблица кодов ошибок

При возникновении ошибки методы API будут возвращать код и описание ошибки.

Код ошибки	Описание ошибки
-32700	Ошибка Парсинга JSON. RPC запрос является не валидным JSON объектом.
-32600	Передан неправильный JSON-RPC объект
-32601	Запрашиваемый метод не найден.
-32504	Недостаточно привилегий для выполнения метода.
-32400	Системная (внутренняя ошибка). Появляется при различных сбоях.
-32300	Не хватает параметров
-32301	Карта не зарегистрирована
-32302	Не удалось получить информацию о карте
-32303	Неверный формат телефона
-32304	Неверный формат номер карты
-32305	Неверный формат срок действия карты
-32306	Не удалось зарегистрировать карту
-32307	Не удалось сгенерировать токен
-32308	Неверный код или время жизни кода истекло.
-32309	Недостаточно средств
-32310	Карта заблокирована или временно не обслуживается
-32311	Услуга SMS-информирования не включена
-32312	Статус транзакции проведенный
-32313	Статус транзакции отмененный
-32314	Транзакция не найдена
-32315	Сервис заблокирован!
-32316	Не удалось получить информацию о поставщике
-32317	Пользователь или заказ не найден
-32318	Процессинговый центр недоступен
-32319	Поставщик заблокирован!
-32320	Неактуальный запрос, timestamp устарел
-32321	Неверный формат пароля
-32322	Неверный формат код активации
-32323	Недействительная подпись
-32324	Срок действия токена истек
-32325	Пользователь не найден
-32326	Неверный формат ID устройства
-32327	Данный банк не поддерживается
-32328	Сумма меньше допустимой
-32329	Сумма выше допустимой
-32330	Не удалось отменить платеж
-32331	Найден дубликат транзакции
-32332	Сервис временно недоступен
-32333	Данный агент не зарегистрирован в системе PaySys
-32334	Статус транзакции не определен. Обратитесь в службу поддержки !
-32335	Внимание! На сайте ведутся технические работы. Приносим извинения за доставленные неудобства.
-32336	Сервис не настроен. Обратитесь в службу поддержки PaySys!
-32337	Не удалось получить паспортные данные
-32370	Транзакция не может быть завершена. Нарушение закона.
-32371	Срок действия карты истек.
-32372	Неверный формат параметра
-32373	ИНН не совпадает
-32374	Данные не совпадает
-32375	Пользователь не зарегистрированны в ЕЦИС, пройдите регистрацию на сайте Букмекера ЕЦИС
-32376	Пользователь не идентифицирован
-32377	Номер SMS-информирования карты должен совпадать с номером аккаунта
-32378	Неверный формат CVC карты
-32379	Имя владельца карты не может быть пустым
-32380	Данная банковская карта не поддерживается
-32381	Идентификатор заказа не может быть пустым
-32382	IP адрес клиента не может быть пустым
-32383	Детали платежа не может быть пустым
-32384	Статус транзакции является ошибочным
-32385	Не корректные данные карты, проверьте данные или попробуйте другую карту.
-32386	Картодержатель не является участником схемы 3Dsecure
-32387	Карта не входит в интервал 3D-secure карт, указанных на стороне эмитента
-32388	Попытка авторизации держателя карты методом 3D-secure посредством сервера ACS
-32389	Авторизация 3D-secure не доступна
-32390	Отказ (ошибка) при авторизации 3D-secure
-32391	Возвращено сообщение об ошибке со стороны ACS сервера
-32392	Попытка выполнить 3D-secure авторизацию для неизвестного типа карты (Dinners Club, American Express)
-32393	Неудачная авторизация 3D-secure
-32394	3D-secure авторизация закончилась системной ошибкой
-32395	(Отклонение от эмитента) Транзакция не разрешена держателю карты
-32396	Неверный формат номер кошелька
-32397	Не удалось получить информацию о кошельке
-32398	Время ожидания эмитента карты истекло
-32399	Превышение лимита
-32410	Кошелек заблокирован или временно не обслуживается
-32411	(Отклонение от эмитента) Операция нарушает безопасность эмитента.
-32412	Эмитент запрещает проводить операцию через терминал
-32413	Превышен лимит частоты вывода средств (Обратитесь в банк в котором обслуживается ваша карта)
-32415	Эмитент не аутентифицировал транзакцию.
-32416	Не удалось выполнить аутентификацию карты на стороне эмитента.
-32417	Неизвестное устройство, отклонение от эмитента.
-32418	Неподдерживаемое устройство, отклонение от эмитента.
-32419	Превышен лимит частоты аутентификации у эмитента.
-32420	Просроченная карта, в базе данных эмитента.
-32421	Неверный номер карты у эмитента.
-32422	Недействительная транзакция, нужно повторить попытку.
-32423	Операция отклонена. У эмитента не существует данной карты.
-32424	Сбой системы безопасности на стороне МПС.
-32425	Украденная карта, сообщение от эмитента.
-32426	Подозреваемое мошенничество, отклонение эмитента.
-32427	Операция не разрешена держателю карты. Обратитесь в банк, выпустивший карту.
-32428	Держатель карты не зарегистрирован сервисе 3DS, обратитесь к эмитенту.
-32429	Транзакция завершилась по таймеру, сервер эмитента не ответил на операцию.
-32430	Низкое доверие транзакции.
-32431	Среднее доверие транзакции.
-32432	Высокое доверие транзакции.
-32433	Очень высокое доверие транзакции.
-32434	Превышен лимит попыток провести операцию.
-32435	Онлайн оплаты не разрешены на данной карте.
-32436	Транзакция 3RI не поддерживается.
-32437	Техническая проблема сервера на стороне эмитента.
-32438	Раздельная аутентификация требуется ACS, но не запрашивается 3DS Requestor.
-32439	Превышено максимальное время истечения срока действия отключенной аутентификации 3DS Requestor.
-32440	Раздельной аутентификации было предоставлено недостаточно времени для аутентификации держателя карты. ACS не будет предпринимать попытку.
-32441	Попытка провести операцию без участия держателя карты.
-32442	Не удалось зарегистрировать кошелек
-32443	Карта не поддерживает 3DS.
-32444	Транзакция отменена эмитентом.
-32445	На стороне эмитента не включен ACS сервер 3DS 2.2.0.
-32446	Временный сбой системы у эмитента, повторите попытку.
-32447	Эмитент не корректно обработал транзакцию
-32448	Данная карта запрещена для проведения операции, сообщение от МПС.
-32449	Время ожидания платежа истекло!
-32450	Указана неверная учетная запись, нужно обратиться к эмитенту
-32451	Ошибка от эмитента. Без комментариев
-32452	ACS сервер не включен для этой версии, отклонение эмитента
-32453	Не удалось выполнит - аутентификацию/верификацию учетной записи; техническая или иная проблема на стороне эмитента
-32454	Полученный номер версии сообщения, недействителен для принимающего компонента транзакции, обратитесь к эмитенту.
-32455	Карта не подключена к 3DS 2.0
-32456	Запрос отклонен. Найден дубликат запроса