Введение

API mserver использует подход REST. Клиенты API получают доступ к Кошельку, Сервисам, Платежам и Картам выполняя GET, POST и DELETE запросы к соответствующим ресурсам /wallet, /services, /payments и /cards. Вызовы API всегда возвращают JSON. Для возврата статуса запроса к API используется код состояния HTTP.

Аутентификация

Используется BASIC аутентификация. В качестве логина используется номер телефона Кошелька в международном формате.

Возможны следующие коды ошибок, уточняющие HTTP статус 401:

Код ошибки	Описание
`wallet_not_active`	Кошелек не активирован. Активируйте кошелек вызовом POST /wallet/activate.
`wallet_disabled`	Кошелек заблокирован администрацией. Причина блокировки возвращается в поле `details`.
`reset_password`	Требуется смена пароля. Измените пароль вызовами POST /wallet/send_password_reset_code и POST /wallet/reset_password.

Дополнительно реализован протокол OAuth 2.0.

Ошибки

API использует HTTP статусы для возврата ошибок.

Статус	Описание
200	запрос выполнен успешно
400	плохо сформированный запрос (например невалидный JSON)
401	неверные учетные данные
404	запрошенный ресурс не существует (для запрашивающего)
405	не тот HTTP метод, например GET вместо POST
415	не тот content-type, мы поддерживаем только application/json
422	запрос сформирован нормально, но не прошел валидацию, например поле не в нужном формате
5XX	проблема с mserver, повторите запрос позже

HTTP статус дублируется в поле meta.status ответа mserver. В определенных случаях вместе со статусом возвращается уточненный код ошибки в поле meta.error.

Например для неверного формата номера телефона при создании кошелка возвращается

{
  "meta" : {
    "code" : 422,
    "error" : "invalid_phone"
  }
}

Коды ошибок

Код ошибки	Описание
wallet_not_found	кошелек не существует
wallet_not_active	кошелек не активирован
missing_phone	не передан обязательный параметр: номер телефона
missing_password	не передан обязательный параметр: пароль
invalid_password	пароль должен быть не короче 6 символов
invalid_phone	требуется номер телефона в международном формате
phone_already_exists	пользователь с таким номером телефона уже зарегистрирован
already_disabled	пользователь уже заблокирован
already_enabled	пользователь уже разблокирован
already_active	пользователь уже активирован
code_expired	код безопасности устарел
invalid_code	код безопасности не совпадает с отправленным в смс
failure_limit_exceeded	превышен лимит попыток ввода кода безопасности
resend_limit_exceeded	превышен лимит запросов кода безопасности
person_already_verified	персональные данные уже идентифицированы
missing_type	не передан обязательный параметр: тип платежа
missing_amount	не передан обязательный параметр: сумма платежа
missing_parameters	не передан обязательный параметр: параметры платежа
missing_destination	не передан обязательный параметр: кошелек назначения перевода
missing_service	не передан обязательный параметр: сервис назначения платежа
message_too_long	сообщение адресату перевода не должно быть длиннее 1024 символа
invalid_payment_parameters	обязательный параметр платежа не передан или имеет недопустимое значение
invalid_next_action	неверное действие для многошагового платежа (например pay вместо update)
invalid_payment_status	недопустимый статус платежа для действия pay
invalid_amount	недопустимая сумма платежа
card_not_found	карта не существует
service_not_found	сервис не существует
destination_not_found	адресат перевода не существует
invalid_destination	нельзя отправить перевод самому себе
card_not_active	нельзя платить неактивной картой
wallet_not_identified	для совершения этого действия требуется идентификация пользователя кошелька
destination_wallet_not_identified	получатель p2p перевода не идентифицирован
in_amount_limit_exceeded	превышен лимит на сумму пополнения
out_amount_limit_exceeded	превышен лимит на сумму платежа
amount_limit_exceeded	превышен лимит на остаток на счете кошелька
monthly_in_turnover_limit_exceeded	превышен лимит на месячный оборот пополнений
monthly_out_turnover_limit_exceeded	превышен лимит на месячный оборот платежей
active_cards_limit_exceeded	превышен лимит на количество одновременно привязанных карт
insufficient_scope	недостаточно разрешений (scope) OAuth для выполнения запроса

Коды безопасности и контрольный разряд

Для активации созданного кошелька и для смены пароля используется 6-значный цифровой код безопасности, который генерируется случайным образом и отправляется СМС сообщением на телефон кошелька. Запросы на создание кошелька, на повторную отправку кода активации и на отправку кода для смены пароля возвращают в поле check_digit контрольный разряд для сгенерированного кода безопасности, рассчитанный по алгоритму Верхуффа. Клиентские приложения могут использовать контрольный разряд для обнаружения опечаток при вводе кода безопасности.

Постраничный вывод списков

В ответах на запросы, возвращающие список элементов, сервер отдает полное количество элементов в поле meta.page.total_elements.

Срочные данные

Часто изменяющиеся данные, в самых последних значениях которых заинтересован клиент, возвращаются в каждом ответе сервера в поле meta.urgent_data. Например, для API кошельков, возвращается доступный остаток на счете кошелька:

{
  "meta" : {    
    "urgent_data" : {
      "amount" : 10010
    }
}

OAuth

mserver поддерживает протокол OAuth 2.0. Зарегистрированное клиентское приложение может получить токен доступа (access token) по одному из поддерживаемых сценариев (flow):

Веб приложения с бэкэндом должны использовать сценарий с кодом авторизации (authorization code flow).
Мобильный клиент, который сейчас использует BASIC аутентификацию паролем может использовать сценарий с паролем пользователя (password flow).

Токен доступа

После успешной OAuth авторизации клиентское приложение получает токен доступа вида b48a991e-e010-4329-9817-f8389a774c45, который может использовать для обращения к API от имени пользователя кошелька.

Время жизни токена зависит от настроек регистрации приложения в mserver. С токеном связан набор разрешений, предоставленных пользователем приложению. При попытке выполнить неразрешенное действие клиентское приложение получит статус HTTP 403, insufficient_scope в поле meta.error ответа и идентификатор разрешения, которого не хватило, в поле meta.details.

Успешная аутентификация токеном доступа

$ curl -H "Authorization: Bearer b48a991e-e010-4329-9817-f8389a774c45" https://www.synq.ru/mserver2-dev/v1/wallet

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10098.98
    }
  },
  "data" : {
    "phone" : "+79261111111",
    "amount" : 10098.98,
    "lock_message" : "t",
    "name" : "Васян Петров",
    "verified" : true,
    "person_status" : "data_verified"
  }
}

Попытка выполнить неразрешенное пользователем действие

curl -H "Authorization: Bearer b48a991e-e010-4329-9817-f8389a774c45" https://www.synq.ru/mserver2-dev/v1/wallet/person

{
  "meta" : {
    "code" : 403,
    "error" : "insufficient_scope",
    "details" : "person.read"
  }
}

Сценарий с кодом авторизации

Клиентское приложение перенаправляет клиента на URL авторизации вида https://www.synq.ru/mserver2-dev/oauth/authorize?response_type=code&client_id=mbank_web&scope=wallet.read payments.read&redirect_uri=https://bestmt.ru/test?ok=1
Происходит перенаправление на страницу логина https://www.synq.ru/mserver2-dev/login
Пользователь кошелька вводит логин и пароль и нажимает “Войти”
Пользователь кошелька выбирает, какие из запрошенных разрешений он согласен предоставить приложению и нажимает “Продолжить”
Происходит перенаправление на страницу с кодом авторизации https://bestmt.ru/test?ok=1&code=QnHgkv
Бэкэнд клиентского приложения обменивает код авторизации на токен доступа POST запросом к сервису токенов mserver /oauth/token.

Параметры URL авторизации

response_type - обязательно, фиксированное значение, равное code
client_id - обязательно, зарегистрированный в mserver ID приложения, которое запрашивает доступ
scope - опционально, перечень запрашиваемых разрешений, разделенный пробелами, если ничего не передано, то будут запрошены все разрешения
redirect_uri - опционально, URI на который пользователь будет перенаправлен в случае успешной авторизации, должен быть зарегистрирован в mserver

Параметры запроса к сервису токенов для authorization code flow

grant_type - обязательно, фиксированное значение authorization_code
‘code’ - обязательно, код авторизации, полученный из URL перенаправления
redirect_uri - опционально, если был задан параметр redirect_uri в URL авторизации
client_id - обязательно, зарегистрированный в mserver ID приложения, которое запрашивает доступ

Обмен кода авторизации на токен доступа

