Руководство по использованию API системы Webisida.com

Интерфейс обработки платежей - Мерчант

Сервис Мерчант функционирует следующим образом:

Продавец создает на своем сайте форму запроса платежа.
На сайте продавца покупатель нажимает на кнопку подтверждения отправки формы и перенаправляется на адрес веб-сервиса Мерчант методом POST.
Веб-сервис Мерчант создает в аккаунте пользователя системы счет на оплату и перенаправляет покупателя на страницу оплаты счета на сайте системы.
В процессе оплаты сервис Мерчант отправляет уведомления о состояниях счета на обработчик по адресу <ResultURL>, при этом при получении уведомления типа verify обрабочик должен подтвердить или опровергнуть корретность счета, а при получении уведомлений типа pay или reject - выполнить операции по изменению состояния счета в своей системе учета. Список отправленных уведомлений можно увидеть нажав на номер счета на странице исходящих счетов.
После оплаты покупатель перенаправляется на страницу сайта продавца, расположенную по адресу <SuccessURL>.
Если в процессе оплаты произошла ошибка, либо покупатель отказался от совершения платежа, он перенаправляется на страницу сайта продавца, расположенную по адресу <FailURL>.

Технические документация

POST /Merchant/Pay
Форма запроса платежа - выставление счета пользователю системы

Эта форма передает запрос с веб-сайта продавца в интерфес Мерчант через веб-браузер пользователя.

Параметры
- Api (Int32): Идентификатор API-интерфейса.
- Timestamp (String): Время формирования запроса по UTC в формате YYYY-MM-dd HH:mm:ss.
- Sig (String): Подпись запроса, образованная путем вычисления MD5-хэша от результата склеивания через два двоеточия параметров Api, Timestamp, Key и остальных, отсортированных в алфавитном порядке обязательных параметров.
- InvId (Int32): Уникальный номер счета в системе учета вашей платформы.
- Payer (Int32): Идентификатор аккаунта пользователя системы, которому выставляется счет.
- Payee (Int32): Идентификатор аккаунта получателя платежа (ID владельца API интерфейса).
- Currency (BalanceCurrency): Валюта, в которой выставляется счет (Credits).
- Amount (Decimal): Cумма оплаты, не более 2-х цифр после точки, не менее 0.01.
- Note (String): Описание товара или услуги, за которую выставляется счет.
- ExpirationTimeout (Int32): Время действительности счета в секундах: минимум 300 (5 минут) максимум 2592000 (30 дней). После истечения срока пользователь не сможет оплатить счет.
- UserData[DataKey] (String): Дополнительные параметры, определяемые создателем счета, которые будут переданы скрипту обработки уведомлений в процессе уведомления об обработке счета. Если дополнительный параметры присутствуют, то они входят в подпись запроса в виде значений параметров в порядке, отсортированном по ключу DataKey.
Если после оплаты счета требуется отправить пользователя на адреса, отличные от тех, которые указаны в настройках API, адреса страниц возврата для успешного и неуспешного платежей можно передать в параметрах UserData[SuccessUrl] и UserData[FailUrl] соответственно.

Формирование подписи
```
md5(Api::Timestamp::Key::Amount::Currency::ExpirationTimeout::InvId::Note::Payee::Payer)
```
При наличии дополнительных параметров, например, UserData[SuccessUrl] и UserData[FailUrl]:
```
md5(Api::Timestamp::Key::Amount::Currency::ExpirationTimeout::InvId::Note::Payee::Payer::UserData[FailUrl]::UserData[SuccessUrl])
```
Пример формы запроса платежа
```
<form action="http://api.webisida.com/Merchant/Pay" method="POST">
	<input type="hidden" name="Api" value="0"/>
	<input type="hidden" name="Timestamp" value="2011-05-25 12:34:56"/>
	<input type="hidden" name="InvId" value="1"/>
	<input type="hidden" name="Payee" value="0"/>
	<input type="hidden" name="Payer" value="1"/>
	<input type="hidden" name="Amount" value="100"/>
	<input type="hidden" name="Currency" value="Credits"/>
	<input type="hidden" name="ExpirationTimeout" value="900"/>
	<input type="hidden" name="Note" value="Счет за услугу"/>
	<input type="hidden" name="Sig" value="8c629fcbdd886a340bef01e8fc92273b"/>
	<input type="submit" value="Перейти к оплате счета"/>
</form>
```
POST <ResultURL>
Форма уведомления об обработке платежа

По мере обработки счета система будет уведомлять вашу платформу о состоянии счета. Уведомления отправляются на обработчик по адресу <ResultURL> (задается в настройках API). При попытке оплаты счета обработчик сначала получит уведомление типа verify. После успешного получения положительного ответа от вашего обработчика и списания средств, отправляется уведомление типа pay. При любой ошибке или отклонении счета отправляется уведомление типа reject.
В случае, если после положительного ответа и оплаты счета ваш обработчик станет не доступен, уведомление pay может быть отправлено до 5 раз.

