Onpay.ru Wiki

Эта страница только для чтения. Вы можете посмотреть исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
====== Миграция с АПИ Робокасса ======

**ВНИМАНИЕ. При использовании данного типа АПИ, платежи без обязательных параметров проходить не будут, для "свободных платежей используйте апи Https1 или Https2.**
\\
====== Подключение ======
Настройки в Кабинете продавца:\\
https://secure.onpay.ru/merchants/edit
1. Выбрать "Робокасса" в Кабинете Onpay (тип АПИ)\\
2. Вы должны привести на своем сайте (кабинет Робокассы) ключи MerchantPass2 к зеркальному виду относительно MerchantPass1, то есть например:	\\
если **MerchantPass1** есть **myfirstpassword** то **MerchantPass2** должен быть **drowssaptsrifym**\\
3. Заполнить поле api_in_key в Кабинете Onpay, подставив туда значение своего ключа MerchantPass1\\
4. Поставить флаг - "уведомлять по апи" на https://secure.onpay.ru/merchants/edit\\
5. Заполнить поле "e-mail для уведомлений там же\\
На платежную форму нужно переходить в соответствии с описанием способа инициализации оплаты/ но вместо URL - https://auth.robokassa.ru/Merchant/Index.aspx, надо использовать - https://secure.onpay.ru/pay/login. **Остаток URL и содержимое запроса остается таким, каким было.**\\
\\
==== Особенности ====
Данное апи реализует не только 2 метода уведомления (check и pay), но и преобразование параметров, приходящих на платежную форму, конвертируя их в стандартные. Добавляет необходимые параметры при перенаправлении плательщика на страницу магазина после завершения платежа.\\
\\
Также есть реализация дополнительных XML сервисов, предусмотренных в агрегаторе Робокасса.\\
\\
Их всего 4 вида:\\
1) Интерфейс получения списка валют\\
2) Интерфейс получения списка доступных способов оплаты\\
3) Интерфейс получения курсов валют и расчета суммы для оплаты\\
4) Интерфейс получения состояния оплаты счета\\
\\
Реализацию имеет лишь Интерфейс получения состояния оплаты счета, остальные являются заглушками, возвращающими корректный ответ с пустыми данными.\\

====== Инициализация оплаты ======
Данная секция описывает формат приходящих данных на платежную форму, и занимается их преобразованием к стандартным в системе Onpay.\\
\\
Магазин отправляет пользователя по данному адресу для произведения им оплаты. Предварительно магазин должен у себя запомнить счет (номер, сумма, дата формирования).\\
\\
URL: https://pay/sMerchantLogin\\
\\
Параметры запроса (метод GET):\\
  MrchLogin=sMerchantLogin&
  OutSum=nOutSum&
  InvId=nInvId&
  Desc=sInvDesc&
  SignatureValue=sSignatureValue
  IncCurrLabel=sIncCurrLabel&
  Email=sEmail&
  Culture=sCulture
  [&shpa=yyy&shpb=xxx...-пользовательские_параметры_начинающиеся_с_SHP_в_сумме_до_2048_знаков]