curl -H "Accept: application/json" -u mbank_web:topsecret https://www.synq.ru/mserver2-dev/oauth/token -d "grant_type=authorization_code&code=xT53tR&redirect_uri=https://bestmt.ru/test?ok=1&client_id=mbank_web"

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10098.98
    }
  },
  "data" : {
    "access_token" : "b48a991e-e010-4329-9817-f8389a774c45",
    "token_type" : "bearer",
    "expires_in" : 2147483253,
    "scope" : "payments.read wallet.read"
  }
}

Сценарий с передачей пароля

Для замены старой схемы аутентификации в мобильном приложении кошелька может быть использован сценарий password flow, при котором бэкэнд приложения обращается к mserver, чтобы обменять учетные данные приложения и пользователя кошелька (client_id, client_secret, username, password) на токен доступа.

Параметры запроса к сервису токенов для password flow

grant_type - обязательно, фиксированное значение password
scope - опционально, перечень запрашиваемых разрешений, разделенный пробелами, если ничего не передано, то будут запрошены все разрешения
username - обязательно, имя пользователя кошелька (номер телефона в международном формате)
password - обязательно, пароль пользователя кошелька

Учетные данные (client_id и client_secret) зарегистрированного клиентского приложения, от имени которого запрашивается токен доступа, передаются BASIC аутентификацией.

Обмен пароля пользователя кошелька на токен доступа

curl -H "Accept: application/json" -u mbank:secret https://www.synq.ru/mserver2-dev/oauth/token -d "grant_type=password&scope=cards.read&username=%2B79201111111&password=password"

{
  "meta" : {
    "code" : 200
  },
  "data" : {
    "access_token" : "6a1c96df-662c-4d1d-b046-a7a4ad14b159",
    "token_type" : "bearer",
    "expires_in" : 3599,
    "scope" : "cards.read"
  }
}

Разрешения

Разрешение	Описание	Разрешенные запросы API
wallet.read	Просмотр кошелька	GET /v1/wallet
person.read	Просмотр персональных данных	GET /v1/wallet/person
person.modify	Задание персональных данных	POST /v1/wallet/person
cards.read	Просмотр сохраненных карт	GET /v1/cards
cards.modify	Сохранение/удаление карты	POST DELETE /v1/cards
payments.read	Просмотр истории платежей	GET /v1/payments
payments.modify	Совершение платежа	POST /v1/payments

Тестовые приложения

client_id	client_secret	Разрешенные сценарии	URL перенаправления	Время жизни токена, секунды
mbank	secret	password		3600
mbank_web	topsecret	authorization_code	http://refill.dev http://refill.nebo15.me http://mbank.dev http://schet.dev http://schet.nebo15.me http://schet.ru	2147483647
mbank_storefront	oklol	client_credentials	http://refill.dev http://refill.nebo15.me http://mbank.dev http://schet.dev http://schet.nebo15.me http://schet.ru	2147483647
mbank_bov	secret	password		3600

Кошелек

Кошелек - учетная запись конечного пользователя в mserver. Позволяет получать информацию о доступном остатке на счете и персональных данных конечного пользователя.

Пример

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10010
    }
  },
  "data" : {    
    "phone" : "+79261111111",    
    "amount" : 0,
    "level" : "anonymous",
    "name" : "Алексей Арсеньев",
    "verified" : false,
    "person_status" : "data_entered"
  }
}

Поля

phone - номер телефона в международном формате, уникальный идентификатор Кошелька (в пределах Проекта), также является логином
amount - остаток на счете кошелька, в рублях
name - имя конечного пользователя, возвращается в случае, если были заданы имя и/или фамилия
verified - true|false статус идентификации пользователя
level - anonymous | identified | personified уровень идентификации пользователя
person_status - no_data | data_entered | data_verified статус персональных данных пользователя

Создание кошелька

Параметры

phone - номер телефона в международном формате
password - пароль, не короче 6 символов

$ curl -H 'Content-type:application/json'
 -d '{"phone": "+79261111111", "password": "password"}'
 https://www.synq.ru/mserver2-dev/v1/wallet

{
  "meta" : {
    "code" : 200
  },
  "data" : {
    "phone" : "+79261111111",
    "check_digit" : "8" 
  },
  "dev" : {
    "security_code" : "242321"
  }
}

Коды ошибок

missing_phone - не передан номер телефона
invalid_phone - номер телефона не соответствует международному формату
missing_password - не передан пароль
invalid_password - пароль короче 6 символов
phone_already_exists - кошелек с таким номером телефона уже существует (и активирован)
wallet_not_active - кошелек с таким номером телефона уже существует и его нужно активировать кодом из СМС

После создания кошелька требуется активация (подтверждение номера телефона) кодом, который отправлен в СМС сообщении. До выполнения активации аутентифицироваться на mserver учетными данными кошелька будет нельзя. Сервер будет возвращать HTTP статус 401 с кодом ошибки wallet_not_active.

Ошибка до активации кошелька

{
  "meta" : {
    "code" : 401,
    "error" : "wallet_not_active"
  }
}

Активация кошелька

Параметры

phone - номер телефона в международном формате
code - код активации кошелька из СМС сообщения

$ curl -H 'Content-type:application/json'  
 -d '{"phone": "+79261111111", "code": "242321"}' 
 https://www.synq.ru/mserver2-dev/v1/wallet/activate

{
  "meta" : {
    "code" : 200
  },
  "data" : {
    "phone" : "+79261111111"
  }
}

Коды ошибок

missing_phone - не передан номер телефона
invalid_phone - номер телефона не соответствует международному формату
missing_code - не передан код активации
already_active - кошелек с телефоном phone уже активирован
invalid_code - переданный код активации не совпадает с присланным в СМС
code_expired - с момента создания кода активации прошло больше 15 минут, запросите код повторно
failure_limit_exceeded - вы прислали неверный код активации больше 5 раз, обратитесь в поддержку

Запрос повторной отправки кода активации

Параметры

phone - номер телефона в международном формате

curl -H 'Content-type:application/json'
 -d '{"phone": "+79261111111"}' 
 https://www.synq.ru/mserver2-dev/v1/wallet/resend_code

{
  "meta" : {
    "code" : 200
  },
  "data" : {
    "phone" : "+79261111111",
    "check_digit" : "3"
  },
  "dev" : {
    "security_code" : "482721"
  }
}

Коды ошибок

missing_phone - не передан номер телефона
invalid_phone - номер телефона не соответствует международному формату
already_active - кошелек с телефоном phone уже активирован
failure_limit_exceeded - вы прислали неверный код активации больше 5 раз, обратитесь в поддержку
resend_limit_exceeded - mserver отправил отведенные 5 СМС сообщений с кодами активации, обратитесь в поддержку

Запрос кода для смены пароля

$ curl -H 'Content-type:application/json' 
 -d '{"phone": "+79261111111"}'
 https://www.synq.ru/mserver2-dev/v1/wallet/send_password_reset_code

{
  "meta" : {
    "code" : 200
  },
  "data" : {
    "phone" : "+79261111111",
    "check_digit" : "1"
  },
  "dev" : {
    "security_code" : "934879"
  }
}

Коды ошибок

failure_limit_exceeded - вы прислали неверный код смены пароля больше 5 раз, обратитесь в поддержку
resend_limit_exceeded - mserver отправил отведенные 5 СМС сообщений с кодами смены пароля, обратитесь в поддержку
wallet_not_active - кошелек не активирован
wallet_disabled - кошелек заблокирован

Смена пароля

$ curl -H 'Content-type:application/json' 
 -d '{"code": "934879", "password": "PassWord", "phone": "+79261111111"}' ttps://www.synq.ru/mserver2-dev/v1/wallet/reset_password

{
  "meta" : {
    "code" : 200
  },
  "data" : {
    "phone" : "+79261111111"
  }
}

Коды ошибок

missing_code - не передан код смены пароля
invalid_code - переданный код смены пароля не совпадает с присланным в СМС
code_expired - с момента создания кода смены пароля прошло больше 15 минут, запросите код повторно
failure_limit_exceeded - вы прислали неверный код смены пароля больше 5 раз, обратитесь в поддержку
wallet_not_active - кошелек не активирован
wallet_disabled - кошелек заблокирован

Загрузка кошелька

$ curl -u+79261111111:password https://www.synq.ru/mserver2-dev/v1/wallet

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10010
    }
  },
  "data" : {    
    "phone" : "+79261111111",
    "amount" : 0,
    "name" : "Алексей Арсеньев",
    "verified" : false,    
    "level" : "anonymous",
    "person_status" : "data_entered"
  }
}

Поиск кошельков

$ curl -u+79261111111:password -H 'Content-type:application/json' 
-d '{"phones": ["+79990000000", "+79260000001", "+79260000002"]}' 
https://www.synq.ru/mserver2-dev/v1/wallet/find

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10010
    }
  },
  "data" : [ {
    "phone" : "+79260000001"
  }, {
    "phone" : "+79260000002"
  } ]
}