Параметры, передаваемые обработчику
- api (Int32): Идентификатор API-интерфейса.
- timestamp (String): Время формирования запроса по UTC в формате YYYY-MM-dd HH:mm:ss.
- sig (String): Подпись запроса, образованная путем вычисления MD5-хэша от результата склеивания через два двоеточия параметров Api, Timestamp, Key и остальных, отсортированных в алфавитном порядке обязательных параметров.
- method (String): Тип уведомления: verify - проверка действительности счета, pay - уведомление об оплате, reject - уведомление об отклонении счета.
- invId (Int32): Уникальный номер счета в системе учета вашей платформы.
- payer (Int32): Идентификатор аккаунта пользователя системы, которому выставляется счет.
- payee (Int32): Идентификатор аккаунта получателя платежа (ID владельца API интерфейса).
- currency (String): Валюта, в которой выставляется счет (Credits).
- amount (Decimal): Сумма платежа, не более 2-х цифр после точки, не менее 0.01.
- note (String): Описание товара или услуги, за которую выставляется счет.
- payeeTransactionId (Int32): Идентификатор транзакции, в результате которой произошло зачисление средств. Очень важно!!! При получении повторных уведомлений методом pay с одним и тем же payeeTransactionId необходимо вернуть результат выполнения предыдущего запроса, ничего не отправляя повторно пользователю, оплатившему счет.
- userData[DataKey] (String): Дополнительные параметры, переданные форме создания платежа.
Формирование подписи

Подпись уведомлений формируется с помощью ключа для подписи уведомлений, заданного в настройках мерчанта.
```
md5(api::timestamp::Key::amount::currency::invId::method::note::payee::payeeTransactionId::payer)
```
При наличии дополнительных параметров, например, UserData[SuccessUrl] и UserData[FailUrl]:
```
md5(api::timestamp::Key::amount::currency::invId::method::note::payee::payeeTransactionId::payer::userData[FailUrl]::userData[SuccessUrl])
```
Ответы для уведомлений

Ответы на уведомления ожидаются в формате JSON (application/json) в кодировке UTF-8, длиной до 1000 символов. В случае прихода отрицательного ответа текст из поля message может быть показан пользователю, а код ошибки будет отправлен на страницу неуспешного платежа вашей платформы. Код ошибки должен быть отрицательным чилом. Рекомендуется использовать числа в пределах -32000 to -32099.
- Положительный ответ
- Отрицательный ответ
```
{"result": {"message": "Запрос успешно обработан"}}
```
```
{"error": {"code": -32000, "message": "Товар закончился."}}
```
GET <SuccessURL>
Форма выполненного платежа

После выполения успешной оплаты пользователь будет перенаправлен на страницу вашего сайта по адресу <SuccessURL> (задается в настройках API).

Параметры, передаваемые обработчику
- invId (Int32): Уникальный номер счета в системе учета вашей платформы.
- amount (Decimal): Сумма платежа, не более 2-х цифр после точки, не менее 0.01.
Данный запрос не подписывается. Не следует использовать этот запрос для изменения состояния счета в вашей системе учета.
GET <FailURL>
Форма невыполненного платежа

После отклонения счета пользователь будет перенаправлен на страницу вашего сайта по адресу <FailURL> (задается в настройках API).

Параметры, передаваемые обработчику
- invId (Int32): Уникальный номер счета в системе учета вашей платформы.
- amount (Decimal): Сумма платежа, не более 2-х цифр после точки, не менее 0.01.
- errcode (String): Код ошибки.
  - 0 (None) - нет ошибки.
  - 1 (Reject) - счет отклонен.
  - 2 (Generic) - неизвестная ошибка.
  - 3 (InactiveApi) - мерчант не активен.
  - 4 (InvalidTimestamp) - недопустимое время формирования запроса (Timestamp).
  - 5 (InvalidSignature) - неверная подпись.
  - 6 (DuplicateInvId) - счет с таким же ID уже создан.
  - 7 (InvalidPayee) - пользователь (продавец) не существует.
  - 8 (InvalidPayer) - пользователь не существует.
  - 9 (InvalidAmount) - недопустимая сумма платежа.
  - 10 (InvalidCurrency) - недопустимая валюта счета.
  - 11 (InvalidExpiration) - недопустимое время жизни счета.
  - 12 (TooLongNote) - описание счета длиннее 1000 символов.
  - 13 (Expired) - счет просрочен.
  - любой другой положительный код - ошибка (коды зарезервированы для бущих изменений).
  - любой другой отрицательный код - ошибка (код получен от вашего обработчика).
Данный запрос не подписывается. Не следует использовать этот запрос для изменения состояния счета в вашей системе учета.

Руководство по использованию API системы Webisida.com

Интерфейс обработки платежей - Мерчант

Технические документация

POST /Merchant/Pay

Параметры

Формирование подписи

Пример формы запроса платежа

POST <ResultURL>

Параметры, передаваемые обработчику

Формирование подписи

Ответы для уведомлений

GET <SuccessURL>

Параметры, передаваемые обработчику

GET <FailURL>

Параметры, передаваемые обработчику