API Яндекс.Денег API для приложений 19.10.2014
←
→
Транскрипция содержимого страницы
Если ваш браузер не отображает страницу правильно, пожалуйста, читайте содержимое страницы ниже
API Яндекс.Денег API для приложений 19.10.2014
API Яндекс.Денег. API для приложений. Версия 1.8 Дата сборки документа: 19.10.2014. Этот документ является составной частью технической документации Яндекса. Сайт справки к сервисам Яндекса: http://help.yandex.ru © 2008—2014 ООО «ЯНДЕКС». Все права защищены. Предупреждение об исключительных правах Яндексу (а также указанному им правообладателю) принадлежат исключительные права на все результаты интеллектуальной деятельности и приравненные к ним средства индивидуализации, используемые при разработке, поддержке и эксплуатации сервиса API Яндекс.Денег. К таким результатам могут относиться, но не ограничиваясь указанными, программы для ЭВМ, базы данных, изображения, тексты, другие произведения, а также изобретения, полезные модели, товарные знаки, знаки обслуживания, коммерческие обозначения и фирменные наименования. Эти права охраняются в соответствии с Гражданским кодексом РФ и международным правом. Вы можете использовать сервис API Яндекс.Денег или его составные части только в рамках полномочий, предоставленных вам Пользовательским соглашением сервиса API Яндекс.Денег или специального соглашения. Нарушение требований по защите исключительных прав правообладателя влечет за собой дисциплинарную, гражданско-правовую, административную или уголовную ответственность в соответствии с российским законодательством. Контактная информация ООО «ЯНДЕКС» http://www.yandex.ru Тел.: +7 495 739 7000 Email: pr@yandex-team.ru Главный офис: 119021, Россия, г. Москва, ул. Льва Толстого, д. 16
Содержание
............................................................................................................................................................................................................... 4
Авторизация приложения .............................................................................................................................................................. 6
Регистрация приложения .......................................................................................................................................................... 8
Запрос авторизации .................................................................................................................................................................... 8
Получение токена .................................................................................................................................................................... 11
Получение дополнительного токена ...................................................................................................................................... 13
Отзыв токена ............................................................................................................................................................................ 15
Права на выполнение операций .............................................................................................................................................. 16
Описание протокола ...................................................................................................................................................................... 20
Формат запроса ........................................................................................................................................................................ 20
Формат ответа .......................................................................................................................................................................... 21
Типы данных ............................................................................................................................................................................ 22
Информация о счете пользователя ............................................................................................................................................. 24
Метод account-info ................................................................................................................................................................... 24
Метод operation-history ............................................................................................................................................................ 26
Метод operation-details ............................................................................................................................................................. 30
Платежи из кошелька Яндекс.Денег .......................................................................................................................................... 34
Метод request-payment ............................................................................................................................................................. 34
Метод process-payment ............................................................................................................................................................ 41
Метод incoming-transfer-accept ............................................................................................................................................... 47
Метод incoming-transfer-reject ................................................................................................................................................. 48
Платежи с банковских карт без авторизации .......................................................................................................................... 50
Метод instance-id ...................................................................................................................................................................... 54
Метод request-external-payment ............................................................................................................................................... 55
Метод process-external-payment .............................................................................................................................................. 57
Уведомления о событиях .............................................................................................................................................................. 61
Уведомление о входящем переводе ....................................................................................................................................... 61
Предметный указатель .................................................................................................................................................................... 65
API Яндекс.Денег API для приложенийAPI для приложений 4
API для приложений — это инструмент, который позволяет использовать практически все функции
нашего сервиса.
Что можно делать с помощью API:
• принимать платежи — и магазинам, и частным пользователям. Списывать деньги можно с любой
банковской карты или из кошелька;
• получать информацию о пользователях — проверять баланс, историю и детали операций;
• получать HTTP-уведомления — для автоматической обработки переводов;
• реализовать безакцептные платежи. По умолчанию — из кошелька пользователя, по договору — с
банковской карты.
С чего начать
1. Зарегистрируйте свое приложение в API Яндекс.Денег.
2. Прочитайте документацию
3. Добавьте в приложение новый платежный функционал. Для быстрого старта используйте наши
SDK — PHP, Java, Android, ObjC, Python, NodeJS, Ruby, iOS.
4. Начните принимать платежи с банковских карт или из электронных кошельков.
О платежах с банковских карт
Страница, где пользователь указывает данные карты, находится на нашей стороне — у Яндекс.Денег
есть сертификат PCI DSS.
Как всё работает:
1. Пользователь выбирает в вашем приложении способ оплаты — банковскую карту.
2. Вы отправляете его на страницу ввода данных (на нашей стороне). В процессе платежа банк может
потребовать дополнительное подтверждение (3-D Secure), тогда мы попросим пользователя ввести
пароль.
3. После проверки банком вы списываете деньги, пользователь возвращается в приложение и видит
страницу с информацией о платеже.
О платежах из кошельков
Вам нужно только один раз получить у пользователя разрешение на доступ к кошельку (стандартный
OAuth).
Как это происходит:
1. Приложение запрашивает права, которые вам нужны. Например, проводить регулярные безакцепт-
ные платежи.
2. Пользователь попадает на наш сайт и подтверждает доступ для приложения.
3. Готово: можно списывать деньги и запрашивать данные без участия пользователя.
API для приложений используют
AVITO.ru Mamba Xsolla Фотострана Дзен Мани
API Яндекс.Денег API для приложенийAPI для приложений 5
Остались вопросы? Напишите нам: api@money.yandex.ru
API Яндекс.Денег API для приложений6
Авторизация приложения
Чтобы ваше приложение могло работать со счетом пользователя в Яндекс.Деньгах, ему необходимо
пройти авторизацию.
Протокол OAuth2 позволяет сделать авторизацию безопасной и удобной. При OAuth2-авторизации при-
ложению не нужно запрашивать у пользователя его логин и пароль. Вместо этого пользователь выдает
приложению разрешение работать со своим счетом в рамках ограничений разрешенных пользователем.
Авторизация приложений в Яндекс.Деньгах соответствует спецификациям:
• The OAuth 2.0 Authorization Framework
• The OAuth 2.0 Authorization Framework: Bearer Token Usage
Схема взаимодействия пользователя и приложения с OAuth-сервером Яндекс.Денег представлена
на диаграмме:
Действия разработчика
1. Разработчик регистрирует свое приложение в Яндекс.Деньгах.
Согласно протоколу OAuth2, это фаза Registration Request. Сервис «Яндекс.Деньги» выдает разра-
ботчику client_id — идентификатор приложения, тип string.
2. Разработчик встраивает в код приложения полученный client_id, объявляя его константой. Далее
приложение распространяется любым удобным способом. В течение жизненного цикла приложения
client_id не изменяется.
API Яндекс.Денег API для приложений7
Сценарий авторизации приложения пользователем
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 Яндекс.Денег API для приложений8
Регистрация приложения
Для регистрации вашего приложения в Яндекс.Деньгах выполните следующие шаги:
1. Перейдите на страницу Регистрация приложения. Для входа потребуется ввести вашу платежную
авторизацию.
2. Укажите параметры приложения:
description
Название вашего приложения, например 'Мобильный магазин'.
logo
Логотип вашего приложения.
application_uri
Ссылка на веб-страницу приложения или сайт разработчика.
redirect_uri
URI для передачи результата авторизации приложения (см. описание redirect_uri в стандар-
те The OAuth 2.0 Authorization Protocol).
Использовать проверку подлинности приложения
Укажите, хотите ли вы использовать секретное слово для проверки подлинности приложения (см.
описание client_secret в стандарте The OAuth 2.0 Authorization Framework).
3. Нажмите кнопку Подтвердить.
Откроется страница Данные приложения, где будут указаны название вашего приложения,
его идентификатор (client_id) и, если выбрана соответствующая опция, сгенерированное се-
кретное слово (client_secret).
Осторожно!
Разработчик приложения не должен открыто публиковать где-либо свой client_id. Утечка
client_id может спровоцировать "фишинговые атаки", то есть выпуск приложений или сайтов,
получающих токены авторизации от вашего имени. При этом Яндекс.Деньги будут считать что по-
лучают запросы от вашего приложения.
Противодействовать этому можно при помощи использования секретного слова
(client_secret), известного только разработчику приложения. Разработчик приложения должен
обеспечить конфиденциальность секретного слова (client_secret).
Запрос авторизации
Приложение отправляет запрос Authorization Request на сервер Яндекс.Денег, используя браузер опе-
рационной системы.
Совет:
Для отправки запроса рекомендуется использовать метод POST — эквивалент HTML form submit
и кодировку UTF-8.
Формат запроса:
API Яндекс.Денег API для приложений9
POST /oauth/authorize HTTP/1.1
Host: m.sp-money.yandex.ru (для мобильных устройств) или sp-money.yandex.ru (для
остальных устройств)
Content-Type: application/x-www-form-urlencoded
Content-Length:
client_id=&response_type=code
&redirect_uri=&scope=&instance_name=
Пример параметров запроса:
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
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 Список запрашиваемых прав.
Разделитель элементов списка —
пробел. Элементы списка
чувствительны к регистру.
instance_name string Идентификатор экземпляра
авторизации в приложении.
Необязательный параметр.
Позволяет получить несколько
авторизаций для одного приложения.
Примечание:
Запрещается отправлять запрос (открывать страницу) непосредственно из приложения, поскольку
по правилам платежной системы логин, пароль и платежный пароль пользователя допускается вводить
только на страницах сервиса «Яндекс.Деньги».
По запросу авторизации пользователь перенаправляется на страницы авторизации Яндекс.Денег. По-
льзователь вводит свой логин и пароль, просматривает список запрашиваемых прав и лимиты на пла-
тежи, подтверждает либо отклоняет запрос авторизации приложения.
API Яндекс.Денег API для приложений10
Результат авторизации возвращается как HTTP 302 Redirect. Приложение должно обработать ответ
HTTP Redirect.
Внимание!
Одно приложение может получить только одну авторизацию для одного пользователя. Повторная ав-
торизация (с тем же значением параметра client_id) аннулирует выданные ранее разрешения.
Существует возможность получить несколько авторизаций для одного пользователя: для этого необхо-
димо указать параметр instance_name. Повторная авторизация в этом случае учитывает оба пара-
метра — client_id и instance_name.
В качестве instance_name рекомендуется использовать уникальный идентификатор пользователя в при-
ложении, например его логин.
Параметры перенаправления с результатом авторизации:
Параметр Тип Описание
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
API Яндекс.Денег API для приложений11
Примечание:
Временный токен (значение поля code ответа) подлежит немедленному обмену на токен авторизации.
Время действия этого токена мало (менее 1 минуты).
Приложение должно получить и обработать ответ сервера Яндекс.Денег и немедленно самостоятельно
обменять временный токен на токен авторизации.
Если приложению не удалось получить ответ сервера, временный токен утерян, либо срок его действия
истек, необходимо повторить процедуру авторизации.
См. также
Получение токена
Отзыв токена
Авторизация приложения
Регистрация приложения
Получение токена
Если авторизация завершилась успехом, приложение должно немедленно обменять временный токен
на токен авторизации. Для этого необходимо отправить запрос, содержащий временный токен, на 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
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
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
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).
API Яндекс.Денег API для приложений12
client_id string Идентификатор приложения,
полученный при регистрации.
grant_type string Фиксированное значение:
authorization_code.
redirect_uri string URI, на который OAuth-сервер пере-
дает результат авторизации. Значе-
ние этого параметра при посимволь-
ном сравнении должно быть иден-
тично значению redirect_uri,
ранее переданному в запросе
authorize.
client_secret string Секретное слово для проверки под-
линности приложения. Указывается,
если сервис зарегистрирован с про-
веркой подлинности.
В ответ на запрос сервер Яндекс.Денег возвращает токен авторизации (access_token), который явл-
яется симметричным секретом приложения и дает право проводить операции со счетом пользователя.
Токен возвращается в виде JSON-документа, который (в зависимости от результата обмена) может со-
держать одно из следующих полей:
Параметр Тип Описание
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: 96
Cache-Control: no-store
{
"access_token":"SlAV32hkhjhkkefhkjGHGSDcbndbjhfSHDFhjdbfvbdsjfhbvfsjhjdfbvdfhjhj
khkwfervnrjKG"
}
Пример ответа при ошибке:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 25
Cache-Control: no-store
{
"error":"invalid_grant"
}
API Яндекс.Денег API для приложений13
Совет:
Использовать временный токен можно только один раз. Если приложению не удалось получить ответ
сервера за время жизни временного токена, процедуру авторизации следует повторить сначала.
Примечание:
Полученный access_token является симметричным секретом авторизации, поэтому разработчик
приложения должен предпринять меры по его защите: хранить токен в зашифрованном виде, предоста-
влять доступ к нему только после авторизации пользователя в приложении. Например, токен авториза-
ции может быть зашифрован с помощью алгоритма 3DES, где ключ шифрования — 4-х значный
ПИН код.
Внимание!
Срок действия токена 3 года. По истечении этого времени, токен автоматически аннулируется.
См. также
Запрос авторизации
Отзыв токена
Авторизация приложения
Регистрация приложения
Получение дополнительного токена
Однажды получив разрешение (токен) на выполнение различных операций, вы можете получить до-
полнительные токены на одно или несколько разрешений из scope исходного токена.
Это может понадобится, если вы, например, шифруете основной токен на пароль или пин-код в прило-
жении, а вам нужно в виджете отображать баланс пользователя. Для доступа к сервису через виджет
вам понадобится токен, который не будет зашифрован на пароль или пин-код, но при этом не будет
содержать платежных разрешений.
В этом случае вы можете получить дополнительный токен к вашему основному с подмножеством раз-
решений исходного токена.
Например, у вас есть access_token со scope = account-info payment-p2p. Вы можете сде-
лать запрос дополнительного токена со scope = account-info. Таким образом можно будет по-
лучать aux_token и в нашем примере баланс пользователя без дополнительных действий по расшиф-
ровке основного токена.
Параметры запроса:
Параметр Тип Описание
scope string Список запрашиваемых прав. Разде-
литель элементов списка — пробел.
Элементы списка чувствительны
к регистру.
Допустимо указывать следующие
права: account-info, operation-history
и operation-details.
В ответ на запрос сервер Яндекс.Денег возвращает дополнительный токен (aux_token).
API Яндекс.Денег API для приложений14
Токен возвращается в виде JSON-документа, который (в зависимости от результата обмена) может со-
держать одно из следующих полей:
Параметр Тип Описание
aux_token string Дополнительный токен авторизации,
присутствует в случае успеха.
error string Код ошибки. Присутствует в случае
ошибки.
Формат запроса:
POST /api/token-aux HTTP/1.1
Host: money.yandex.ru (или m.money.yandex.ru)
Accept-Encoding: gzip
Accept-Language:
Authorization: Bearer
Content-Type: application/x-www-form-urlencoded
Content-Length:
scope=
Пример запроса:
POST /api/token-aux HTTP/1.1
Host: money.yandex.ru
Accept-Encoding: gzip
Accept-Language: ru
Authorization: Bearer
41001417296262.39C64C899C736595ED47820C1EF245A2508A092F99FEFCB44728465618F8F06A2
1329ACB5E33BB69222CBF334F50CD21D9D04285FE60161B55
Content-Type: application/x-www-form-urlencoded
Content-Length: 31
scope=account-info
Пример ответа при успехе:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 589
Cache-Control: no-store
{"aux_token":"aux.
41001417296262.39C64C899C736595ED47820C1EF245A2508A092F99FEFCB44728465618F8F06A2
1329ACB5E33BB69222CBF334F50CD21D9D04285FE60161B55
CC461FBC5E7F75673B4B57211581B83C6B572F9E999EF180A45AEB42A0E2B730D88A503DA2098579
4589633FC88EB7B28835603EAA46C3A0F5E4F072F3C30C1F03325C654B583F"}
Пример ответа при ошибке:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 25
Cache-Control: no-store
{"error":"invalid_grant"}
Возможные ошибки:
Значение поля error Описание
invalid_scope Параметр scope отсутствует, либо имеет некорректное
значение или имеет логические противоречия.
invalid_grant Неверное значение параметра client_id
или client_secret, либо приложение не имеет права
запрашивать авторизацию (например, его client_id
заблокирован Яндекс.Деньгами).
API Яндекс.Денег API для приложений15
invalid_grant В выдаче aux_token отказано. Возможные причины:
• основной токен недействителен
• запрашивается дополнительный токен
по дополнительному токену
См. также
Запрос авторизации
Отзыв токена
Получение токена
Авторизация приложения
Регистрация приложения
Отзыв токена
Приложение может отозвать полученный токен авторизации. При этом все права, выданные этому то-
кену, будут отменены.
Для этого отправьте запрос на OAuth-сервер Яндекс.Денег, имеющий HTTP-заголовок Authorization,
содержащий отзываемый токен.
Методу revoke можно указать один из токенов: основной или дополнительный. Если указан основной
токен — отзывается основной токен и все дополнительные. Если указан дополнительный токен — от-
зывается только дополнительный токен. Если указан дополнительный токен и параметр запроса
revoke-all=true то отзывается основной токен и все дополнительные.
Параметры запроса:
Параметр Тип Описание
revoke-all boolean Отозвать основной токен и все до-
полнительные.
Необязательный параметр, по умол-
чанию false.
Запрос должен быть отправлен методом POST.
Пример запроса:
POST /api/revoke HTTP/1.1
Host: money.yandex.ru
Authorization: Bearer
01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF
Content-Length: 0
В ответ сервер Яндекс.Денег возвращает один из следующих HTTP-кодов:
HTTP-код ответа Описание
200 OK Токен успешно отозван.
400 Bad Request Формат HTTP-запроса не соответствует протоколу. Воз-
можные причины: запрос невозможно разобрать, HTTP-
заголовок Authorization отсутствует, либо имеет
некорректное значение.
401 Unauthorized Указанный токен не существует, либо уже отозван.
Пример успешного ответа:
HTTP/1.1 200 OK
Content-Length: 0
Пример ответа при ошибке:
API Яндекс.Денег API для приложений16
HTTP/1.1 400 Bad Request
Content-Length: 0
См. также
Запрос авторизации
Получение токена
Получение дополнительного токена
Авторизация приложения
Регистрация приложения
Права на выполнение операций
При вызове операций протокола необходимо передавать токен авторизации, который обладает соответ-
ствующими правами. Список прав запрашивается как значение параметра scope вызова authorize
OAuth2-авторизации приложения пользователем, права перечисляются через пробел.
Список возможных прав:
Название права Описание
account-info Получение информации о состоянии счета, см. метод
account-info.
operation-history Просмотр истории операций, см. метод operation-
history.
operation-details Просмотр деталей операции, см. метод operation-details.
incoming-transfers Прием/отмена входящих переводов с кодом протекции
и до востребования.
payment Возможность осуществлять платежи в конкретный
магазин или переводить средства на конкретный счет
пользователя, см. методы request-payment и process-
payment.
payment-shop Возможность осуществлять платежи во все доступные
для API магазины, см. методы request-payment и process-
payment.
payment-p2p Возможность переводить средства на любые счета,
номера телефонов, email-адреса других пользователей,
см. методы request-payment и process-payment
money-source Доступные методы проведения платежа, см. методы
request-payment и process-payment. Подробнее
см. Право money-source.
Ограничение:
В рамках scope нельзя одновременно использовать:
• право payment-p2p и права payment.to-account
• право payment-shop и права payment.to-pattern
API Яндекс.Денег API для приложений17
Совет:
Некоторые права требуют указания строковых значений, которые могут содержать символы, нарушаю-
щие синтаксис scope. Для таких символов следует применять backslash escaping согласно формату
JSON. Например: \" \\
Ограничения, применяемые к правам
К выдаваемым правам могут применяться ограничения. Ограничения задаются следующим образом:
имя_права.destination.limit
Ограничения, накладываемые на права:
Условие destination (получатель платежа)
Применяется к правам: payment.
В качестве значения допустимо указывать только одно из следующих условий:
• to-pattern(patternId) — ограничивает возможность провести платеж только
по заданному patternId;
• to-account(to) — ограничивает возможность перевода средств только на счет определенного
пользователя. В качестве идентификатора получателя допустимо указывать номер счета, номер
привязанного к счету получателя мобильного телефона или email-адрес пользователя.
Параметры ограничения:
Параметр Описание
to Идентификатор счета получателя перевода, номер
счета, привязанный к счету телефон или email.
Обязательный параметр.
Совет:
Номер мобильного телефона как идентификатор получателя перевода.
Если пользователь, получатель перевода, имеет привязанный к счету мобильный телефон, то в каче-
стве идентификатора получателя платежа можно вместо номера счета использовать номер привязан-
ного мобильного телефона. Указанный номер телефона должен соответствовать формату ITU-T E.164
Numbering plan of the international telephone service
Для России: полный номер, начинающийся с 7 без знака '+'.
Например: 79219990099
Совет:
Формат email.
Возможные варианты формата email-адреса описаны в википедии. Помните, что в email-адресе могут
быть символы, нарушающие синтаксис scope, например двойная кавычка.
Для таких символов следует применять backslash escaping согласно формату JSON. Например: \" \
\
Пример для определения получателя перевода по номеру счета:
.to-account("41001XXXXXXXX")
API Яндекс.Денег API для приложений18
Пример для определения получателя перевода по номеру привязанного мобильного телефона:
.to-account("79219990099")
Пример определения получателя перевода по email:
.to-account("username@yandex.ru")
Условие 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 коп. в сутки, пользователь может изменять сумму.
.limit(1,100.50)
Пример: одноразовый платеж на 1000 руб, пользователь не может изменить сумму.
.limit(,1000)
API Яндекс.Денег API для приложений19
Значение по умолчанию: 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")
API Яндекс.Денег API для приложений20
Описание протокола
• Формат запроса
• Формат ответа
• Права на выполнение операций
• Типы данных
Формат запроса
Запросы осуществляются посредством протокола HTTP 1.1 с использованием SSL (HTTPS), на адрес:
https://money.yandex.ru/api/
Авторизация запросов осуществляется согласно стандарту The OAuth 2.0 Authorization Framework:
Bearer Token Usage.
HTTP запросы должны содержать заголовок:
Authorization: Bearer
Примечание:
Указанный токен должен иметь права на исполнение запрашиваемого метода с заданным набором
параметров.
Требования безопасности:
1. Все сетевые взаимодействия производятся только по HTTPS.
2. Приложение должно проверять корректность SSL-сертификата сервера. Если SSL-сертификат
не прошел проверку, необходимо немедленно прекратить сессию, чтобы не допустить утечку данных
авторизации.
3. Не храните токен авторизации в открытом виде, в том числе в виде cookies.
4. Никогда не используйте токен авторизации в параметрах запросов (GET, POST, и пр.).
Для передачи параметров запроса используется следующий формат:
• каждый параметр указывается парой ключ/значение в виде параметра POST-запроса;
• MIME-тип: application/x-www-form-urlencoded;
• кодировка символов: UTF-8.
Пример запроса:
API Яндекс.Денег API для приложений21
POST /api/request-payment HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded
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 (согласно стандарту The OAuth 2.0 Authorization
Framework: Bearer Token Usage).
При отказе в авторизации запроса в ответе присутствуют следующие поля:
Поле Описание
error Код причины отказа в авторизации.
error_description Дополнительное текстовое описание причины отказа.
Коды причины отказа в авторизации:
HTTP-код ответа Значение поля error Описание
API Яндекс.Денег API для приложений22
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.
Приложению следует повторить запрос через некоторое время с теми же параметрами.
См. также
Формат запроса
Права на выполнение операций
Типы данных
Типы данных
Тип данных протокола Соответствующий JSON-тип Описание
string string Текстовая строка в кодировке UTF-8.
amount number Сумма. Число с фиксированной
точкой, две цифры после точки.
boolean boolean Логическое значение: true, false.
int number 32-битное знаковое целое число.
long number 64-битное знаковое целое число.
object object Вложенный объект JSON.
array array Массив объектов JSON.
datetime string Временная метка согласно стандарту
RFC3339 в следующем формате
YYYY-MM-DDThh:mm:ss.fZZZZZ
(см. расшифровку ниже).
API Яндекс.Денег API для приложений23
Расшифровка формата 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 на указанное число часов и минут).
Пример:
2011-07-01T19:00:00.000+04:00 — 19 часов 1 июля 2011 года, часовой пояс Europe/
Moscow (UTC+04:00).
См. также
Date and Time on the Internet: Timestamps
Формат запроса
Формат ответа
Права на выполнение операций
API Яндекс.Денег API для приложений24
Информация о счете пользователя
• Метод account-info
• Метод operation-history
• Метод operation-details
Метод account-info
Описание
Получение информации о состоянии счета пользователя.
Требуемые права токена: account-info
Входные параметры
Отсутствуют
Возвращает
В случае успеха возвращает JSON-документ со следующим содержимым:
Параметр Тип Описание
account string Номер счета пользователя.
balance amount Баланс счета пользователя.
currency string Код валюты счета пользователя. Всегда 643 (рубль РФ по
стандарту ISO 4217).
account_status string Статус пользователя. Возможные значения:
• anonymous — анонимный счет
• named — именной счет
• identified — идентифицированный счет
account_type string Тип счета пользователя. Возможные значения:
• personal — счет пользователя в Яндекс.Деньгах
• professional — профессиональный счет в Яндекс.Деньгах
avatar object Ссылка на аватар пользователя. Если аватарка пользователя
не установлена, параметр отсутствует.
balance_details object Расширенная информация о балансе. По умолчанию этот блок
отсутствует. Блок появляется если сейчас или когда либо ранее
были:
• зачисления в очереди
• задолженности
• блокировки средств
Подробности.
cards_linked array Информация о привязанных банковских картах.
API Яндекс.Денег API для приложений25
Параметр Тип Описание
Если к счету не привязано ни одной карты то параметр отсутствует.
Если к счету привязана хотя бы одна карта, параметр содержит спи-
сок данных о привязанных картах.
services_additional array Список подключенных дополнительных сервисов:
• link_alfabank — если подключена услуга "Связь с банком
Альфа-Клик" , установлено значение alfabank в профиле
пользователя
• link_openbank — если подключена услуга "Связь с банком
Открытие" , установлено значение open в профиле пользователя
Если ни одной подключенной услуги нет, то параметр отсутствует.
Параметры объекта avatar:
Параметр Тип Описание
url string Ссылка на аватар пользователя.
ts datetime Timestamp последнего изменения аватарки.
Параметры объекта balance_details:
Параметр Тип Описание
total amount Общий баланс счета.
available amount Сумма доступная для расходных операций.
deposition_pending amount Сумма средств стоящих в очереди пополнений. Если зачислений
в очереди нет то параметр отсутствует.
blocked amount Сумма заблокированных средств по решению исполнительных
органов. Если заблокированных средств нет то параметр
отсутствует.
debt amount Сумма задолженности (отрицательного остатка на счете). Если
задолженности нет то параметр отсутствует.
Параметры объекта cards_linked:
Параметр Тип Описание
pan_fragment string Маскированный номер карты.
type string Тип карты. Может отсутствовать, если неизвестен. Возможные
значения:
• VISA
• MasterCard
• AmericanExpress
• JCB
Пример запроса:
POST /api/account-info HTTP/1.1
Host: money.yandex.ru
Authorization: Bearer
01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF
Content-Type: application/x-www-form-urlencoded
Content-Length: 0
Пример ответа:
API Яндекс.Денег API для приложений26
{
"account":"4100123456789",
"balance":1000.00,
"currency":"643",
"account_status":"anonymous",
"account_type":"personal",
"avatar":{
"url":"http://avatars.yandex.net/get-yamoney-profile/yamoney-profile-30633298/
normal",
"ts":"2013-03-13T20:43:00.000+04:00"
},
"cards_linked":[
{
"pan_fragment":"510000******9999",
"type" : "MasterCard"
} ],
"services_additional":[
"link_alfabank"
]
}
Метод operation-history
Описание
Метод позволяет просматривать историю операций (полностью или частично) в постраничном режиме.
Записи истории выдаются в обратном хронологическом порядке: от последних к более ранним.
Требуемые права токена: operation-history.
Входные параметры
Параметр Тип Описание
type string Перечень типов операций (см. таблицу), которые требуется
отобразить. Типы операций перечисляются через пробел. Если
параметр отсутствует, выводятся все операции.
label string Отбор платежей по значению метки. Выбираются платежи,
у которых указано заданное значение параметра label вызова
request-payment.
from datetime Вывести операции ОТ момента времени (операции более поздние
или равные from). Если параметр отсутствует, выводятся
все операции.
till datetime Вывести операции ДО момента времени (операции более ранние
чем till). Если параметр отсутствует, выводятся все операции.
start_record string Если параметр присутствует то будут отображены операции,
начиная с номера start_record. Операции нумеруются с 0. (см.
замечание).
records int Количество запрашиваемых записей истории операций.
Допустимые значения: от 1 до 100, по умолчанию 30.
details boolean Показывать подробные детали операции. По умолчанию false.
Для отображения деталей операции требуется наличие права
operation-details.
Типы операций:
Тип Описание
deposition Пополнение счета (приход).
payment Платежи со счета (расход).
API Яндекс.Денег API для приложений27
Тип Описание
incoming-transfers- Непринятые входящие P2P-переводы любого типа.
unaccepted
Совет:
Логика отбора записей истории.
Отбор записей истории осуществляется по условиям:
• тип операции
• метка платежа
• интервал времени
Все условия аддитивны, каждое условие вносит дополнительное ограничение.
Правила выборки данных по интервалу времени:
1. Если заданы оба условия from и till, то отбор записей осуществляется за интервал времени рав-
ному или больше from и менее till.
2. Если заданы оба условия from и till, то отбор записей осуществляется за интервал времени рав-
ному или больше from и менее till.
3. Если задано только условие till, осуществляется отбор всех записей со временем меньше till.
4. Если оба условия условия from и till отсутствуют, записи выбираются без ограничения по вре-
мени.
Если история содержит большое количество операций, список операций выдается постранично.
По умолчанию выдается первая страница истории. Если есть хотя бы одна последующая страница, то в
ответе присутствует параметр next_record, определяющий порядковый номер её первой записи.
Чтобы получить следующую страницу, повторите запрос с теми же параметрами, добавив параметр
start_record и указав в нем порядковый номер первой записи следующей страницы, полученный
ранее из параметра next_record.
Чтобы получить большую выборку записей в интервале времени необходимо сформировать запрос с ус-
ловиями from и till, получить первую страницу истории, затем формировать запросы последующих
страниц истории с теми же значениями параметров from и till, а также параметром
start_record, значение которого было получено из параметра next_record ответа предыдущей
страницы истории.
Возвращает
Метод возвращает следующие параметры:
Параметр Тип Описание
error string Код ошибки. Присутствует при ошибке выполнения запроса.
next_record string Порядковый номер первой записи на следующей странице истории
операций. Присутствует в случае наличия следующей страницы
истории (см. замечание).
operations array Список операций.
Параметры операции:
Параметр Тип Описание
operation_id string Идентификатор операции.
API Яндекс.Денег API для приложений28
Параметр Тип Описание
status string Статус платежа (перевода). Может принимать следующие значения:
• success — платеж завершен успешно;
• refused — платеж отвергнут получателем или отменен
отправителем;
• in_progress — платеж не завершен, перевод не принят
получателем или ожидает ввода кода протекции.
datetime datetime Дата и время совершения операции.
title string Краткое описание операции (название магазина или источник
пополнения).
pattern_id string Идентификатор шаблона, по которому совершен платеж.
Присутствует только для платежей.
direction string Направление движения средств. Может принимать значения:
• in (приход);
• out (расход).
amount amount Сумма операции.
label string Метка платежа. Присутствует для входящих и исходящих переводов
другим пользователям Яндекс.Денег, у которых был указан
параметр label вызова request-payment.
type string Тип операции.
Возможные типы операций:
Тип Описание
payment-shop Исходящий платеж в магазин
outgoing-transfer Исходящий P2P-перевод любого типа
deposition Зачисление
incoming-transfer Входящий перевод или перевод до востребования.
Необходимость вызова incoming-transfer-accept/
incoming-transfer-reject определяется по полю
status=in_progress.
incoming-transfer-protected Входящий перевод с кодом протекции.
Необходимость вызова incoming-transfer-accept/
incoming-transfer-reject определяется по полю
status=in_progress.
Совет:
Если значение входного параметра 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.
API Яндекс.Денег API для приложений29
все прочие значения Техническая ошибка, повторите вызов операции
позднее.
Примечание:
Если история содержит большое количество операций, список операций выдается постранично.
По умолчанию выдается первая страница истории. Если есть хотя бы одна последующая страница, то в
ответе присутствует параметр next_record, определяющий порядковый номер ее первой записи.
Чтобы получить следующую страницу, повторите запрос с теми же параметрами, добавив параметр
start_record и указав в нем порядковый номер первой записи следующей страницы, полученный ранее
из параметра next_record.
Запрос полной истории
Пример запроса полной истории:
POST /api/operation-history HTTP/1.1
Host: money.yandex.ru
Authorization: Bearer
01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF
Content-Type: application/x-www-form-urlencoded
Content-Length: 9
records=3
Пример запроса последующих страниц истории платежей:
POST /api/operation-history HTTP/1.1
Host: money.yandex.ru
Authorization: Bearer
01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF
Content-Type: application/x-www-form-urlencoded
Content-Length: 40
type=payment&records=20&start_record=120
Пример ответа полной истории:
{
"next_record" : "4",
operations : [
{
"operation_id" : "1234567",
"status" : "success",
"pattern_id" : "2904",
"direction" : "out",
"amount" : 500.00,
"datetime" : "2011-07-11T20:43:00.000+03:00",
"title" : "Оплата ADSL-доступа компании XXX",
"type" : "payment-shop"
},
{
"operation_id" : "1234568",
"status" : "success",
"pattern_id" : "2901",
"direction" : "out",
"amount" : 300.00,
"datetime" : "2011-07-10T20:43:00.000+03:00",
"title" : "Прямое пополнение счета телефона YYY",
"type" : "payment-shop"
},
{
API Яндекс.Денег API для приложений30
"operation_id" : "1234569",
"status" : "success",
"direction" : "in",
"amount" : 1000.00,
"datetime" : "2011-07-10T20:40:00.000+03:00",
"title" : "Банк ZZZ, пополнение",
"type" : "deposit"
}
]
}
Пример ответа с подробными деталями операции при платеже в магазин:
{
"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",
"type" : "payment-shop"
}
]
}
Пример ответа с подробными деталями операции для исходящего перевода другому пользователю:
{
"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",
"title" : "Перевод на счет 4100123456789",
"recipient" : "4100123456789",
"recipient_type" : "account",
"message" : "Купите бублики",
"comment" : "Перевод пользователю Яндекс.Денег",
"codepro" : false,
"details" : "Счет получателя:\n4100123456789\nСумма к получению: 50,00 руб.",
"type" : "outgoing-transfer"
}
]
}
Пример ответа при неверно заданном параметре:
{
"error" : "illegal_param_type"
}
Метод operation-details
Описание
Позволяет получить детальную информацию об операции из истории.
Требуемые права токена: operation-details.
API Яндекс.Денег API для приложенийВы также можете почитать