Задание персональных данных пользователя

Параметры

family_name - фамилия
given_name - имя
patronymic_name - отчество
birth_date - дата рождения в формате гггг-мм-дд
passport_series_number - серия и номер паспорта, 10 цифр
passport_issued_at - дата в формате гггг-мм-дд
itn - ИНН, 12 цифр
ssn - СНИЛС, 11 цифр

$ curl -u+79261111111:password -H 'Content-type:application/json' 
-d '{"family_name": "Арсеньев", "given_name": "Алексей", "patronymic_name": "Александрович", 
"birth_date": "1982-01-02", "passport_series_number": "2202655885", "passport_issued_at" : "2012-02-27", 
"itn": "330500938709", "ssn": "11223344595"}'  
https://www.synq.ru/mserver2-dev/v1/wallet/person

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10010
    }
  },
  "data" : {
    "family_name" : "Арсеньев",
    "given_name" : "Алексей",
    "patronymic_name" : "Александрович",
    "birth_date" : "1982-01-02",
    "passport_series_number" : "2202655885",
    "passport_issued_at" : "2012-02-27",
    "itn" : "330500938709",                       
    "ssn" : "11223344595",                        
    "status" : "data_entered"
  }
}

Коды ошибок

invalid_family_name - фамилия длиннее 512 символов
invalid_given_name - имя длиннее 512 символов
invalid_patronymic_name - отчество длиннее 512 символов
invalid_passport_series_number - серия/номер паспорта не соответствует формату
invalid_itn - ИНН не соответствует формату
invalid_ssn - СНИЛС не соответствует формату
person_already_verified - перcональные данные утверждены, изменение невозможно, обратитесь в поддержку

Загрузка персональных данных пользователя

$ curl -u+79261111111:password https://www.synq.ru/mserver2-dev/v1/wallet/person

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10010
    }
  },
  "data" : {
    "family_name" : "Арсеньев",
    "given_name" : "Алексей",
    "patronymic_name" : "Александрович",
    "birth_date" : "1982-01-02",
    "passport_series_number" : "2202655885",
    "passport_issued_at" : "2012-02-27",
    "itn" : "330500938709",
    "ssn" : "11223344595",
    "status" : "data_verified",
    "verified_at" : "2014-05-29T17:06:20.066Z"
  }
}

Статусы персональных данных

Код статуса ПД	Описание
`data_entered`	Персональные данные введены пользователем, изменение ПД возможно
`data_verified`	Персональные данные проверены, дальнейшее изменение ПД невозможно

Запрос персональных данных клиента системы БЭСТ

Возвращает список наборов персональных данных клиента системы денежных переводов БЭСТ полученный поиском по номеру телефона кошелька, либо по номеру карты клиента БЭСТ. Одному номеру телефона в системе БЭСТ может соответствовать более одного набора персональных данных.

Параметры

card_number - номер карты клиента БЭСТ
pin - PIN код

Запрос по номеру телефона кошелька

$ curl -u+79261111111:password https://www.synq.ru/mserver2-dev/v1/wallet/client

Запрос по номеру карты клиента БЭСТ

$ curl -u+79261111111:password https://www.synq.ru/mserver2-dev/v1/wallet/client?card_number=8003330316000271&pin=1234

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 18.51
    },
    "page" : {
      "total_elements" : 1
    }
  },
  "data" : [ {
    "data" : {
      "lastname" : "Арсеньев",
      "firstname" : "Алексей",
      "patronymic" : "Александрович",
      "account" : "",
      "isresident" : 1,
      "id_card" : "8003330316000271",
      "id_client" : 147
    },
    "address" : {
      "street" : "",
      "house" : "",
      "house_block" : "",
      "house_building" : "",
      "flat" : "",
      "phone" : "79261111111",
      "email" : ""
    },
    "data_extended" : {
      "inn" : "",
      "birth_day" : "1982-01-01T21:00:00.000+0000",
      "birth_place" : "Город Орёл Орловской области",
      "migration_card_number" : ""
    },
    "identification" : {
      "type" : "Паспорт гражданина Российской Федерации_",
      "series" : "2202",
      "number" : "655885",
      "issuer" : "Отделом УФМС России по гор Орёл",
      "issue_date" : "2013-02-06T20:00:00.000+0000",
      "dep_code" : ""
    }
  }]
}

Сервисы

Сервис - это назначение платежа. Сервис содержит описание параметров, которые должны быть переданы в платежном запросе конечным пользователем.

Пример

{
    "id" : 9,
    "name" : "Альфа Банк",
    "min" : 10,
    "max" : 15000,
    "verification_required": true,
    "parameters" : [ {
      "code" : "phoneNumber",
      "min_length" : 16,
      "max_length" : 16,
      "name" : "№ карты (16 цифр)",
      "pattern" : "^\\d{16}$",
      "type" : "numeric",
      "pattern_description" : "№ карты (16 цифр)",
      "items" : [ ]
}

Поля

id - идентификатор сервиса, передается в платежном запросе в поле service для указания назначения платежа
name - человекочитаемое имя сервиса
min, max - минимальная и максимальная сумма платежа, включительно
verification_required - true | false требуется ли идентификация плательщика
parameters.code - ключ параметра платежа
min_length, max_length - минимальная и максимальная длина значения параметра платежа
name - человекочитаемое имя параметра
pattern - регулярное выражение, которому должно удовлетворять значение параметра платежа
pattern_description - человекочитаемое описание для pattern
type - numeric|text|enum тип параметра платежа, число/текст/перечисление
items - возможные значения параметра платежа с типом enum

Загрузка списка сервисов

$ curl -u+79261111111:password https://www.synq.ru/mserver2-dev/v1/services

 {
   "meta" : {
     "total_elements" : 23,
     "code" : 200,
    "urgent_data" : {
      "amount" : 10010
    }

   },
   "data" : [ {
     "id" : 9,
     "name" : "Альфа Банк",
     "min" : 10,
     "max" : 15000,
     "verification_required" : false,
     "parameters" : [ {
       "code" : "phoneNumber",
       "min_length" : 16,
       "max_length" : 16,
       "name" : "№ карты (16 цифр)",
       "pattern" : "^\\d{16}$",
       "type" : "numeric",
       "pattern_description" : "№ карты (16 цифр)",
       "items" : [ ]
     }, {
       "code" : "valid",
       "name" : "Срок действия (вид: ГГММ)",
       "pattern" : "^\\d{4}$",
       "type" : "text",
       "pattern_description" : "Срок действия (вид: ГГММ)",
       "items" : [ ]
     } ]
   } ]
 }

Загрузка сервиса по идентификатору

$ curl -u+79261111111:password https://www.synq.ru/mserver2-dev/v1/services/1

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10010
    }

  },
  "data" : {
    "id" : 1,
    "name" : "Мегафон",
    "min" : 1,
    "max" : 15000,
    "verification_required" : false,
    "parameters" : [ {
      "code" : "phoneNumber",
      "min_length" : 10,
      "max_length" : 10,
      "name" : "№ телефона (10 цифр)",
      "pattern" : "^\\d{10}$",
      "type" : "numeric",
      "pattern_description" : "№ телефона (10 цифр)",
      "items" : [ ]
    } ]
  }
}

Сервисы по группам

$ curl -u+79261111111:password https://www.synq.ru/mserver2-dev/v1/services/groups

{
  "meta" : {
    "total_elements" : 23,
    "code" : 200,
    "urgent_data" : {
      "amount" : 10010
    }

  },
  "data" : [ {
    "code" : "bank",
    "name" : "Банковские услуги",
    "services" : [ {
      "id" : 9,
      "name" : "Альфа Банк",
      "min" : 10,
      "max" : 15000,
      "verification_required" : false,
      "parameters" : [ {
        "code" : "phoneNumber",
        "min_length" : 16,
        "max_length" : 16,
        "name" : "№ карты (16 цифр)",
        "pattern" : "^\\d{16}$",
        "type" : "numeric",
        "pattern_description" : "№ карты (16 цифр)",
        "items" : [ ]
      }, {
        "code" : "valid",
        "name" : "Срок действия (вид: ГГММ)",
        "pattern" : "^\\d{4}$",
        "type" : "text",
        "pattern_description" : "Срок действия (вид: ГГММ)",
        "items" : [ ]
      } ]
    } ]
  } ]
}

Поиск подходящего сервиса по номеру карты или телефона

Поля

type - phone | card тип поиска
input - номер карты или телефона

Пример поиска по номеру карты

$ curl -u+79261111111:password https://www.synq.ru/mserver2-dev/v1/services/search?type=card&input=5417150970409149

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