\\
^ Параметр ^ Описание ^ Преобразуется в параметр ^
| sMerchantLogin | login магазина (обязательный параметр) | recipient |
| nOutSum | требуемая к получению сумма (обязательный параметр). Формат представления числа - разделитель точка. | price |
| nInvId | номер счета в магазине (должен быть уникальным для магазина). Может принимать значения от 1 до 2147483647. Если содержит пустое значение, вовсе не указан, либо равен "0", то при создании операции ей будет автоматически присвоен уникальный номер счета.  | pay_for |
| sInvDesc | описание покупки, можно использовать только символы английского или русского алфавита, цифры и знаки препинания. Максимальная длина 100 символов. | является составной часть параметра - note |
| sSignatureValue | контрольная сумма MD5(обязательный параметр) - строка представляющая собой 32-разрядное число в 16-ричной форме и любом регистре (всего 32 символа 0-9, A-F). Формируется по строке, содержащей следующие параметры, разделенные ':', с добавлением api_in_key - (устанавливается через интерфейс администрирования): sMerchantLogin:nOutSum:nInvId:api_in_key[:пользовательские параметры, в отсортированном алфавитном порядке]  | не преобразуется, лишь проверяется на валидность |
| sIncCurrLabel | Его значение игнорируется | |
| sEmail | e-mail пользователя. Пользователь может изменить его в процессе оплаты. | user_email |
| sCulture | опционально, язык общения с клиентом. Значения: en, ru. Если не установлен - берется язык региональных установок браузера. | обрабатывается, но не преобразовывается |
\\
При инициализации оплаты, вы можете передать дополнительные параметры, которые необходимы для работы вашего магазина. Переданные дополнительные параметры будут возвращены скриптам магазина по Result Url, Success Url и Fail Url. \\
Наименование дополнительных параметров должно ОБЯЗАТЕЛЬНО начинаться с "SHP" в любом регистре. \\
Например: Shp_item, SHP_1, ShpEmail, shp_oplata, ShpClientId и т.д. \\
\\
При инициализации оплаты, каждый из передаваемых дополнительных параметров, ОБЯЗАТЕЛЬНО должен быть включён в подсчёт контрольной суммы (MD5). \\
Например, если переданы пользовательские параметры shpb=xxx и shpa=yyy, то подпись формируется из строки: \\
sMerchantLogin:nOutSum:nInvId:sMerchantPass1:shpa=yyy:shpb=xxx \\
\\
При проверке контрольной суммы (MD5) в скриптах магазина по Result Url, Success Url и Fail Url также необходимо учитывать полученные дополнительные параметры при подсчёте контрольной суммы (MD5). См. соответствующие разделы документации.\\
\\
====== Запросы к мерчанту ======
==== Check ====
Check не используется в данном типе апи, всегда возвращает true\\

==== Pay ====
В случае успешного проведения оплаты робот системы проводит запрос по URL API, указанный в настройках магазина в зеленом кабинете, с указанием следующих параметров (методом, выбранным в настройках): \\
  OutSum=nOutSum&
  InvId=nInvId&
  SignatureValue=sSignatureValue
  [&пользовательские_параметры] 
\\
Если в настройках в качестве метода отсылки данных был выбран Email, то в случае успешного проведения оплаты робот системы отправит вам сообщение на email, указанный в качестве notification_email модели User, с указанием параметров, указанных выше.\\
\\
^ Параметр ^ Описание ^ 
| nOutSum | полученная сумма. Сумма будет передана в рублях. Формат представления числа - разделитель точка. |
| nInvId | номер счета в магазине |
| sSignatureValue | контрольная сумма MD5 - строка представляющая собой 32-разрядное число в 16-ричной форме и любом регистре (всего 32 символа 0-9, A-F). Формируется по строке, содержащей некоторые параметры, разделенные ':', с добавлением api_in_key - (устанавливается через интерфейс администрирования) т.е. nOutSum:nInvId:api_in_key[:пользовательские параметры, в отсортированном порядке]. К примеру если при инициализации операции были переданы пользовательские параметры shpb=xxx и shpa=yyy то подпись формируется из строки ...:sMerchantPass2:shpa=yyy:shpb=xxx |
\\
Скрипт, находящийся по Result URL должен проверить правильность контрольной суммы и соответствия суммы платежа ожидаемой сумме. При формировании строки подписи учтите формат представления суммы (в строку при проверке подписи вставляйте именно полученное значение, без какого-либо форматирования).\\
\\
Данный запрос производится после получения денег.\\
\\
Факт успешности сообщения магазину об исполнении операции определяется по результату, возвращаемому системе. Результат должен содержать "OKnMerchantInvId", т.е. для счета #5 должен быть возвращен текст "OK5".\\
\\
В случае невозможности связаться со скриптом по адресу URL API (связь прерывается по time-out-у либо по отсутствию DNS-записи, либо получен не ожидаемый ответ) на notification_email отправляется письмо и запрос pay считается завершенным успешно. В случае систематического отсутствия связи между серверами магазина и сервисом лучше использовать метод определения оплаты с применением интерфейсов XML, а самый желательный и защищенный способ - совмещенный.\\
\\
==== Переадресация пользователя при успешной оплате (SuccessURL) ====
В случае успешного исполнения платежа Покупатель может перейти по данному адресу.\\
\\
Методом, выбранным при регистрации, будут переданы следующие параметры ("чек" об оплате): \\
  OutSum=nOutSum&
  InvId=nInvId&
  SignatureValue=sSignatureValue&
  Culture=sCulture
  [&пользовательские_параметры]
