API Яндекс.Денег Руководство разработчика 15.11.2012
←
→
Транскрипция содержимого страницы
Если ваш браузер не отображает страницу правильно, пожалуйста, читайте содержимое страницы ниже
API Яндекс.Денег Руководство разработчика 15.11.2012
API Яндекс.Денег. Руководство разработчика. Версия 1.5 Дата сборки документа: 15.11.2012. Этот документ является составной частью технической документации Яндекса. Сайт справки к сервисам Яндекса: http://help.yandex.ru © 2008—2012 ООО «ЯНДЕКС». Все права защищены. Предупреждение об исключительных правах Яндексу (а также указанному им правообладателю) принадлежат исключительные права на все результаты интеллектуальной деятельности и приравненные к ним средства индивидуализации, используемые при разработке, поддержке и эксплуатации сервиса API Яндекс.Денег. К таким результатам могут относиться, но не ограничиваясь указанными, программы для ЭВМ, базы данных, изображения, тексты, другие произведения, а также изобретения, полезные модели, товарные знаки, знаки обслуживания, коммерческие обозначения и фирменные наименования. Эти права охраняются в соответствии с Гражданским кодексом РФ и международным правом. Вы можете использовать сервис API Яндекс.Денег или его составные части только в рамках полномочий, предоставленных вам Пользовательским соглашением сервиса API Яндекс.Денег или специального соглашения. Нарушение требований по защите исключительных прав правообладателя влечет за собой дисциплинарную, гражданско-правовую, административную или уголовную ответственность в соответствии с российским законодательством. Контактная информация ООО «ЯНДЕКС» http://www.yandex.ru Тел.: +7 495 739 7000 Email: pr@yandex-team.ru Главный офис: 119021, Россия, г. Москва, ул. Льва Толстого, д. 16
Содержание
Введение ............................................................................................................................................................................................. 4
Авторизация приложения .............................................................................................................................................................. 5
Регистрация приложения .......................................................................................................................................................... 6
Запрос авторизации .................................................................................................................................................................... 7
Получение токена .................................................................................................................................................................... 10
Отзыв токена ............................................................................................................................................................................ 12
Описание протокола ...................................................................................................................................................................... 13
Формат запроса ........................................................................................................................................................................ 13
Формат ответа .......................................................................................................................................................................... 14
Права на выполнение операций .............................................................................................................................................. 15
Типы данных протокола .......................................................................................................................................................... 20
Получение информации о счете пользователя ........................................................................................................................ 22
Метод account-info ................................................................................................................................................................... 22
Метод operation-history ............................................................................................................................................................ 23
Метод operation-details ............................................................................................................................................................. 26
Проведение платежей .................................................................................................................................................................... 29
Метод request-payment ............................................................................................................................................................. 29
Метод process-payment ............................................................................................................................................................ 33
Уведомления о событиях .............................................................................................................................................................. 37
Уведомление о входящем переводе ....................................................................................................................................... 37
Предметный указатель .................................................................................................................................................................... 40
API Яндекс.Денег Руководство разработчикаРуководство разработчика 4
Введение
Руководство предназначено для разработчиков сервисов и приложений, использующих API Яндекс.Де-
нег.
API Яндекс.Денег Руководство разработчика5
Авторизация приложения
Чтобы ваше приложение могло работать со счетом пользователя в системе "Яндекс.Деньги", ему необ-
ходимо пройти авторизацию.
Протокол OAuth2 позволяет сделать авторизацию безопасной и удобной. При OAuth2-авторизации при-
ложению не нужно запрашивать у пользователя его логин и пароль. Вместо этого пользователь выдает
приложению разрешение работать со своим счетом в рамках ограничений разрешенных пользователем.
Авторизация приложений в системе "Яндекс.Деньги" соответствует спецификациям:
• The OAuth 2.0 Authorization Protocol
• The OAuth 2.0 Protocol: Bearer Tokens
Схема взаимодействия пользователя и приложения с OAuth-сервером Яндекс.Денег представлена
на диаграмме:
Действия разработчика
1. Разработчик регистрирует свое приложение в системе "Яндекс.Деньги".
Согласно протоколу OAuth2, это фаза Registration Request. Система "Яндекс.Деньги" выдает разра-
ботчику client_id — идентификатор приложения, тип string.
2. Разработчик встраивает в код приложения полученный client_id, объявляя его константой. Далее
приложение распространяется любым удобным способом. В течение жизненного цикла приложения
client_id не изменяется.
API Яндекс.Денег Руководство разработчика6
Сценарий авторизации приложения пользователем
1. Пользователь инициирует авторизацию приложения для управления своим счетом.
2. Приложение отправляет запрос Authorization Request (запрос авторизации) на сервер Яндекс.Денег.
3. Яндекс.Деньги перенаправляют пользователя на страницу авторизации в системе "Яндекс.Деньги".
4. Пользователь вводит свой логин и пароль, просматривает список запрашиваемых прав и подтвер-
ждает либо отклоняет запрос авторизации приложения.
5. Приложение получает ответ Authorization Response в виде HTTP Redirect со временным токеном
для получения доступа или кодом ошибки.
6. Приложение, используя полученный временный токен доступа, отправляет запрос на получение
токена авторизации (Access Token Request)
7. Ответ содержит токен авторизации (access_token).
8. Приложение сообщает пользователю результат авторизации.
Удостоверение подлинности приложения по секретному слову
Система "Яндекс.Деньги" предоставляет дополнительную возможность удостоверения факта того
что токен авторизации будет получен именно из вашего приложения.
Для этого, при получении токена авторизации (вызов /oauth/token), приложение передает секретное сло-
во (client_secret), известное только приложению.
Примечание:
Защита на основе секретного слова будет эффективна лишь в том случае, если запрос на получение
токена авторизации отправляется от сервера приложения, минуя устройство или браузер пользователя.
Требования безопасности
1. Все сетевые взаимодействия производятся только по HTTPS.
2. Приложение должно проверять корректность SSL-сертификата сервера и немедленно прекращать
сессию в случае неуспеха проверки, чтобы не допустить утечку данных авторизации.
3. Не храните токен авторизации в открытом виде, в том числе в виде cookies.
4. Никогда не используйте токен авторизации в параметрах запросов (GET, POST, и пр.).
5. Секретное слово никогда не должно проходить через устройство или браузер пользователя.
6. Секретное слово не должно использоваться в иных запросах кроме запроса на получение токена.
Регистрация приложения
Для регистрации приложения требуется передать сведения о нем в систему "Яндекс.Деньги".
API Яндекс.Денег Руководство разработчика7
Для этого выполните следующие шаги:
1. Перейдите на страницу Регистрация сервиса. Для входа потребуется ввести ваш платежный пароль.
2. Укажите параметры приложения:
description
Название вашего приложения, например 'Мобильный магазин'.
application_uri
Ссылка на веб-страницу приложения или сайт разработчика.
redirect_uri
URI для передачи результата авторизации приложения (см. описание redirect_uri в стандар-
те The OAuth 2.0 Authorization Protocol).
Использовать проверку подлинности сервиса
Укажите, хотите ли вы использовать секретное слово для проверки подлинности сервиса (см.
описание client_secret в стандарте The OAuth 2.0 Authorization Protocol).
3. Нажмите кнопку Подтвердить.
Откроется страница Данные сервиса, где будут указаны название вашего приложения, его иденти-
фикатор (client_id) и, если выбрана соответствующая опция, сгенерированное секретное слово
(client_secret).
Осторожно!
Разработчик приложения не должен открыто публиковать где-либо свой client_id. Утечка
client_id может спровоцировать "фишинговые атаки", то есть выпуск приложений или сайтов,
получающих токены авторизации от вашего имени. При этом система "Яндекс.Деньги" будет счи-
тать что получает запросы от вашего приложения. Противодействовать этому можно при помощи
использования секретного слова (client_secret), известного только разработчику приложения.
Разработчик приложения должен обеспечить конфиденциальность секретного слова
(client_secret).
См. также
Авторизация приложения
Запрос авторизации
Приложение отправляет запрос Authorization Request на сервер системы "Яндекс.Деньги". Приложение
следует открыть браузер операционной системы и отправить HTTP-запрос в браузере операционной
системы.
Совет:
Для отправки запроса рекомендуется использовать метод POST — эквивалент HTML form submit
и кодировку UTF-8.
Формат запроса:
POST /oauth/authorize HTTP/1.1
Host: m.sp-money.yandex.ru (для мобильных устройств) или sp-money.yandex.ru (для
остальных устройств)
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length:
client_id=&response_type=code
&redirect_uri=&scope=
API Яндекс.Денег Руководство разработчика8
Пример параметров запроса:
client_id=092763469236489593523464667
response_type=code
redirect_uri=https://client.example.com/cb
scope=account-info operation-history
Пример запроса:
POST /oauth/authorize HTTP/1.1
Host: sp-money.yandex.ru
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 154
client_id=092763469236489593523464667&response_type=code&redirect_uri=https%3A
%2F%2Fclient%2Eexample%2Ecom%2Fcb&scope=account%2Dinfo%20operation%2Dhistory
Параметры запроса:
Параметр Тип Описание
client_id string Идентификатор приложения,
полученный при регистрации.
response_type string Фиксированное значение: code.
redirect_uri string URI, на который OAuth сервер пере-
дает результат авторизации.
Значение этого параметра при по-
символьном сравнении должно быть
идентично значению
redirect_uri, указанному при ре-
гистрации приложения. При сравне-
нии не учитываются индивидуаль-
ные параметры приложения, кото-
рые могут быть добавлены в конец
строки URI.
scope string Список запрашиваемых прав.
Разделитель элементов списка —
пробел. Элементы списка
чувствительны к регистру.
Примечание:
Запрещается отправлять запрос (открывать страницу) непосредственно из приложения, поскольку
по правилам платежной системы логин,пароль и платежный пароль пользователя допускается вводить
только на страницах платежной системы "Яндекс.Деньги".
По запросу авторизации пользователь перенаправляется на страницы авторизации системы "Ян-
декс.Деньги".Пользователь вводит свой логин и пароль, просматривает список запрашиваемых прав
и лимиты на платежи, подтверждает либо отклоняет запрос авторизации приложения.
Результат авторизации возвращается как HTTP 302 Redirect. Приложение должно обработать ответ
HTTP Redirect.
Внимание!
Если пользователь повторно вызывает авторизацию приложения с тем же значением параметра
client_id, выданные ранее разрешения аннулируются.
Параметры перенаправления с результатом авторизации:
Параметр Тип Описание
API Яндекс.Денег Руководство разработчика9
code string Временный токен (authorization
code), подлежащий обмену
на постоянный токен авторизации.
Присутствует если пользователь
подтвердил авторизацию
приложения.
error string Код ошибки. Присутствует в случае
ошибки или отказа в авторизации
пользователем.
error_description string Дополнительное текстовое
пояснение ошибки.
Возможные ошибки:
Значение поля error Описание Поведение системы
invalid_request В запросе отсутствуют обязательные Страница с текстом ошибки.
параметры, либо параметры имеют
некорректные или недопустимые
значения.
invalid_scope Параметр scope отсутствует, либо Страница с текстом ошибки.
имеет некорректное значение
или имеет логические противоречия.
unauthorized_client Неверное значение параметра Страница с текстом ошибки.
client_id, либо приложение
не имеет право запрашивать
авторизацию (например
его client_id заблокирован
системой "Яндекс.Деньги").
access_denied Пользователь отклонил запрос Перенаправление в приложение
авторизации приложения. с кодом ошибки.
Пример ответа Яндекс.Денег при успешной авторизации:
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=i1WsRn1uB1ehfbb37
Ответ системы Яндекс.Деньги при отказе в авторизации:
HTTP/1.1 302 Found
Location: https://client.example.com/cb?error=access_denied
Примечание:
Временный токен (значение поля code ответа сервера системы) подлежит немедленному обмену на то-
кен авторизации. Время действия этого токена мало (менее 1 минуты).
Приложение должно получить и обработать ответ сервера Яндекс.Денег и немедленно самостоятельно
обменять временный токен на токен авторизации.
Если приложению не удалось получить ответ сервера, временный токен утерян, либо срок его действия
истек, необходимо повторить процедуру авторизации.
См. также
Получение токена
Отзыв токена
Авторизация приложения
Регистрация приложения
API Яндекс.Денег Руководство разработчика10
Получение токена
Если авторизация завершилась успехом, приложение должно немедленно обменять временный токен
на токен авторизации. Для этого необходимо отправить запрос, содержащий временный токен, на OAuth-
сервер системы. Запрос должен быть отправлен методом POST.
Формат запроса:
POST /oauth/token HTTP/1.1
Host: m.sp-money.yandex.ru (для мобильных устройств) или sp-money.yandex.ru (для
остальных устройств)
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length:
code=&client_id=&grant_type=authorization_code&redirect_uri=
Пример запроса без проверки подлинности:
POST /oauth/token HTTP/1.1
Host: sp-money.yandex.ru
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 145
code=i1WsRn1uB1ehfbb37&client_id=092763469236489593523464667&grant_type=authoriz
ation_code&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
Пример запроса с проверкой подлинности по секретному слову:
POST /oauth/token HTTP/1.1
Host: sp-money.yandex.ru
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 179
code=i1WsRn1uB1ehfbb37&client_id=092763469236489593523464667&grant_type=authoriz
ation_code&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom
%2Fcb&client_secret=my_secret_word
Параметры запроса:
Параметр Тип Описание
code string Временный токен
(authorization code).
client_id string Идентификатор приложения,
полученный при регистрации.
grant_type string Фиксированное значение:
authorization_code.
redirect_uri string URI, на который OAuth-сервер пере-
дает результат авторизации. Значе-
ние этого параметра при посимволь-
ном сравнении должно быть иден-
тично значению redirect_uri,
ранее переданному в запросе
authorize.
client_secret string Секретное слово для проверки под-
линности приложения. Указывается,
если сервис зарегистрирован с про-
веркой подлинности.
В ответ на запрос сервер Яндекс.Денег возвращает токен авторизации (access_token), который явл-
яется симметричным секретом приложения и дает право проводить операции со счетом пользователя.
Токен возвращается в виде JSON-документа, который (в зависимости от результата обмена) может со-
держать одно из следующих полей:
Параметр Тип Описание
API Яндекс.Денег Руководство разработчика11
access_token string Токен авторизации. Присутствует
в случае успеха.
error string Код ошибки. Присутствует в случае
ошибки.
Возможные ошибки:
Значение поля error Описание
invalid_request Обязательные параметры запроса отсутствуют
или имеют некорректные или недопустимые значения.
unauthorized_client Неверное значение параметра client_id
или client_secret, либо приложение не имеет права
запрашивать авторизацию (например, его client_id
заблокирован системой "Яндекс.Деньги").
invalid_grant В выдаче access_token отказано. Временный токен
не выдавался системой, либо просрочен, либо по этому
временному токену уже выдан access_token
(повторный запрос токена авторизации с тем
же временным токеном).
Пример ответа при успешном обмене временного токена:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 102
Cache-Control: no-store
{
"access_token":"SlAV32hkhjhkkefhkjGHGSDcbndbjhfSHDFhjdbfv...wfervnrjKG"
}
Пример ответа при ошибке:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 31
Cache-Control: no-store
{
"error":"invalid_grant"
}
Совет:
Использовать временный токен можно только один раз. Если приложению не удалось получить ответ
сервера за время жизни временного токена, процедуру авторизации следует повторить сначала.
Примечание:
Полученный access_token является симметричным секретом авторизации, поэтому разработчик
приложения должен предпринять меры по его защите: хранить токен в зашифрованном виде, предоста-
влять доступ к нему только после авторизации пользователя в приложении. Например, токен авториза-
ции может быть зашифрован с помощью алгоритма 3DES, где ключ шифрования — 4-х значный
ПИН код.
API Яндекс.Денег Руководство разработчика12
Внимание!
Срок действия токена 3 года. По истечении этого времени, токен автоматически аннулируется.
См. также
Запрос авторизации
Отзыв токена
Авторизация приложения
Регистрация приложения
Отзыв токена
Приложение может отозвать полученный токен авторизации. При этом все права, выданные этому то-
кену, будут отменены.
Для этого отправьте запрос на OAuth-сервер системы, имеющий HTTP-заголовок Authorization, содер-
жащий отзываемый токен.
Запрос должен быть отправлен методом POST.
Пример запроса:
POST /api/revoke HTTP/1.1
Host: money.yandex.ru
Authorization: Bearer 01234567890ABCDEF01234567890
Content-Length: 0
В ответ сервер Яндекс.Денег возвращает один из следующих HTTP-кодов:
HTTP-код ответа Описание
200 OK Токен успешно отозван.
400 Bad Request Формат HTTP-запроса не соответствует протоколу.
Возможные причины: запрос невозможно разобрать,
HTTP-заголовок Authorization отсутствует, либо
имеет некорректное значение.
401 Unauthorized Указанный токен не существует, либо уже отозван.
Пример успешного ответа:
HTTP/1.1 200 OK
Content-Length: 0
Пример ответа при ошибке:
HTTP/1.1 400 Bad Request
Content-Length: 0
См. также
Запрос авторизации
Получение токена
Авторизация приложения
Регистрация приложения
API Яндекс.Денег Руководство разработчика13
Описание протокола
• Формат запроса
• Формат ответа
• Права на выполнение операций
• Типы данных протокола
Формат запроса
Запросы осуществляются посредством протокола HTTP 1.1 с использованием SSL (HTTPS), на адрес:
https://money.yandex.ru/api/
Авторизация запросов осуществляется согласно стандарту The OAuth 2.0 Protocol: Bearer Tokens.
HTTP запросы должны содержать заголовок:
Authorization: Bearer
Примечание:
Указанный токен должен иметь права на исполнение запрашиваемого метода с заданным набором
параметров.
Требования безопасности:
1. Все сетевые взаимодействия производятся только по HTTPS.
2. Приложение должно проверять корректность SSL-сертификата сервера. Если SSL-сертификат
не прошел проверку, необходимо немедленно прекратить сессию, чтобы не допустить утечку данных
авторизации.
3. Не храните токен авторизации в открытом виде, в том числе в виде cookies.
4. Никогда не используйте токен авторизации в параметрах запросов (GET, POST, и пр.).
Для передачи параметров запроса используется следующий формат:
• каждый параметр указывается парой ключ/значение в виде параметра POST-запроса;
• MIME-тип: application/x-www-form-urlencoded;
• кодировка символов: UTF-8.
Пример запроса:
API Яндекс.Денег Руководство разработчика14
POST /api/request-payment HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Authorization: Bearer 01234567890ABCDEF01234567890
param1=value1¶m2=value2¶m3=value3
См. также
Формат ответа
Права на выполнение операций
Типы данных протокола
Формат ответа
Ответ сервиса представляет собой JSON-документ в кодировке UTF-8, см. The application/json Media
Type for JavaScript Object Notation (JSON) и официальный сайт JSON. Содержимое документа зависит
от результата выполнения запроса.
Пример ответа в случае успешного выполнения:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 51
Expires: Thu, 01 Dec 1994 16:00:00 GMT
Cache-Control: no-cache
{
"param1":"value1",
"param2":"value2"
}
В ответе платежных методов присутствуют HTTP-заголовки, запрещающие прокси-серверам и локаль-
ным браузерам кэшировать содержимое.
Совет:
В ответе могут также присутствовать поля, не описанные в настоящем протоколе. Приложению следует
их игнорировать.
При отказе в авторизации сервер отвечает HTTP кодом 4xx. Возможные причины отказа:
• запрос невозможно разобрать;
• в запросе отсутствует HTTP-заголовок Authorization;
• в заголовке Authorization указан несуществующий, некорректный или просроченный токен;
• запрошена операция, на которую у токена нет прав.
Ответ содержит заголовок WWW-Authenticate (согласно стандарту OAuth2-Bearer).
При отказе в авторизации запроса в ответе присутствуют следующие поля:
Поле Описание
error Код причины отказа в авторизации.
error_description Дополнительное текстовое описание причины отказа.
Коды причины отказа в авторизации:
HTTP-код ответа Значение поля error Описание
API Яндекс.Денег Руководство разработчика15
400 invalid_request Формат HTTP запроса
не соответствует протоколу. Запрос
невозможно разобрать, либо
заголовок Authorization
отсутствует, либо имеет
некорректное значение.
401 invalid_token Указан несуществующий,
просроченный, или отозванный
токен.
403 insufficient_scope Запрошена операция, на которую
у токена нет прав.
Пример ответа при отсутствующем заголовке:
HTTP/1.1 400 Bad Request
WWW-Authenticate: Bearer error="invalid_request"
Пример ответа при просроченном токене:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The access
token has expired"
Пример ответа в случае отсутствия у токена необходимых прав:
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", error_description="Платеж
запрещен параметрами авторизации приложения"
В случае общей технической ошибки сервер возвращает HTTP код 500 Internal Server Error.
Приложению следует повторить запрос через некоторое время с теми же параметрами.
См. также
Формат запроса
Права на выполнение операций
Типы данных протокола
Права на выполнение операций
При вызове операций протокола необходимо передавать токен авторизации, который обладает соответ-
ствующими правами. Список прав запрашивается как значение параметра scope вызова authorize
OAuth2-авторизации приложения пользователем, права перечисляются через пробел.
Список возможных прав:
Название права Описание
account-info Получение информации о состоянии счета, см. метод
account-info.
operation-history Просмотр истории операций, см. метод operation-
history.
operation-details Просмотр деталей операции, см. метод operation-details.
payment Возможность осуществлять платежи в конкретный
магазин или переводить средства на конкретный счет
пользователя, см. методы request-payment и process-
payment.
payment-shop Возможность осуществлять платежи во все доступные
для API магазины, см. методы request-payment и process-
payment.
payment-p2p Возможность переводить средства на любые счета
других пользователей, см. методы request-payment
и process-payment.
API Яндекс.Денег Руководство разработчика16
shopping-cart Оплата корзины товаров. Подробнее см. Право shopping-
cart.
money-source Доступные методы проведения платежа, см. методы
request-payment и process-payment. Подробнее
см. Право money-source.
Ограничение:
В рамках scope можно одновременно использовать только одно из:
• набор прав payment;
• право payment-shop;
• право payment-p2p.
Ограничения, применяемые к правам
К выдаваемым правам могут применяться ограничения. Ограничения задаются следующим образом:
имя_права.destination.limit
Ограничения, накладываемые на права:
Условие destination (получатель платежа)
Применяется к правам: payment.
В качестве значения допустимо указывать только одно из следующих условий:
• to-pattern(patternId) — ограничивает возможность провести платеж только
по заданному patternId;
• to-account(to,identifier_type) — ограничивает возможность перевода средств только
на счет определенного пользователя. В качестве идентификатора получателя допустимо
указывать номер счета или номер привязанного к счету получателя мобильного телефона.
Параметры ограничения:
Параметр Описание
to Идентификатор счета получателя перевода.
Обязательный параметр.
identifier_type Тип идентификатора получателя платежа. Возможные
значения:
• account — номер счета в системе Яндекс.Деньги;
• phone — номер привязанного мобильного
телефона.
По умолчанию: account.
Совет:
Номер мобильного телефона как идентификатор получателя перевода.
Если пользователь, получатель перевода, имеет привязанный к счету мобильный телефон, то в каче-
стве идентификатора получателя платежа можно вместо номера счета использовать номер привязан-
ного мобильного телефона. Указанный номер телефона должен соответствовать формату ITU-T E.164
Numbering plan of the international telephone service Для России: полный номер, начинающийся с 7
без знака '+'.
API Яндекс.Денег Руководство разработчика17
Например: 79219990099
Пример для определения получателя перевода по номеру счета:
.to-account("41001XXXXXXXX") или .to-account("41001XXXXXXXX","account")
Пример для определения получателя перевода по номеру привязанного мобильного телефона:
.to-account("79219990099","phone")
Условие limit (лимит платежа)
limit(duration,sum)
Применяется к правам: payment, payment-shop, payment-p2p.
Ограничение указывается последним.
Формат:
• limit(duration,sum) — Ограничение общей суммы платежей за период времени.
• limit(,sum) — Делегирование права выполнить одноразовый платеж на фиксированную
сумму.
Параметры:
Параметр Значение
duration Период времени, в сутках. Если параметр отсутствует,
то платеж по данному разрешению может быть
проведен только один раз.
sum Общая сумма платежей за период duration в валюте
счета пользователя.
Совет:
Условие limit можно использовать для делегирования одноразовых платежей. Срок жизни
разрешения равен сроку жизни токена. Пользователь не может изменить сумму платежа.
Ограничение:
В рамках одного scope разрешается указывать либо только платежи за период, либо только
одноразовые платежи.
Ограничение:
Если в scope указано требование одноразового платежа, то, совместно с правом payment,
допускается указывать только права money-source и account-info, остальные права
запрещены.
Ограничение:
Вне зависимости от значений запрошенных лимитов, к платежам могут применяться ограничения,
установленные платежной системой для различных видов транзакций.
Пример: ограничение платежа 100 руб 50 коп. в сутки, пользователь может изменять сумму.
API Яндекс.Денег Руководство разработчика18
.limit(1,100.50)
Пример: одноразовый платеж на 1000 руб, пользователь не может изменить сумму.
.limit(,1000)
Значение по умолчанию: limit(1,3000) — 3000 рублей в сутки, пользователь может изменять
сумму.
Право money-source
Указание платежной системе, какие методы платежа поддерживаются приложением.
Формат:
money-source(список_методов_платежа)
Запрашиваемый метод проведения платежа:
• wallet — платежи со счета в системе "Яндекс.Деньги";
• card — с привязанной к счету банковской карты пользователя.
По умолчанию: wallet.
Ограничение:
Использование банковской карты невозможно для перевода средств на счета других пользователей.
Пример для платежа с привязанной банковской карты и со счета:
money-source("wallet","card")
Пример для платежа только с привязанной банковской карты:
money-source("card")
Пример для платежа только со счета:
money-source("wallet")
Примеры значений параметра scope
Разрешен просмотр истории платежей:
account-info operation-history operation-details
Разрешен просмотр остатка на счете и платежи в магазин 123 на сумму не более 1000 рублей в неделю:
account-info payment.to-pattern("123").limit(7,1000)
Разрешены переводы на счет XXXX, но не более 500 рублей в две недели:
payment.to-account("XXXX").limit(14,500)
Разрешен одноразовый перевод на счет, которому привязан телефон ZZZ, на сумму 500 рублей:
payment.to-account("ZZZ","phone").limit(,500)
Разрешены платежи с привязанной банковской карты в магазин 123 на сумму 1000 рублей в неделю:
payment.to-pattern("123").limit(7,1000) money-source("wallet","card")
Право shopping-cart
Единовременная оплата корзины товаров.
Формат:
shopping-cart(totalSum,shippingCost,currency,customerNumber).to-
pattern(patternId).item(description,qty,itemCost,itemPage).item()...
API Яндекс.Денег Руководство разработчика19
Ограничение:
1. Наличие этого права исключает возможность наличия всех других прав, кроме money-source
и account-info.
2. Право требует обязательного наличия условия to-pattern().
3. Условие to-account() не поддерживается.
4. Одно право shopping-cart может распространяться на несколько товаров.
5. В рамках одного shopping-cart допускается только одно условие to-
pattern().
Совет:
Разрешение на оплату корзины товаров имеет срок действия 1 час.
Совет:
По одному разрешению можно оплатить только одну корзину.
Параметры:
Параметр Тип Описание
description string Текстовое описание товара, например "Japanese Green Tea Kabuse
Aracha".
qty number Количество единиц товара, шт.
Может принимать значения:
• целое положительное число — количество единиц товара;
• значение отсутствует — одна штука.
itemCost amount Стоимость единицы товара.
itemPage string HTTP-ссылка на страницу товара в магазине. Необязательный
параметр.
shippingCost amount Стоимость доставки заказа. Может принимать значения:
• положительное число — товар с платной доставкой, цена
доставки товара;
• 0 — товар с бесплатной доставкой;
• значение отсутствует — доставка для данного товара
отсутствует.
totalSum amount Полная стоимость корзины (сумма к оплате). Рассчитывается
как сумма всех itemCost*qty плюс стоимость доставки
shippingCost.
currency string Код валюты платежа, всегда 643 (Рубль РФ по стандарту ISO 4217).
customerNumber string Номер заказа в магазине.
Пример: один товар в корзине, доставка отсутствует, ссылка на товар не указана.
shopping-cart(300.24,,"643","№123/2011").to-
pattern().item("Japanese Green Tea Kabuse Aracha 7oz.",,300.24)
Пример: два товара, платная доставка, один из товаров в количестве 2 штук.
API Яндекс.Денег Руководство разработчика20
shopping-cart(1000,200,"643","№123/2011").to-
pattern().item("Japanese Green Tea Kabuse Aracha 7oz.",,300,"http://
myshop.ru/tea/aracha.html").item("Japanese Green Tea Houjicha 7oz.",
2,250,"http://myshop.ru/tea/houjicha.html"
См. также
Формат запроса
Формат ответа
Типы данных протокола
Типы данных протокола
Тип данных протокола Соответствующий JSON-тип Описание
string string Текстовая строка в кодировке UTF-8.
amount number Сумма. Число с фиксированной
точкой, две цифры после точки.
boolean boolean Логическое значение: true, false.
int number 32-битное знаковое целое число.
object object Вложенный объект JSON.
array array Массив объектов JSON.
datetime string Временная метка согласно стандарту
RFC3339 в следующем формате
YYYY-MM-DDThh:mm:ss.fZZZZZ
(см. расшифровку ниже).
Расшифровка формата datetime:
• YYYY — год, всегда 4 цифры;
• MM — месяц, всегда 2 цифры (01=Январь, и т. д.);
• DD — день месяца, точно 2 цифры (от 01 до 31);
• T — латинский символ «T», должен быть в верхнем регистре;
• hh — часы, всегда 2 цифры (24-часовой формат, от 00 до 23);
• mm — минуты, всегда 2 цифры (от 00 до 59);
• ss — секунды, всегда 2 цифры (от 00 до 59);
• f — дробная часть секунды (до шести цифр), может отсутствовать, в этом случае следует опускать
и точку-разделитель;
• ZZZZZ — Описатель временной зоны, обязательный параметр. Может принимать значения:
• Z – UTC, символ "Z" должен быть в верхнем регистре;
• +hh:mm или -hh:mm – смещение относительно UTC (показывает, что указано локальное время,
которое опережает или отстает от UTC на указанное число часов и минут).
Пример:
API Яндекс.Денег Руководство разработчика21
2011-07-01T19:00:00.000+04:00 — 19 часов 1 июля 2011 года, часовой пояс Europe/
Moscow (UTC+04:00).
См. также
Date and Time on the Internet: Timestamps
Формат запроса
Формат ответа
Права на выполнение операций
API Яндекс.Денег Руководство разработчика22
Получение информации о счете пользователя
• Метод account-info
• Метод operation-history
• Метод operation-details
Метод account-info
Описание
Получение информации о состоянии счета пользователя.
Требуемые права токена: account-info
Входные параметры
Отсутствуют
Возвращает
В случае успеха возвращает JSON-документ со следующим содержимым:
Параметр Тип Описание
account string Номер счета пользователя.
balance amount Баланс счета пользователя.
currency string Код валюты счета пользователя. Всегда 643 (рубль РФ по
стандарту ISO 4217).
identified boolean Пользователь идентифицирован в системе "Яндекс.Деньги"
(значение параметра: true).
account_type string Тип счета пользователя. Возможные значения:
• personal — счет пользователя системы "Яндекс.Деньги";
• professional — профессиональный счет в системе
"Яндекс.Деньги".
Пример запроса:
POST /api/account-info HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Authorization: Bearer 01234567890ABCDEF01234567890
Content-Length: 0
Пример ответа:
{
"account" : "4100123456789",
"balance" : 1000.00,
"currency" : "643",
"identified" : false,
"account_type" : "personal"
}
API Яндекс.Денег Руководство разработчика23
Метод operation-history
Описание
Метод позволяет просматривать историю операций (полностью или частично) в постраничном режиме.
Записи истории выдаются в обратном хронологическом порядке: от последних к более ранним.
Требуемые права токена: operation-history.
Входные параметры
Параметр Тип Описание
type string Перечень типов операций (см. таблицу), которые требуется
отобразить. Типы операций перечисляются через пробел. Если
параметр отсутствует, выводятся все операции.
label string Отбор платежей по значению метки. Выбираются платежи,
у которых указано заданное значение параметра label вызова
request-payment.
from datetime Вывести операции ОТ момента времени (операции более поздние
или равные from). Если параметр отсутствует, выводятся
все операции.
till datetime Вывести операции ДО момента времени (операции более ранние
чем till). Если параметр отсутствует, выводятся все операции.
start_record string Если параметр присутствует то будут отображены операции,
начиная с номера start_record (см. замечание).
records int Количество запрашиваемых записей истории операций.
Допустимые значения: от 1 до 100, по умолчанию 30.
details boolean Показывать подробные детали операции. По умолчанию false.
Для отображения деталей операции требуется наличие права
operation-details.
Типы операций:
Тип Описание
deposition Пополнение счета (приход).
payment Платежи со счета (расход).
Возвращает
Метод возвращает следующие параметры:
Параметр Тип Описание
error string Код ошибки. Присутствует при ошибке выполнения запроса.
next_record string Порядковый номер первой записи на следующей странице истории
операций. Присутствует в случае наличия следующей страницы
истории (см. замечание).
operations array Список операций.
Параметры операции:
Параметр Тип Описание
operation_id string Идентификатор операции.
API Яндекс.Денег Руководство разработчика24
Параметр Тип Описание
status string Статус платежа (перевода). Может принимать следующие значения:
• success — платеж завершен успешно;
• refused — платеж отвергнут получателем или отменен
отправителем;
• in_progress — платеж не завершен, перевод не принят
получателем или ожидает ввода кода протекции.
datetime datetime Дата и время совершения операции.
title string Краткое описание операции (название магазина или источник
пополнения).
pattern_id string Идентификатор шаблона, по которому совершен платеж.
Присутствует только для платежей.
direction string Направление движения средств. Может принимать значения:
• in (приход);
• out (расход).
amount amount Сумма операции.
label string Метка платежа. Присутствует для входящих и исходящих переводов
другим пользователям системы, у которых был указан параметр
label вызова request-payment.
Совет:
Если значение входного параметра details установлено в true, в ответе будут также присутствовать
выходные параметры операции operation-details.
Код ошибки выполнения операции:
Код Описание
illegal_param_type Неверное значение параметра type.
illegal_param_start_record Неверное значение параметра start_record.
illegal_param_records Неверное значение параметра records.
illegal_param_label Неверное значение параметра label.
illegal_param_from Неверное значение параметра from.
illegal_param_till Неверное значение параметра till.
все прочие значения Техническая ошибка, повторите вызов операции
позднее.
Примечание:
Если история содержит большое количество операций, список операций выдается постранично.
По умолчанию выдается первая страница истории. Если есть хотя бы одна последующая страница, то в
ответе присутствует параметр next_record, определяющий порядковый номер ее первой записи.
Чтобы получить следующую страницу, повторите запрос с теми же параметрами, добавив параметр
start_record и указав в нем порядковый номер первой записи следующей страницы, полученный ранее
из параметра next_record.
Запрос полной истории
Пример запроса:
API Яндекс.Денег Руководство разработчика25
POST /api/operation-history HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 35
Authorization: Bearer 01234567890ABCDEF01234567890
type=deposition%20payment&records=3
Пример ответа:
{
"next_record" : "4",
operations : [
{
"operation_id" : "1234567",
"status" : "success",
"pattern_id" : "2904",
"direction" : "out",
"amount" : 500.00,
"datetime" : "2011-07-11T20:43:00.000+04:00",
"title" : "Оплата ADSL-доступа компании XXX"
},
{
"operation_id" : "1234568",
"status" : "success",
"pattern_id" : "2901",
"direction" : "out",
"amount" : 300.00,
"datetime" : "2011-07-10T20:43:00.000+04:00",
"title" : "Прямое пополнение счета телефона YYY"
},
{
"operation_id" : "1234569",
"status" : "success",
"direction" : "in",
"amount" : 1000.00,
"datetime" : "2011-07-10T20:40:00.000+04:00",
"title" : "Банк ZZZ, пополнение"
}
]
}
Пример ответа с подробными деталями операции:
{
"next_record" : "2",
operations : [
{
"operation_id" : "1234567",
"status" : "success",
"pattern_id" : "2904",
"direction" : "out",
"amount" : 500.00,
"datetime" : "2011-07-11T20:43:00.000+04:00",
"title" : "Оплата ADSL-доступа компании XXX",
"details" : "Предоплата услуг ADSL доступа в интернет компании XXX\nНомер лицевого
счета абонента: \n1234567/89\nЗачисленная сумма: 500.00\nНомер транзакции:
2000002967767"
}
]
}
Пример ответа с подробными деталями операции для исходящего перевода другому пользователю:
{
"next_record" : "2",
operations : [
{
"operation_id" : "1234567",
"status" : "success",
"pattern_id" : "p2p",
"direction" : "out",
"amount" : 50.25,
"datetime" : "2011-07-11T20:43:00.000+04:00",
API Яндекс.Денег Руководство разработчика26
"title" : "Перевод на счет 4100123456789",
"recipient" : "4100123456789",
"recipient_type" : "account",
"message" : "Купите бублики",
"comment" : "Перевод пользователю Яндекс.Денег",
"codepro" : false,
"details" : "Счет получателя:\n4100123456789\nСумма к получению: 50,00 руб."
}
]
}
Пример ответа при неверно заданном параметре:
{
"error" : "illegal_param_type"
}
Запрос последующих страниц истории платежей
Пример запроса:
POST /api/operation-history HTTP/1.1
Host: money.yandex.ru
Authorization: Bearer 01234567890ABCDEF01234567890
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 40
type=payment&records=20&start_record=120
Метод operation-details
Описание
Позволяет получить детальную информацию об операции из истории.
Требуемые права токена: operation-details.
Входные параметры
Параметр Тип Описание
operation_id string Идентификатор операции. Значение параметра следует указывать
как значение параметра operation_id ответа метода operation-
history, или значение поля payment_id ответа метода process-
payment, если запрашивается история счета плательщика.
Возвращает
Метод возвращает следующие параметры:
Параметр Тип Описание
error string Код ошибки, присутствует при ошибке выполнения запроса.
operation_id string Идентификатор операции. Значение параметра соответствует либо
значению параметра operation_id ответа метода operation-
history либо, в случае если запрашивается история счета
плательщика, значению поля payment_id ответа метода process-
payment.
status string Статус платежа (перевода). Значение параметра соответствует
значению поля status ответа метода operation-history.
pattern_id string Идентификатор шаблона платежа, по которому совершен платеж.
Присутствует только для платежей.
API Яндекс.Денег Руководство разработчика27
Параметр Тип Описание
direction string Направление движения средств. Может принимать значения:
• in (приход);
• out (расход).
amount amount Сумма операции.
datetime datetime Дата и время совершения операции.
title string Краткое описание операции (название магазина или источник
пополнения).
sender string Номер счета отправителя перевода. Присутствует для входящих
переводов от других пользователей.
recipient string Идентификатор получателя перевода. Присутствует для исходящих
переводов другим пользователям.
recipient_type string Тип идентификатора получателя перевода. Присутствует для исхо-
дящих переводов другим пользователям. Возможные значения:
• account — Номер счета получателя в системе Яндекс.Деньги;
• phone — Номер привязанного мобильного телефона
получателя;
• email — E-mail получателя перевода.
message string Сообщение получателю перевода. Присутствует для переводов
другим пользователям.
comment string Комментарий к переводу (для отправителя). Присутствует в истории
переводов отправителя.
codepro boolean Перевод защищен кодом протекции. Присутствует для переводов
другим пользователям.
label string Метка платежа. Присутствует для входящих и исходящих переводов
другим пользователям системы, у которых был указан параметр
label вызова request-payment.
details string Детальное описание платежа. Строка произвольного формата,
может содержать любые символы и переводы строк.
В случае ошибки возвращается ее код:
Код Описание
illegal_param_operation_id Неверное значение параметра operation_id.
все прочие значения Техническая ошибка, повторите вызов метода позднее.
Пример запроса:
POST /api/operation-details HTTP/1.1
Host: money.yandex.ru
Authorization: Bearer 01234567890ABCDEF01234567890
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 20
operation_id=1234567
Пример ответа при оплате в магазин:
{
"operation_id" : "1234567",
"status" : "success",
"pattern_id" : "2904",
"amount" : 500.00,
"direction" : "out",
"datetime" : "2011-07-11T20:43:00.000+04:00",
"title" : "Оплата ADSL-доступа компании Мой-Провайдер",
"details" : "Предоплата услуг ADSL-доступа в интернет компании ООО \"XXX\"\nНомер
лицевого счета абонента: \n1234567/89\nЗачисленная сумма: 500.00\nНомер транзакции:
2000002967767"
}
API Яндекс.Денег Руководство разработчика28
Пример ответа для исходящего перевода другому пользователю:
{
"operation_id" : "1234567",
"status" : "success",
"pattern_id" : "p2p",
"direction" : "out",
"amount" : 50.25,
"datetime" : "2011-07-11T20:43:00.000+04:00",
"title" : "Перевод на счет 4100123456789",
"recipient" : "4100123456789",
"recipient_type" : "account",
"message" : "Купите бублики",
"comment" : "Перевод от пользователя Яндекс.Денег",
"codepro" : false,
"details" : "Счет получателя:\n4100123456789\nСумма к получению: 50,00 руб."
}
Пример ответа при запросе несуществующей операции:
{
"error" : "illegal_param_operation_id"
}
API Яндекс.Денег Руководство разработчика29
Проведение платежей
Сценарий платежа в системе "Яндекс.Деньги":
1. Платежи проводятся на основе шаблона платежа с заполнением пользовательских параметров.
Приложению следует отобразить пользователю форму с запросом параметров платежа (сумма,
номер телефона, номер договора, и т. п.).
2. Приложение отправляет запрос платежа, содержащий идентификатор шаблона платежа
и параметры, введенные пользователем (вызывается метод request-payment). Сервер Яндекс.Денег
проверяет параметры платежа и возможность проведения платежа в магазин, возвращает
идентификатор и текст контракта платежа.
3. Приложение отображает пользователю контракт платежа, пользователь может подтвердить платеж
или отказаться от него.
4. Если пользователь подтвердил платеж, приложение отправляет запрос на подтверждение платежа
(вызов метода process-payment) c указанием идентификатора запроса, параметры, возвращенного
ранее методом request-payment.
Примечание:
1. Средства со счета пользователя списываются при вызове метода process-payment.
2. При повторном вызове process-payment с теми же параметрами метод возвратит состояние ранее
проведенного платежа.
3. В случае обрыва связи или иных сетевых ошибок приложение должно повторить вызов метода с теми
же параметрами.
Возможные виды платежей:
• платеж в магазин;
• перевод средств на счета других пользователей.
Метод request-payment
Описание
Запрос платежа. Проверка параметров платежа и возможности приема платежа магазином, либо пере-
вода средств на счет пользователя системы "Яндекс.Деньги".
Требуемые права для платежа в магазин: payment.to-pattern ("шаблон платежа") или payment-shop.
Требуемые права для перевода средств на счета других пользователей: payment.to-account ("идентифи-
катор получателя", "тип идентификатора") или payment-p2p.
Входные параметры для платежа в магазин
Параметр Тип Описание
pattern_id string Идентификатор шаблона платежа.
* string Пользовательские параметры шаблона платежа, требуемые
магазином.
API Яндекс.Денег Руководство разработчика30
Входные параметры для перевода средств на счета других
пользователей
Параметр Тип Описание
pattern_id string Фиксированное значение: p2p.
to string Идентификатор получателя перевода.
identifier_type string Тип идентификатора получателя перевода. Необязательный
параметр. Значение по умолчанию — номер счета в системе
Яндекс.Деньги. Значение должно соответствовать значению
identifier_type ограничения to-account параметра scope
запроса авторизации.
amount amount Сумма перевода.
comment string Комментарий к переводу, отображается в истории отправителя.
message string Комментарий к переводу, отображается получателю.
label string Метка платежа. Необязательный параметр.
Совет:
Любому переводу при его проведении можно присвоить "метку платежа". Метка платежа — это неко-
торая дополнительная информация, присваиваемая приложением данному переводу.
Впоследствии, можно выбрать из истории переводы по указанной метке. Например, в качестве метки
платежа можно указывать код или идентификатор некой сущности в приложении. Допустимо исполь-
зовать значения длиной до 64 символов. Значение метки чувствительно к регистру символов.
Возвращает
В случае успеха возвращает следующие параметры:
Параметр Тип Описание
status string Код результата выполнения операции (см.таблицу).
error string Код ошибки при проведении платежа (пояснение к полю status).
Присутствует только при ошибках.
money_source object Доступные для приложения методы проведения платежа,
см.Доступные методы платежа. Присутствует только при успешном
выполнении метода.
request_id string Идентификатор запроса платежа, сгенерированный системой.
Присутствует только при успешном выполнении метода.
contract string Текст описания платежа (контракт). Присутствует только
при успешном выполнении метода.
balance amount Текущий баланс счета пользователя. Присутствует при выполнении
следующих условий:
• метод выполнен успешно;
• токен авторизации обладает правом account-info.
recipient_identified boolean Идентифицирован ли получатель в системе "Яндекс.Деньги". Воз-
можные значения:
• true — получатель идентифицирован;
• false или параметр отсутствует — получатель
не идентифицирован.
Параметр присутствует при успешном выполнении метода в случае
перевода средств на счет другого пользователя.
API Яндекс.Денег Руководство разработчика31
Параметр Тип Описание
recipient_account_type string Тип счета получателя в системе "Яндекс.Деньги". Параметр
присутствует при успешном выполнении метода в случае перевода
средств на счет другого пользователя.
Код результата выполнения операции:
Код Описание
success Успешное выполнение.
refused Отказ в проведении платежа, объяснение причины отказа содержится в поле
error. Это конечное состояние платежа.
В случае ошибки выполнения операции возвращается ее код:
Код Описание
illegal_params Обязательные параметры платежа отсутствуют
или имеют недопустимые значения.
illegal_param_label Недопустимое значение параметра label.
phone_unknown Указан номер телефона не связанный со счетом
пользователя или получателя платежа.
payment_refused Магазин отказал в приеме платежа (например
пользователь попробовал заплатить за товар, которого
нет в магазине).
authorization_reject В авторизации платежа отказано. Возможные причины:
• транзакция с текущими параметрами запрещена
для данного пользователя;
• пользователь не принял Соглашение
об использовании системы "Яндекс.Деньги".
not_enough_funds На счете плательщика недостаточно средств.
Необходимо пополнить счет и провести новый платеж.
limit_exceeded Превышен один из лимитов на операции:
• на сумму операции для выданного токена
авторизации;
• сумму операции за период времени для выданного
токена авторизации;
• ограничений платежной системы для различных
видов операций.
все прочие значения Техническая ошибка, повторите вызов операции
позднее.
Примечание:
При выполнении запроса платежа система "Яндекс.Деньги", как правило, связывается с сервером
магазина, поэтому время ответа метода может составлять до 30 секунд. Во время работы метода
request-payment приложение должно показывать пользователю сообщение о том, что приложение
ожидает ответа от магазина.
Примечание:
Успешное выполнение метода request-payment не является гарантией успешного завершения
процесса платежа, так как авторизация платежа выполняется при вызове метода process-payment.
API Яндекс.Денег Руководство разработчикаВы также можете почитать