$ curl -u+79261111111:password "https://www.synq.ru/mserver2-dev/v1/services/search?type=phone&input=9099560000"

Пример возвращаемых данных

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    }
  },
  "data" : [ {
    "id" : 3,
    "name" : "Билайн",
    "min" : 2,
    "max" : 15000,
    "verification_required" : false,
    "parameters" : [ {
      "code" : "phoneNumber",
      "min_length" : 10,
      "max_length" : 10,
      "name" : "Номер телефона",
      "type" : "numeric",
      "pattern_description" : "10-ти значный федеральный номер",
      "items" : [ ]
    } ]
  } ]
}

Платежи

Платеж - это операция движения денежных средств между счетами mserver выполняемая по распоряжению пользователя. Платежи различаются по типу:

Код типа платежа	Описание
`out`	Вывод средств со счета кошелька пользователя в пользу провайдера (провайдер КредитПилот)
`p2p`	Перевод денег со счета кошелька пользователя на счет кошелька другого пользователя
`in`	Ввод средств на счет кошелька пользователя через провайдера (провайдеры КредитПилот, ИПСП, Рапида)
`inout`	Транзит средств от ИПСП в пользу КредитПилот

Поля, общие для всех типов платежей

type - in|out|p2p|inout тип Платежа
client_payment_id - клиентский идентификатор (UUID)
amount - сумма к зачислению в рублях
total - полная сумма Платежа с учетом комиссии в рублях
createdAt - время создания
processedAt - время завершения online обработки
status - состояние
decline_reason - причина отказа в проведении

Поля для платежей типа `out` / `inout` (вывод денег / транзит)

service - назначение платежа
outbound - провайдер, на счет которого были отправлены деньги со счете кошелька
parameters - параметры платежа, например номер карты/телефона

Поля для типа `in` / `inout` (ввод денег / транзит)

inbound - провайдер, со счета которого деньги пришли на счет кошелька
card - карта с которой прошло пополнение

Поля для типа `p2p` (перевод между кошельками)

destination - кошелек назначения перевода
message - сообщение адресату перевода

Статусы платежа

Код статуса платежа	Описание
`created`	Платеж создан (например вызовом POST /payments) и ожидает от клиента команды на исполнение
`processing`	Платеж был запущен в обработку (например вызовом POST /payments/{id}/pay и исполняется
`completed`	Платеж успешно исполнен
`declined`	Платеж отклонен, с уточнением причины в поле `decline_reason`

Причины отказа в проведении платежа

Код причины отказа	Описание
`invalid_data`	Неверные данные платежа (например неверный номер карты/номер телефона)
`insufficient_funds`	Недостаточно средств на счете кошелька
`internal_error`	Что-то пошло не так, обратитесь в поддержку

Клиентский идентификатор платежа

Клиент может генерировать UUID для каждого отдельного платежа и передавать его в поле client_payment_id платежного запроса. Если в процессе создания платежа такой клиент получил ошибку I/O, он должен повторять запрос создания платежа с тем же самым client_payment_id до получения ответа. Гарантируется, что платеж с данным client_payment_id будет создан не более 1 раза.

Проведение платежа

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

проведение платежа

Получение истории платежей

$ curl -u+79261111111:password "https://www.synq.ru/mserver2-dev/v1/payments?page=0&size=35&type=out,in&status=completed,declined"

Параметры page и size в запросе позволяют задать номер (начиная с 0) и размер страницы, которую запрашивает клиент. По умолчанию номер страницы - 0 и размер страницы - 35 платежей. Опциональные параметры type и status позволяют фильтровать платежи по типу и статусу.

{
  "meta" : {
    "page" : {
      "total_elements" : 15
    },
    "code" : 200,
    "urgent_data" : {
      "amount" : 10010
    }

  },
  "data" : [ {
    "id" : 1401089238188,
    "client_payment_id" : "e131a7e2-c553-4295-867e-1023359bee31",
    "amount" : 2,
    "total" : 5.01,
    "created_at" : "2014-07-08T16:08:56.536Z",
    "status" : "declined",
    "type" : "out",
    "service" : {
      "id" : 15,
      "name" : "MTS Украина"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ телефона (9-10 цифр)",
      "value" : "0509244604"
    } ],
    "outbound" : {
      "id" : 35,
      "code" : "tpr_out",
      "name" : "ООО ТПР (провайдер)"
    }
  }, {
    "id" : 1401089238187,
    "client_payment_id" : "e731a7e2-c553-4295-867e-1023359bee31",
    "amount" : 2,
    "total" : 5.01,
    "created_at" : "2014-07-08T16:05:40.110Z",
    "processed_at" : "2014-07-08T16:07:41.435Z",
    "status" : "completed",
    "type" : "out",
    "service" : {
      "id" : 15,
      "name" : "MTS Украина"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ телефона (9-10 цифр)",
      "value" : "0509244604"
    } ],
    "outbound" : {
      "id" : 35,
      "code" : "tpr_out",
      "name" : "ООО ТПР (провайдер)"
    }
  }, {
    "id" : 1401089238186,
    "client_payment_id" : "1331a7e2-c553-4295-867e-1023359bee38",
    "amount" : 1,
    "total" : 4.01,
    "created_at" : "2014-07-08T15:14:42.620Z",
    "status" : "declined",
    "decline_reason" : "internal_error",
    "type" : "out",
    "service" : {
      "id" : 15,
      "name" : "MTS Украина"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ телефона (9-10 цифр)",
      "value" : "1509244604"
    } ],
    "outbound" : {
      "id" : 35,
      "code" : "tpr_out",
      "name" : "ООО ТПР (провайдер)"
    }
  }, {
    "id" : 1401089238185,
    "client_payment_id" : "1231a7e2-c553-4295-867e-1023359bee38",
    "amount" : 1,
    "total" : 4.01,
    "created_at" : "2014-07-08T15:13:28.298Z",
    "status" : "declined",
    "decline_reason" : "internal_error",
    "type" : "out",
    "service" : {
      "id" : 15,
      "name" : "MTS Украина"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ телефона (9-10 цифр)",
      "value" : "0509244604"
    } ],
    "outbound" : {
      "id" : 35,
      "code" : "tpr_out",
      "name" : "ООО ТПР (провайдер)"
    }
  }, {
    "id" : 1401089238184,
    "client_payment_id" : "1731a7e2-c553-4295-867e-1023359bee38",
    "amount" : 1,
    "total" : 4.01,
    "created_at" : "2014-07-08T15:11:19.489Z",
    "status" : "declined",
    "type" : "out",
    "service" : {
      "id" : 15,
      "name" : "MTS Украина"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ телефона (9-10 цифр)",
      "value" : "0509244604"
    } ],
    "outbound" : {
      "id" : 35,
      "code" : "tpr_out",
      "name" : "ООО ТПР (провайдер)"
    }
  }, {
    "id" : 1401089238183,
    "client_payment_id" : "e731a7e2-c553-4295-867e-1023359bee34",
    "amount" : 1,
    "total" : 4.01,
    "created_at" : "2014-07-08T14:58:52.154Z",
    "status" : "declined",
    "type" : "out",
    "service" : {
      "id" : 15,
      "name" : "MTS Украина"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ телефона (9-10 цифр)",
      "value" : "0509244604"
    } ],
    "outbound" : {
      "id" : 35,
      "code" : "tpr_out",
      "name" : "ООО ТПР (провайдер)"
    }
  }, {
    "id" : 1401089238182,
    "client_payment_id" : "e731a7e2-c553-4295-867e-1023359bee38",
    "amount" : 1,
    "total" : 4.01,
    "created_at" : "2014-07-08T14:56:39.222Z",
    "status" : "declined",
    "type" : "out",
    "service" : {
      "id" : 15,
      "name" : "MTS Украина"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ телефона (9-10 цифр)",
      "value" : "0509244604"
    } ],
    "outbound" : {
      "id" : 35,
      "code" : "tpr_out",
      "name" : "ООО ТПР (провайдер)"
    }
  }, {
    "id" : 1401089238181,
    "client_payment_id" : "e731a7e2-c553-4295-867e-1023359bee28",
    "amount" : 1,
    "total" : 4.01,
    "created_at" : "2014-07-08T14:25:44.646Z",
    "processed_at" : "2014-07-08T14:26:55.029Z",
    "status" : "completed",
    "type" : "out",
    "service" : {
      "id" : 15,
      "name" : "MTS Украина"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ телефона (9-10 цифр)",
      "value" : "0509244604"
    } ],
    "outbound" : {
      "id" : 35,
      "code" : "tpr_out",
      "name" : "ООО ТПР (провайдер)"
    }
  } ]
}

Уведомления об изменении статуса платежа

Для уведомления внешней системы об изменениях статуса платежа mserver выполняет POST запрос на URL /payments/status. Уведомление передается в теле POST запроса в виде объекта платежной операции сериализованного в JSON. Например:

{
  "created_at" : "2014-08-02T14:37:20.102Z",
  "payment" : {
    "id" : 1401089240253,
    "client_payment_id" : "a02b1416-b9c1-4782-88c5-da4d78b32f8d",
    "amount" : 1,
    "total" : 1,
    "created_at" : "2014-08-02T14:36:02.997Z",
    "processed_at" : "2014-08-02T14:37:20.102Z",
    "status" : "completed",
    "type" : "in",
    "inbound" : {
      "id" : 62,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "card" : {
      "state" : "used",
      "title" : "541715******2399",
      "type" : "MasterCard"
    }
  },
  "from" : "processing",
  "to" : "completed",
  "type" : "complete"
}

Поля

created_at - момент времени совершения платежной операции
payment - стандартное представление объекта платежа описанное выше
from - начальный статус платежа
to - конечный статус платежа
type - тип платежной операции, см. ниже

Типы платежных операций

Тип	Описание
`complete`	Платеж проведен
`decline`	Платеж отклонен
`undo`	Отмена ранее успешного платежа (сторно)
`redo`	Ранее отмененный платеж сделан успешным (сторно сторно and we need to go deeper)

Платеж со счета кошелька

Параметры

type = out - тип платежа
client_payment_id - клиентский идентификатор платежа (опциональный)
amount - сумма к зачислению
service - назначение платежа, идентификатор Сервиса
parameters - параметры платежного запроса в соответствии с /services/{service}

$ curl -u+79261111111:password -H 'Content-type:application/json' 
 -d '{"type": "out", "client_payment_id": "e731a7e2-c553-4295-867e-1023359bee28", 
 "amount": 100, "service": 61, "parameters": {"phoneNumber": "9267101283", 
 "BIK": "044583151", "Name": "name", "SName": "sname", "Fam": "fam"}}' 
 https://www.synq.ru/mserver2-dev/v1/payments

{
  "meta" : {
    "code" : 200,
    "next_action" : "get",
    "urgent_data" : {
      "amount" : 10010
    }

  },
  "data" : {
    "id" : 1401089234883,
    "client_payment_id" : "e731a7e2-c553-4295-867e-1023359bee28",
    "amount" : 100,
    "created_at" : "2014-05-26T15:15:07.389Z",
    "status" : "processing",
    "type" : "out",
    "service" : {
      "id" : 61,
      "name" : "Мультибанк"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона (10 цифр)",
      "value" : "9267101283"
    }, {
      "code" : "BIK",
      "name" : "БИК",
      "value" : "044583151"
    }, {
      "code" : "Name",
      "name" : "Имя Отправителя",
      "value" : "name"
    }, {
      "code" : "SName",
      "name" : "Отчество Отправителя",
      "value" : "sname"
    }, {
      "code" : "Fam",
      "name" : "Фамилия Отправителя",
      "value" : "fam"
    } ],
    "outbound" : {
      "id" : 35,
      "code" : "tpr_out",
      "name" : "ООО ТПР (провайдер)"
    }
  }
}

Коды ошибок

missing_type - отсутствует обязательный параметр type
missing_client_payment_id - отсутствует обязательный параметр client_payment_id
missing_amount - отсутствует обязательный параметр amount
invalid_amount - неверная сумма платежа, должно быть min <= amount <= max, где min и max - минимальная и максимальная сумма для Сервиса
missing_service - отсутствует обязательный параметр service
service_not_found - запрошенный сервис не найдет
missing_parameters - не передан обязательный параметр parameters

Перевод между кошельками

Параметры

type = p2p - тип платежа
client_payment_id - клиентский идентификатор платежа
amount - сумма перевода
destination - кошелек назначения перевода
message - сообщение адресату перевода (опционально)

$ curl -u+79261111111:password -H 'Content-type:application/json' 
 -d '{"type": "p2p", "client_payment_id": "071c6d23-7508-4e35-ad92-852308a47677", "amount": 100, "destination": "+79261111112", "message": "Съешь ещё этих мягких французских булок, да выпей чаю"}'   https://www.synq.ru/mserver2-dev/v1/payments

{
  "meta" : {
    "code" : 200,
    "next_action" : "pay",
    "urgent_data" : {
      "amount" : 10010
    }

  },
  "data" : {
    "id" : 1401089237211,
    "client_payment_id" : "071c6d23-7508-4e35-ad92-852308a47677",
    "amount" : 100,
    "total" : 100.00,
    "created_at" : "2014-07-01T06:30:01.277Z",
    "status" : "created",
    "type" : "p2p",
    "destination" : {
      "phone" : "+79261111112"
    },
    "message" : "Съешь ещё этих мягких французских булок, да выпей чаю"
  }
}

Коды ошибок

missing_type - отсутствует обязательный параметр type
missing_client_payment_id - отсутствует обязательный параметр client_payment_id
missing_amount - отсутствует обязательный параметр amount
invalid_amount - сумма перевода должна быть > 0
missing_destination - отсутствует обязательный параметр destination
destination_not_found - кошелек назначения платежа не найден
invalid_destination - попытка отправить p2p перевод самому себе
insufficient_funds - недостаточно средств для выполнения p2p перевода
wallet_not_identified - отправитель p2p перевода не идентифицирован
destination_wallet_not_identified - получатель p2p перевода не идентифицирован

Пополнение кошелька

Пополнение кошелька пользователя через запросы к API возможно с использованием пластиковых карт. Существуют 3 сценария пополнения кошелька с карты:

однократное пополнение
однократное пополнение с сохранением данных карты для последующего использования (“привязка карты”)
пополнение с сохраненной ранее карты (“рекарринг”)

Параметры

type = in - тип платежа
client_payment_id - клиентский идентификатор платежа
amount - сумма к зачислению
store_card - true | false - сохранить карту, чтобы использовать ее для платежей в дальнейшем (опциональный)
card - идентификатор сохраненной карты с которой будут списаны деньги (опциональный)

Однократное

Создаем платеж:

$ curl -u+79261111111:password -H 'Content-type:application/json' 
 -d '{"type": "in", "client_payment_id": "071c6d23-7508-4e35-ad92-852308a47678", "amount": 100}'
 https://www.synq.ru/mserver2-dev/v1/payments