\\
^ Параметр ^ Описание ^ 
| nOutSum | полученная сумма. Сумма будет передана в рублях. Формат представления числа - Разделитель точка. |
| nInvId | номер счета в магазине |
| sSignatureValue | контрольная сумма MD5 - строка представляющая собой 32-разрядное число в 16-ричной форме и любом регистре (всего 32 символа 0-9, A-F). Формируется по строке, содержащей некоторые параметры, разделенные ':', с добавлением api_in_key (указывается при регистрации) т.е. nOutSum:nInvId:sMerchantPass1[:пользовательские параметры, в отсортированном порядке]. К примеру если при инициализации операции были переданы пользовательские параметры shpb=xxx и shpa=yyy то подпись формируется из строки ...:api_in_key:shpa=yyy:shpb=xxx |
| sCulture | язык общения с клиентом, выбранный при инициализации оплаты. Значения: en, ru. |
\\
Переход пользователя по данному адресу с корректными параметрами (соответствия CRC) означает, что платеж по реквизитам Продавца выполнен успешно. Сервис несет финансовую ответственность перед Продавцом в соответствии с Соглашением за достоверность такого подтверждения.\\
\\
Однако для дополнительной защиты крайне желательно, чтобы факт оплаты проверялся скриптом исполняемым при переходе на Result URL, или путем запроса XML-интерфейса о результате данной платежной операции, и только при реальном наличии счета с номером nMerchantInvId в БД магазина.\\
\\
==== Переадресация пользователя при отказе от оплаты (FailURL) ====
В случае отказа от исполнения платежа Покупатель перенаправляется по данному адресу.\\
\\
Для того, чтобы Продавец мог разблокировать заказанный товар на складе при отказе от его оплаты методом, выбранным при регистрации, будут переданы параметры: \\
  OutSum=nOutSum&
  InvId=nInvId&
  Culture=sCulture
  [&пользовательские_параметры]

^ Параметр ^ Описание ^ 
| nOutSum | полученная сумма. Сумма будет передана в рублях. Формат представления числа - Разделитель точка. |
| nInvId | номер счета в магазине |
| sCulture | язык общения с клиентом, выбранный при инициализации оплаты. Значения: en, ru. |

====== XML-интерфейсы ======
==== Общая информация ====
Всего есть 4 вида интерфейсов:\\
1) Интерфейс получения списка валют\\
2) Интерфейс получения списка доступных способов оплаты\\
3) Интерфейс получения курсов валют и расчета суммы для оплаты\\
4) Интерфейс получения состояния оплаты счета\\
Реализацию имеет лишь Интерфейс получения состояния оплаты счета, остальные являются заглушками, возвращающими корректный ответ с пустыми данными.\\
\\
Запросы к интерфейсам можно отправлять методом HTTP GET или HTTP POST:\\
URL для запросов HTTP GET/POST:\\
  /xml_interfaces/GetCurrencies
  /xml_interfaces/GetPaymentMethods
  /xml_interfaces/GetRates
  /xml_interfaces/OpState - реализован
\\
Ответ на запрос, переданный методом HTTP GET/POST, возвращается в формате XML-документа. Документ имеет следующую структуру:\\
\\
  <?xml version="1.0" encoding="utf-8" ?>
  <...>
    <Result>
      <Code>integer</Code>
      <Description>string</Description>
    </Result>
    <...>
      Запрошенные данные (возвращаются только в случае успешного выполнения запроса)
      Required data
    </...>
  </...>
\\
Элемент Result содержит информацию о результате выполнения запроса:\\
**Code**\\
- результат выполнения запроса. В случае успешного выполнения - 0, в противном случае код ошибки. Если во время выполнения запроса произошла ошибка, то в ответе не будет содержаться дополнительных элементов с запрашиваемыми данными\\
**Description**\\
- текстовое описание результата выполнения запроса\\
\\
Общие коды ошибок, которые могут возвращаться всеми запросами:\\
2 - информация о магазине с таким MerchantLogin не найдена или магазин не активирован\\
1000 - внутренняя ошибка сервиса\\
\\
==== Интерфейс получения состояния оплаты счета (OpState) ====
Описание:\\
Возвращает детальную информацию о текущем состоянии и реквизитах оплаты. \\
\\
Необходимо помнить, что операция инициируется не в момент ухода пользователя на оплату, а позже - после подтверждения его платежных реквизитов, т.е. вы вполне можете не находить операцию, которая по вашему мнению уже должна начаться.\\
\\
Название метода:\\
OpState\\
\\
Параметры запроса:\\