{
  "meta" : {
    "code" : 200,
    "next_action" : "pay",
    "urgent_data" : {
      "amount" : 10010
    }
  },
  "data" : {
    "id" : 1401089237212,
    "client_payment_id" : "071c6d23-7508-4e35-ad92-852308a47678",
    "amount" : 100,
    "total" : 100.00,
    "created_at" : "2014-07-01T06:55:27.870Z",
    "status" : "created",
    "type" : "in",
    "inbound" : {
      "id" : 62,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "card" : {
      "state" : "created"
    }
  }
}

Платим:

$curl -u+79261111111:password -H 'Content-type:application/json' 
 -X POST https://www.synq.ru/mserver2-dev/v1/payments/1401089237212/pay

{
  "meta" : {
    "code" : 200,
    "next_action" : "get",
    "urgent_data" : {
      "amount" : 10010
    }

  },
  "data" : {
    "id" : 1401089237212,
    "client_payment_id" : "071c6d23-7508-4e35-ad92-852308a47678",
    "amount" : 100,
    "total" : 100,
    "created_at" : "2014-07-01T06:55:27.870Z",
    "status" : "processing",
    "type" : "in",
    "inbound" : {
      "id" : 62,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "card" : {
      "state" : "pending",
      "payment_page_url" : "https://test1.ipsp.com/frontend/endpoint?product_id=1721&desc=mserver2&payment_type=S&amount=100.00&currency=RUB&cf=1401089237212&locale=ru&hash=3d49fa2b7ceb67f8ad7ed7f2247dd2cad1c4acdc"
    }
  }
}

далее следует перенаправить пользователя на платежную страницу по ссылке из поля card.payment_page_url.

С сохранением данных карты

Создаем платеж:

$ curl -u+79261111111:password -H 'Content-type:application/json' 
 -d '{"type": "in", "client_payment_id": "071c6d23-7508-4e35-ad92-852308a47679", "amount": 100, "store_card": true}' https://www.synq.ru/mserver2-dev/v1/payments

{
  "meta" : {
    "code" : 200,
    "next_action" : "pay",
    "urgent_data" : {
      "amount" : 10010
    }

  },
  "data" : {
    "id" : 1401089237231,
    "client_payment_id" : "071c6d23-7508-4e35-ad92-852308a47679",
    "amount" : 100,
    "total" : 100.00,
    "created_at" : "2014-07-01T08:31:24.058Z",
    "status" : "created",
    "type" : "in",
    "inbound" : {
      "id" : 62,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "card" : {
      "id" : 21,
      "state" : "created"
    }
  }
}

Платим:

$ curl -u+79261111111:password-H 'Content-type:application/json' 
-X POST https://www.synq.ru/mserver2-dev/v1/payments/1401089237231/pay

{
  "meta" : {
    "code" : 200,
    "next_action" : "get",
    "urgent_data" : {
      "amount" : 10010
    }

  },
  "data" : {
    "id" : 1401089237231,
    "client_payment_id" : "071c6d23-7508-4e35-ad92-852308a47679",
    "amount" : 100,
    "total" : 100,
    "created_at" : "2014-07-01T08:31:24.058Z",
    "status" : "processing",
    "type" : "in",
    "inbound" : {
      "id" : 62,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "card" : {
      "id" : 21,
      "state" : "pending",
      "payment_page_url" : "https://test1.ipsp.com/frontend/endpoint?product_id=1721&desc=mserver2&payment_type=S&amount=100.00&currency=RUB&cf=1401089237231&locale=ru&biller_client_id=21&perspayee_expiry=0150&recur_freq=1&hash=5136f2cb7fd77f98b1df86d4644338e5a10dab98"
    }
  }
}

далее следует перенаправить пользователя на платежную страницу по ссылке из поля card.payment_page_url.

Убедимся, что платеж успешен и карта сохранена

$ curl -u+79261111111:passwordhttps://www.synq.ru/mserver2-dev/v1/payments/1401089237231

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10010
    }

  },
  "data" : {
    "id" : 1401089237231,
    "client_payment_id" : "071c6d23-7508-4e35-ad92-852308a47679",
    "amount" : 100,
    "total" : 100,
    "created_at" : "2014-07-01T08:31:24.058Z",
    "processed_at" : "2014-07-01T08:39:40.173Z",
    "status" : "completed",
    "type" : "in",
    "inbound" : {
      "id" : 62,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "card" : {
      "id" : 21,
      "state" : "active",
      "title" : "541715******2399",
      "type" : "MasterCard"
    }
  }
}

C сохраненной карты

Используем карту #21 сохраненную в предыдущем примере.

Создаем платеж:

$ curl -u+79261111111:password-H 'Content-type:application/json'
 -d '{"type": "in", "client_payment_id": "071c6d23-7508-4e35-ad92-852308a47689", "amount": 100, "card": 21}'  
 https://www.synq.ru/mserver2-dev/v1/payments

{
  "meta" : {
    "code" : 200,
    "next_action" : "pay",
    "urgent_data" : {
      "amount" : 10010
    }

  },
  "data" : {
    "id" : 1401089237232,
    "client_payment_id" : "071c6d23-7508-4e35-ad92-852308a47653",
    "amount" : 100,
    "total" : 100.00,
    "created_at" : "2014-07-01T08:58:51.143Z",
    "status" : "created",
    "type" : "in",
    "inbound" : {
      "id" : 62,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "card" : {
      "id" : 21,
      "state" : "active",
      "title" : "541715******2399",
      "type" : "MasterCard"
    }
  }
}

Платим:

$ curl -u+79261111111:password -H 'Content-type:application/json' X POST https://www.synq.ru/mserver2-dev/v1/payments/1401089237232/pay

{
  "meta" : {
    "code" : 200,
    "next_action" : "get",
    "urgent_data" : {
      "amount" : 10010
    }

  },
  "data" : {
    "id" : 1401089237232,
    "client_payment_id" : "071c6d23-7508-4e35-ad92-852308a47653",
    "amount" : 100,
    "total" : 100,
    "created_at" : "2014-07-01T12:04:49.330Z",
    "status" : "processing",
    "type" : "in",
    "inbound" : {
      "id" : 62,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "card" : {
      "id" : 25,
      "state" : "active",
      "title" : "541715******2399",
      "type" : "MasterCard"
    }
  }
}

Транзитный платеж

Транзитный платеж соединяет в одном действии зачисление денег на кошелек через поставщика ввода средств (в настоящее время ИПСП) и списание денег со счета кошелька в пользу поставщика вывода средств (в настоящее время КредитПилот).

По аналогии с пополнением кошелька возможны следующие варианты транзитного платежа:

однократное списание с карты
однократное списание с карты с сохранением данных карты для последующего использования (“привязка карты”)
списание средств с сохраненной ранее карты (“рекарринг”)

Параметры

type = inout - тип платежа
client_payment_id - клиентский идентификатор платежа (опциональный)
amount - сумма к зачислению
store_card - true | false - сохранить карту, чтобы использовать ее для платежей в дальнейшем (опциональный)
card - идентификатор сохраненной карты с которой будут списаны деньги (опциональный)
service - назначение платежа, идентификатор Сервиса
parameters - параметры платежного запроса в соответствии с /services/{service}

Однократное списание с карты

Создаем платеж:

$ curl -u+79261111111:password -H 'Content-type:application/json' 
-d '{"type": "inout", "amount": 100, "service": 834, "parameters": {"phoneNumber": "9267101283"}}' 
https://www.synq.ru/mserver2-dev/v1/payments

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    },
    "next_action" : "pay"
  },
  "data" : {
    "id" : 18357,
    "client_payment_id" : "9de7de50-cb15-40f0-a953-c77df91803c9",
    "amount" : 100,
    "total" : 100.00,
    "created_at" : "2015-02-02T12:23:57.548Z",
    "status" : "created",
    "type" : "inout",
    "service" : {
      "id" : 834,
      "name" : "Мегафон"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона",
      "value" : "9267101283"
    } ],
    "inbound" : {
      "id" : 4,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "outbound" : {
      "id" : 1,
      "code" : "tpr_out",
      "name" : "Кредит Пилот"
    },
    "card" : {
      "state" : "created"
    },
    "wallet" : {
      "phone" : "+79261111111"
    }
  }
}

Параметры (для этапа подтверждения платежа /pay)

card_success_url - URL на который пользователь будет перенаправлен в случае успешного сохранения карты, опционально
card_failure_url - URL на который пользователь будет перенаправлен в случае неуспешного сохранения карты, опционально

Коды ошибок

active_cards_limit - превышено максимально возможное количество активных карт

Платим:

$ curl -u+79261111111:password -H 'Content-type:application/json' -X POST 
https://www.synq.ru/mserver2-dev/v1/payments/18357/pay

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    },
    "next_action" : "get"
  },
  "data" : {
    "id" : 18357,
    "client_payment_id" : "9de7de50-cb15-40f0-a953-c77df91803c9",
    "amount" : 100,
    "total" : 100,
    "created_at" : "2015-02-02T12:23:57.548Z",
    "status" : "processing",
    "type" : "inout",
    "service" : {
      "id" : 834,
      "name" : "Мегафон"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона",
      "value" : "9267101283"
    } ],
    "inbound" : {
      "id" : 4,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "outbound" : {
      "id" : 1,
      "code" : "tpr_out",
      "name" : "Кредит Пилот"
    },
    "card" : {
      "state" : "pending",
      "payment_page_url" : "https://test1.ipsp.com/frontend/endpoint?product_id=1721&desc=BestWallet&payment_type=S&amount=100.00&currency=RUB&cf=18357&locale=ru&hash=1a6752f0f13df41aaa7dd24419ab04b1b1743b15"
    },
    "wallet" : {
      "phone" : "+79261111111"
    }
  }
}

далее следует перенаправить пользователя на платежную страницу по ссылке из поля card.payment_page_url.

Проверяем статус платежа:

$ curl -u+79261111111:password -H 'Content-type:application/json' 
https://www.synq.ru/mserver2-dev/v1/payments/18357

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    },
    "next_action" : "get"
  },
  "data" : {
    "id" : 18357,
    "client_payment_id" : "9de7de50-cb15-40f0-a953-c77df91803c9",
    "amount" : 100,
    "total" : 100,
    "created_at" : "2015-02-02T12:23:57.548Z",
    "processed_at" : "2015-02-02T12:27:13.279Z",
    "status" : "completed",
    "type" : "inout",
    "service" : {
      "id" : 834,
      "name" : "Мегафон"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона",
      "value" : "9267101283"
    } ],
    "inbound" : {
      "id" : 4,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "outbound" : {
      "id" : 1,
      "code" : "tpr_out",
      "name" : "Кредит Пилот"
    },
    "card" : {
      "state" : "used",
      "title" : "541715******7260",
      "type" : "MasterCard"
    },
    "wallet" : {
      "phone" : "+79261111111"
    },
    "remote_check" : "1422880082862"
  }
}

Платеж успешен.

С сохранением данных карты

Сценарий ничем не отличается от предыдущего, кроме передачи флага “store_card”: true при создании платежа. Идентификатор карты, возвращенный в data.card.id можно впоследствии использовать для пополнения счета кошелька или выполнения транзитных платежей с сохраненной карты.

Создаем платеж:

$ curl -u+79261111111:password -H 'Content-type:application/json' 
-d '{"type": "inout", "amount": 100, "store_card": true, "service": 834, "parameters": {"phoneNumber": "9267101283"}}' 
https://www.synq.ru/mserver2-dev/v1/payments

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    },
    "next_action" : "pay"
  },
  "data" : {
    "id" : 18387,
    "client_payment_id" : "f80143c5-29aa-4514-8aee-94acc3c3a026",
    "amount" : 100,
    "total" : 100.00,
    "created_at" : "2015-02-02T13:06:35.191Z",
    "status" : "created",
    "type" : "inout",
    "service" : {
      "id" : 834,
      "name" : "Мегафон"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона",
      "value" : "9267101283"
    } ],
    "inbound" : {
      "id" : 4,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "outbound" : {
      "id" : 1,
      "code" : "tpr_out",
      "name" : "Кредит Пилот"
    },
    "card" : {
      "id" : 7221,
      "state" : "created"
    },
    "wallet" : {
      "phone" : "+79261111111"
    }
  }
}

Параметры (для этапа подтверждения платежа /pay)

card_success_url - URL на который пользователь будет перенаправлен в случае успешного сохранения карты, опционально
card_failure_url - URL на который пользователь будет перенаправлен в случае неуспешного сохранения карты, опционально

Коды ошибок

active_cards_limit - превышено максимально возможное количество активных карт

Платим:

$ curl -u+79261111111:password -H 'Content-type:application/json' -X POST 
https://www.synq.ru/mserver2-dev/v1/payments/18387/pay

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    },
    "next_action" : "get"
  },
  "data" : {
    "id" : 18387,
    "client_payment_id" : "f80143c5-29aa-4514-8aee-94acc3c3a026",
    "amount" : 100,
    "total" : 100,
    "created_at" : "2015-02-02T13:06:35.191Z",
    "status" : "processing",
    "type" : "inout",
    "service" : {
      "id" : 834,
      "name" : "Мегафон"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона",
      "value" : "9267101283"
    } ],
    "inbound" : {
      "id" : 4,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "outbound" : {
      "id" : 1,
      "code" : "tpr_out",
      "name" : "Кредит Пилот"
    },
    "card" : {
      "id" : 7221,
      "state" : "pending",
      "payment_page_url" : "https://test1.ipsp.com/frontend/endpoint?product_id=1721&desc=BestWallet&payment_type=S&amount=100.00&currency=RUB&cf=18386&locale=ru&biller_client_id=82c9273ea7e0455d96efd0864f3042a6&perspayee_expiry=0150&recur_freq=1&hash=9621bc5f10d1430b2143fcbdb3c6a4be9b545aba"
    },
    "wallet" : {
      "phone" : "+79261111111"
    }
  }
}

далее следует перенаправить пользователя на платежную страницу по ссылке из поля card.payment_page_url.

Проверяем статус платежа:

$ curl -u+79261111111:password https://www.synq.ru/mserver2-dev/v1/payments/18387

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    },
    "next_action" : "get"
  },
  "data" : {
    "id" : 18387,
    "client_payment_id" : "1fa097f7-63a3-4778-aa3c-c62fc5e85045",
    "amount" : 100,
    "total" : 100,
    "created_at" : "2015-02-02T13:24:12.185Z",
    "processed_at" : "2015-02-02T13:24:57.711Z",
    "status" : "completed",
    "type" : "inout",
    "service" : {
      "id" : 834,
      "name" : "Мегафон"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона",
      "value" : "9267101283"
    } ],
    "inbound" : {
      "id" : 4,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "outbound" : {
      "id" : 1,
      "code" : "tpr_out",
      "name" : "Кредит Пилот"
    },
    "card" : {
      "id" : 7222,
      "state" : "active",
      "title" : "541715******6825",
      "type" : "MasterCard"
    },
    "wallet" : {
      "phone" : "+79261111111"
    },
    "remote_check" : "1422883547606"
  }
}

Платеж успешен. Карта с ID 7222 успешно сохранена (имеет статус active).

C сохраненной карты

Транзитный платеж с сохраненной карты отличается от платежа с однократным списанием только указанием идентификатора карты в поле card при создании платежа.

Создаем платеж используя карту с ID 7222, сохраненную в примере выше:

$ curl -u+79261111111:password -H 'Content-type:application/json' 
-d '{"type": "inout", "amount": 100, "card": 7222, "service": 834, "parameters": {"phoneNumber": "9267101283"}}' 
https://www.synq.ru/mserver2-dev/v1/payments

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    },
    "next_action" : "pay"
  },
  "data" : {
    "id" : 18388,
    "client_payment_id" : "8ff2a629-e397-42f5-9610-c6dbd12627d0",
    "amount" : 100,
    "total" : 100.00,
    "created_at" : "2015-02-02T13:31:01.643Z",
    "status" : "created",
    "type" : "inout",
    "service" : {
      "id" : 834,
      "name" : "Мегафон"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона",
      "value" : "9267101283"
    } ],
    "inbound" : {
      "id" : 4,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "outbound" : {
      "id" : 1,
      "code" : "tpr_out",
      "name" : "Кредит Пилот"
    },
    "card" : {
      "id" : 7222,
      "state" : "active",
      "title" : "541715******6825",
      "type" : "MasterCard"
    },
    "wallet" : {
      "phone" : "+79261111111"
    }
  }
}

Платим:

$ curl -u+79261111111:password -H 'Content-type:application/json' -X POST 
https://www.synq.ru/mserver2-dev/v1/payments/18388/pay

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    },
    "next_action" : "get"
  },
  "data" : {
    "id" : 18388,
    "client_payment_id" : "8ff2a629-e397-42f5-9610-c6dbd12627d0",
    "amount" : 100,
    "total" : 100,
    "created_at" : "2015-02-02T13:31:01.643Z",
    "status" : "processing",
    "type" : "inout",
    "service" : {
      "id" : 834,
      "name" : "Мегафон"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона",
      "value" : "9267101283"
    } ],
    "inbound" : {
      "id" : 4,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "outbound" : {
      "id" : 1,
      "code" : "tpr_out",
      "name" : "Кредит Пилот"
    },
    "card" : {
      "id" : 7222,
      "state" : "active",
      "title" : "541715******6825",
      "type" : "MasterCard"
    },
    "wallet" : {
      "phone" : "+79261111111"
    }
  }
}

Проверяем статус платежа:

$ curl -u+79261111111:password https://www.synq.ru/mserver2-dev/v1/payments/18388

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    },
    "next_action" : "get"
  },
  "data" : {
    "id" : 18388,
    "client_payment_id" : "8ff2a629-e397-42f5-9610-c6dbd12627d0",
    "amount" : 100,
    "total" : 100,
    "created_at" : "2015-02-02T13:31:01.643Z",
    "processed_at" : "2015-02-02T13:32:14.429Z",
    "status" : "completed",
    "type" : "inout",
    "service" : {
      "id" : 834,
      "name" : "Мегафон"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона",
      "value" : "9267101283"
    } ],
    "inbound" : {
      "id" : 4,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "outbound" : {
      "id" : 1,
      "code" : "tpr_out",
      "name" : "Кредит Пилот"
    },
    "card" : {
      "id" : 7222,
      "state" : "active",
      "title" : "541715******6825",
      "type" : "MasterCard"
    },
    "wallet" : {
      "phone" : "+79261111111"
    }
  }
}

Платеж успешен.

Отложенный выбор типа платежа

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

POST /payments/{:id}/pay

нужно передать в теле запроса следующие поля:

Поля запроса подтверждения платежа для смены типа in -> inout

type = inout - тип платежа
store_card - true | false - сохранить карту, чтобы использовать ее для платежей в дальнейшем (опциональный)
card - идентификатор сохраненной карты с которой будут списаны деньги (опциональный)

Создаем платеж используя кошелек как источник средств:

$ curl -u+79261111111:password -H 'Content-type:application/json' 
-d '{"type": "out", "amount": 100, "card": 7222, "service": 834, "parameters": {"phoneNumber": "9267101283"}}' 
https://www.synq.ru/mserver2-dev/v1/payments

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    },
    "next_action" : "pay"
  },
  "data" : {
    "id" : 19493,
    "client_payment_id" : "11140dd2-f002-4970-8603-fb48dc299673",
    "amount" : 100,
    "total" : 100.00,
    "created_at" : "2015-02-09T11:36:54.263Z",
    "status" : "created",
    "type" : "out",
    "service" : {
      "id" : 834,
      "name" : "Мегафон"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона",
      "value" : "9267101283"
    } ],
    "outbound" : {
      "id" : 1,
      "code" : "tpr_out",
      "name" : "Кредит Пилот"
    },
    "wallet" : {
      "phone" : "+79261111111"
    }
  }
}