^ Параметр ^ Описание ^ 
| MerchantLogin | логин магазина, строка |
| InvoiceID | номер счета магазина, целое число |
| Signature | контрольная сумма MD5 - строка, представляющая собой 16-разрядное число в hex-формате и любом регистре (всего 32 символа 0-9, A-F). Формируется по строке, содержащей все обязательные параметры, разделенные «:», с добавлением api_in_key (указывается при регистрации) т.е. MerchantLogin:InvoiceID:api_in_key |
\\
Пример запроса методом HTTP GET:\\
/xml_interfaces/OpState?MerchantLogin=demo&InvoiceID=1932809606&Signature=9e2bf657364d25acf5905b4ac4f50e39\\
\\
Формат ответа для запросов HTTP GET/POST:\\
  <?xml version="1.0" encoding="utf-8" ?>
  <OperationStateResponse>
    <Result>
      <Code>integer</Code>
      <Description>string</Description>
    </Result>
    <State>
      <Code>integer</Code>
      <RequestDate>datetime</RequestDate>
      <StateDate>datetime</StateDate>
    </State>
    <Info>
      <IncCurrLabel>string</IncCurrLabel>
      <IncSum>decimal</IncSum>
      <IncAccount>string</IncAccount>
      <PaymentMethod>
        <Code>string</Code>
        <Description>string</Description>
      </PaymentMethod>
      <OutCurrLabel>string</OutCurrLabel>
      <OutSum>decimal</OutSum>
    </Info>
  </OperationStateResponse>
\\
Описание возвращаемых данных:\\

^ Параметр ^ Описание ^ 
| Code | отображает код текущего состояния операции оплаты счета. Возможные значения: 5 - операция только инициализирована, деньги от покупателя не получены. Состояние ввода денег. Это означает, что от пользователя ещё не поступила оплата по выставленному ему счёту или платёжная система, через которую пользователь совершает оплату, ещё не подтвердила факт оплаты. Либо (при оплате смс-сообщениями) оплата поступили частично, и система ожидает прихода оставшейся суммы. 100 - операция выполнена, завершена успешно. Платёж проведён успешно, деньги зачислены на счёт (кошелёк) продавца, уведомление об успешном платеже отправлено продавцу. |
| RequestDate | дата/время ответа на запрос (*) |
| StateDate | дата/время последнего изменения состояния операции (*) |
| IncCurrLabel | валюта, которой платил клиент |
| IncSum | сумма, уплаченная клиентом, в единицах валюты IncCurrLabel |
| Code | код способа оплаты |
| Description | текстовое описание |
| OutCurrLabel | валюта, в которой получает средства магазин |
| OutSum |сумма, зачисленная на счет магазина, в единицах валюты OutCurrLabel |
\\
* Формат данных типа дата/время\\
Дата/время передаются в формате, рекомендованном стандартом ISO 8601 (YYYY-MM-DDThh:mm:ss.fffffffZZZZZ), где:\\
  YYYY - год, 4 цифры
  MM - месяц, 2 цифры
  DD - день месяца, 2 цифры (от 01 до 31)
  T – латинский символ «T» в верхнем регистре
  hh - часы, 2 цифры (24-часовой формат, от 00 до 23)
  mm - минуты, 2 цифры (от 00 до 59)
  ss - секунды, 2 цифры (от 00 до 59)
  fffffff – от 1 до 7 цифр дробной части секунд
  ZZZZZ - описатель временной зоны, может принимать значения:
  +hh:mm или -hh:mm – смещение относительно UTC (показывает, что указано локальное время, которое на данное число часов и минут опережает или отстает от UTC)
  символ «Z» (должен быть в верхнем регистре), означает, что момент времени представлен в UTC зоне (эквивалентно +00:00 и -00:00)

Пример: 2010-02-11T16:07:11.6973153+03:00\\
\\
Коды ошибок, специфичные для этого интерфейса:\\
1 - неверная цифровая подпись запроса\\
3 - информация об операции с таким InvoiceID не найдена\\

!!!Внимание, XML интерфейсы, кроме OpState, не поддерживаются, а являются лишь заглушками\\
Onpay.ru Wiki

Инструменты пользователя

Инструменты сайта

Инструменты страницы