Решаем заплатить сохраненной картой с ID 7222:

$ curl -u+79261111111:password -H 'Content-type:application/json' 
-d '{"type": "inout", "card": 7222}'
https://www.synq.ru/mserver2-dev/v1/payments/19493/pay

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    },
    "next_action" : "get"
  },
  "data" : {
    "id" : 19493,
    "client_payment_id" : "11140dd2-f002-4970-8603-fb48dc299673",
    "amount" : 100,
    "total" : 100,
    "created_at" : "2015-02-09T11:36:54.263Z",
    "status" : "processing",
    "type" : "inout",
    "service" : {
      "id" : 834,
      "name" : "Мегафон"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона",
      "value" : "9267101283"
    } ],
    "inbound" : {
      "id" : 4,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "outbound" : {
      "id" : 1,
      "code" : "tpr_out",
      "name" : "Кредит Пилот"
    },
    "card" : {
      "id" : 7222,
      "state" : "active",
      "title" : "541715******6825",
      "type" : "MasterCard"
    },
    "wallet" : {
      "phone" : "+79261111111"
    }
  }
}

Проверяем статус платежа:

$ curl -u+79261111111:password https://www.synq.ru/mserver2-dev/v1/payments/19493

{
  "meta" : {
    "code" : 200,
    "urgent_data" : {
      "amount" : 10000
    },
    "next_action" : "get"
  },
  "data" : {
    "id" : 19493,
    "client_payment_id" : "11140dd2-f002-4970-8603-fb48dc299673",
    "amount" : 100,
    "total" : 100,
    "created_at" : "2015-02-09T11:36:54.263Z",
    "processed_at" : "2015-02-09T11:40:17.546Z",
    "status" : "completed",
    "type" : "inout",
    "service" : {
      "id" : 834,
      "name" : "Мегафон"
    },
    "parameters" : [ {
      "code" : "phoneNumber",
      "name" : "№ Телефона",
      "value" : "9267101283"
    } ],
    "inbound" : {
      "id" : 4,
      "code" : "ipsp_in",
      "name" : "ООО ИПСП (агент)"
    },
    "outbound" : {
      "id" : 1,
      "code" : "tpr_out",
      "name" : "Кредит Пилот"
    },
    "card" : {
      "id" : 7222,
      "state" : "active",
      "title" : "541715******6825",
      "type" : "MasterCard"
    },
    "wallet" : {
      "phone" : "+79261111111"
    },
    "remote_check" : "1423482079404"
  }
}

Платеж успешен.

Карты

Карта - это сохраненный в mserver токен, с помощью которого пользователь кошелька может пополнять счет без ввода данных пластиковой карты.

Поля

id - уникальный идентификатор карты
state - состояние карты, см. ниже
title - название карты, в качестве названия сейчас используется маскированный номер карты
type - бренд карты: Visa/MasterCard/…

Состояния карты

Код состояния карты	Описание
`created`	Карта только что создана
`pending`	Карта сохраняется (ожидается уведомление от IPSP о успехе/неуспехе карточной транзакции
`active`	Карта сохранена, может быть использована для повторных платежей
`failed`	Карта не сохранена (и уже не будет)
`used`	Карта использована для однократного пополнения
`deleted`	Карта удалена

Создание карты

Параметры

card_success_url - URL на который пользователь будет перенаправлен в случае успешного сохранения карты, опционально
card_failure_url - URL на который пользователь будет перенаправлен в случае неуспешного сохранения карты, опционально

Коды ошибок

active_cards_limit - превышено максимально возможное количество активных карт

$ curl -u+79261111111:password -H 'Content-type:application/json' -d '{"card_success_url": "http://ya.ru", "card_failure_url": "http://google.com"}' https://www.synq.ru/mserver2-dev/v1/cards

{
  "meta" : {
    "code" : 200
  },
  "data" : {
    "id" : 62,
    "state" : "pending",
    "payment_page_url" : "https://test1.ipsp.com/frontend/endpoint?product_id=1721&desc=mserver2&payment_type=A&amount=1.00&currency=RUB&biller_client_id=1f95c7b9-74e5-4fd7-983d-c8d03d90347e&perspayee_expiry=0150&recur_freq=1&locale=ru&hash=cace0d7de544a25d2aa685ef12263a10655d9058"
  }
}

После создания карты следует перенаправить пользователя на платежную страницу по ссылке из поля payment_page_url. После ввода пользователем данных карты на платежной странице и получения mserver уведомления от IPSP об успехе или неуспехе карточной транзакции карта перейдет в состояние active или failed.

Загрузка карты

$ curl -u+79261111111:password -H 'Content-type:application/json' https://www.synq.ru/mserver2-dev/v1/cards/62

{
  "meta" : {
    "code" : 200
  },
  "data" : {
    "id" : 62,
    "state" : "active",
    "title" : "541715******2399",
    "type" : "MasterCard"
  }
}

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

Получение списка карт

$ curl -u+79261111111:password -H 'Content-type:application/json' https://www.synq.ru/mserver2-dev/v1/cards?state=active,pending

{
  "meta" : {
  "page" : {
      "total_elements" : 1
    },
    "code" : 200
  },
  "data" : [ {
    "id" : 62,
    "state" : "active",
    "title" : "541715******2399",
    "type" : "MasterCard"
  } ]
}

Опциональный параметр state позволяет фильтровать карты по состоянию.

Удаление карты

$ сurl -u+79261111111:password -H 'Content-type:application/json' 
 -X DELETE https://www.synq.ru/mserver2-dev/v1/cards/62

{
  "meta" : {
    "code" : 200
  }
}

Уведомления об изменении статуса привязки карты

Для уведомления внешней системы об изменениях статуса карты mserver выполняет POST запрос на URL /cards/status. Уведомление передается в теле POST запроса в виде объекта карты сериализованного в JSON. Например:

{
    "id" : 62,
    "state" : "active",
    "title" : "541715******2399",
    "type" : "MasterCard",
    "wallet" : {
     "phone" : "+792611111111"
    }
}

Данные тестовых карт

Номер карты	Срок действия	CVV2/CVC2	3D-Secure
5417150893587260	01/17	082	✓
5417150396276825	01/17	789	✗
4652060573334999	01/17	067	✓
4652060724922338	01/17	989	✗

Пароль 3D-Secure: 123456.

Введение

Аутентификация

Ошибки

Коды ошибок

Коды безопасности и контрольный разряд

Постраничный вывод списков

Срочные данные

OAuth

Токен доступа

Сценарий с кодом авторизации

Параметры URL авторизации

Параметры запроса к сервису токенов для authorization code flow

Сценарий с передачей пароля

Параметры запроса к сервису токенов для password flow

Разрешения

Тестовые приложения

Кошелек

Поля

Создание кошелька

Параметры

Коды ошибок

Активация кошелька

Параметры

Коды ошибок

Запрос повторной отправки кода активации

Параметры

Коды ошибок

Запрос кода для смены пароля

Коды ошибок

Смена пароля

Коды ошибок

Загрузка кошелька

Поиск кошельков

Задание персональных данных пользователя

Параметры

Коды ошибок

Загрузка персональных данных пользователя

Статусы персональных данных

Запрос персональных данных клиента системы БЭСТ

Параметры

Запрос по номеру телефона кошелька

Запрос по номеру карты клиента БЭСТ

Сервисы

Поля

Загрузка списка сервисов

Загрузка сервиса по идентификатору

Сервисы по группам

Поиск подходящего сервиса по номеру карты или телефона

Поля

Платежи

Поля, общие для всех типов платежей

Поля для платежей типа out / inout (вывод денег / транзит)

Поля для типа in / inout (ввод денег / транзит)

Поля для типа p2p (перевод между кошельками)

Статусы платежа

Причины отказа в проведении платежа

Клиентский идентификатор платежа

Проведение платежа

Получение истории платежей

Уведомления об изменении статуса платежа

Поля

Типы платежных операций

Платеж со счета кошелька

Параметры

Коды ошибок

Перевод между кошельками

Параметры

Коды ошибок

Пополнение кошелька

Параметры

Однократное

С сохранением данных карты

C сохраненной карты

Транзитный платеж

Параметры

Однократное списание с карты

Параметры (для этапа подтверждения платежа /pay)

Коды ошибок

С сохранением данных карты

Параметры (для этапа подтверждения платежа /pay)

Поля для платежей типа `out` / `inout` (вывод денег / транзит)

Поля для типа `in` / `inout` (ввод денег / транзит)

Поля для типа `p2p` (перевод между кошельками)