ЭСКРОУ (англ. escrow) — депонирование у третьего лица денежной суммы на имя другого лица с тем, чтобы она была выдана ему лишь после выполнения известного условия.
Введение
Задача Escrow-сервиса — прием и хранение информации о сделках, которые были размещены на сторонних веб-сайтах (доски объявлений, сервисы купли-продажи и т.п.).
Escrow-сервис WebMoney выступает доверенной стороной в сделке между продавцом и покупателем, и, посредством залогов, страхует их от обмана или недобросовестного выполнения условий.
Процесс сделки состоит из следующих этапов:
…
1. Инициатор сделки выставляет условия сделки и вносит свой гарантийный платёж.
2. На сервис отправляется информация о платеже и условия сделки.
3. Сервис отправляет торговой площадке информацию в виде ID сделки, и статуса (подтверждённая, отложенная).
4. Инициатор сделки может отменить/снять свое предложение не дожидаясь ответа 2-ой стороны. В этом случае гарантийный взнос возвращается или реактивируется для создания нового предложения.
5. Приходит согласие 2-ой стороны на сделку, взимается гарантийная оплата со 2-го участника сделки, о чём сообщается сервису.
6. Сделка переводится в статус «подтверждена» и ожидается сообщение от обоих участников об успешном завершении сделки. Также контролируется срок сделки.
7. Если от обеих сторон подтверждение пришло, то деньги внесённые в качестве гарантийной оплаты возвращаются участникам. Если же один из участников не подтверждает успешность сделки — гарантийная оплата не возвращается (резервируется на счету сервиса).
8. Возможна обоюдная отмена сделки, в этом случае залог либо возвращается, либо реактивируется для создания нового предложения. Если отмена сделки не двусторонняя, то гарантийные средства резервируются на счету сервиса, до подтверждения 2-м участником сделки.
9. Сделка уходит в историю.
Веб-сервис
Веб-сервис расположен по адресу http://escrow.webmoney.ru/ws/EscrowWS.asmx
Методы
_ public int Create(int serviceId, string externalId, string requesterId, string contractorId, string requesterAttribute, string contractorAttribute, decimal amount, string tranId, int currencyId, int duration, decimal requesterDeposit, decimal contractorDeposit, bool answerImmediately, string requesterPhone, bool sendNotify, string addParams, bool isAccepted, string comment, bool quickPay, DealType type, string hash, out DealInfo dealInfo)_
Входные параметры:
serviceId ID сервиса, сайта, магазина и т.д. который подключен для работы через
escrow-сервис. Выдается при подключении escrow-сервису.
externalId ID заявки в рамках внешнего сервиса
requesterId ID участника, в контексте сервиса, который является инициатором
сделки
contractorId ID участника, в контексте сервиса, который является 2-м участником
сделки
requesterAttribute дополнительный параметры для идентификации участника, например WMID
contractorAttribute дополнительный параметры для идентификации участника, например WMID
amount цена, сумма сделки
tranId ID транзакции, по которой была произведена оплата залога инициатором сделки
currencyId ID валюты. Валюта (или несколько валют) выдается при подключении к
escrow- сервису.
duration длительность сделки в днях
requesterDeposit сумма, которую должен заплатить (уже заплатил) инициатор сделки.
contractorDeposit сумма, которую должен заплатить 2-ой участник сделки.
answerImmediately флаг, который указывает, что при возникновении ошибки проверки платежа сделка не будет создана. Если answerImmediately=false, то сделка создается со статусом OfferNew и для проверки смены статуса на OfferApproved нужно вызывать метод веб-сервиса Get (см. ниже).
requesterPhone номер мобильного телефона для SMS-подтверждения сделки. Допускаются только цифры.
sendNotify флаг, который означает, что включено SMS-оповещение
addParams дополнительные параметры
quickPay флаг, который означает, что сделку можно будет оплатить залогом
type тип сделки (1 — продажа, 2 — покупка)
comment комментарий, название товара, описание и т.п. При необходимости возможно
иcпользование расширенного варианта (см. ниже)
hash Строка SHA1, которая формируется следующим образом:
serviceId + requesterId + requesterAttribute + amount + tranId + currencyId + duration + requesterDeposit + requesterPhone + contractorDeposit + addParams + type + secretKey
amount, requesterDeposit, contractorDeposit — строка в формате 0.00
secretKey — задается при подключении к escrow-сервису.
Расширение поля Comment:
Поле принимает XML в формате:
<OfferDescriptionInfo> <Type></Type> <Description></Description> <MeasureType></MeasureType> <Quantity></Quantity> <Properties></Properties> <Place></Place> <Conditions></Conditions> </OfferDescriptionInfo>Type тип сделки. возможные значения Product, Service
Description описание сути сделки
MeasureType мера. возможные значения Weight, Count
Quantity кол-во
Properties свойства сделки
Place место передачи товара, оказания услуги
Conditions условия передачи товара, услуги
Выходные параметры:
См. “Коды ошибок”
dealInfo класс DealInfo, который содержит информацию о сделке
Подтверждение сделки. Подписка на сделку 2-го участника.
public int Accept(int serviceId, int dealId, string contractorId,
string contractorAttribute, decimal amount, string tranId, int currencyId,
bool answerImmediately, string contractorPhone, bool sendNotify,
string addParams, string hash, out DealInfo dealInfo)
Входные параметры:
serviceId ID сервиса
dealId ID сделки
contractorId ID участника, в контексте сервиса, который является 2-м участником
сделки
contractorAttribute дополнительный параметры для идентификации участника, например
WMID
amount сумма, которую должен заплатить 2-ой участник сделки.
tranId ID транзакции, по которой была произведена оплата залога 2-м участником
сделки.
currencyId ID валюты. Валюта (или несколько валют) выдается при подключении к escrow- сервису.
answerImmediately флаг, который указывает, что при возникновении ошибки проверки платежа сделка не будет создана.
contractorPhone номер мобильного телефона для SMS-подтверждения сделки. Допускаются только цифры.
sendNotify флаг, который означает, что включено SMS-оповещение
addParams дополнительные параметры
hash Строка SHA1, которая формируется следующим образом:
serviceId + dealId + contractorId + contractorAttribute + amount + tranId + currencyId + contractorPhone + addParams + secretKey
Выходные параметры:
См. “Коды ошибок”
dealInfo класс DealInfo, который содержит информацию о сделке
public int AcceptWithReactivate(int serviceId, int dealId, string contractorId,
decimal requesterDeposit, decimal contractorDeposit,
string contractorAttribute, decimal amount, string tranId, int currencyId,
bool answerImmediately, string contractorPhone, bool sendNotify,
string addParams, string comment, string hash, out DealInfo dealInfo)
Входные параметры:
serviceId ID сервиса
dealId ID сделки
contractorId ID участника, в контексте сервиса, который является 2-м участником
сделки.
requesterDeposit сумма, которую должен заплатить (уже заплатил) инициатор сделки.
contractorDeposit сумма, которую должен заплатить 2-ой участник сделки.
contractorAttribute дополнительный параметры для идентификации участника, например
WMID
amount сумма, которую должен заплатить 2-ой участник сделки.
tranId ID транзакции, по которой была произведена оплата залога 2-м участником сделки.
currencyId ID валюты. Валюта (или несколько валют) выдается при подключении к escrow-сервису.
answerImmediately флаг, который указывает, что при возникновении ошибки проверки платежа сделка не будет создана.
contractorPhone номер мобильного телефона для SMS-подтверждения сделки. Допускаются только цифры.
sendNotify флаг, который означает, что включено SMS-оповещение
addParams дополнительные параметры
comment комментарий, название товара, описание и т.п.
hash Строка SHA1, которая формируется следующим образом:
serviceId + dealId + contractorId + requesterDeposit + contractorDeposit + amount + tranId + currencyId + contractorPhone + contractorAttribute + addParams + secretKey
Выходные параметры:
См. “Коды ошибок”
dealInfo класс DealInfo, который содержит информацию о сделке
Подтверждение сделки одним из участников
public int Approve(int serviceId, int dealId, string userId, string hash)
Входные параметры:
serviceId ID сервиса
dealId ID сделки
userId ID участника, в контексте сервиса.
hash Строка SHA1, которая формируется следующим образом:
serviceId + dealId + userId + secretKey
Выходные параметры:
См. “Коды ошибок”
Отмена сделки одним из участников
public int Cancel(int serviceId, int dealId, string userId, string hash)
Входные параметры:
serviceId ID сервиса
dealId ID сделки
userId ID участника, в контексте сервиса.
hash Строка SHA1, которая формируется следующим образом:
serviceId + dealId + userId + secretKey
Выходные параметры:
См. “Коды ошибок”
public int Get(int serviceId, int dealId, string hash, out DealInfo dealInfo)
Входные параметры:
serviceId ID сервиса
dealId ID сделки
hash Строка SHA1, которая формируется следующим образом:
serviceId + dealId + secretKey
Выходные параметры:
См. “Коды ошибок”
dealInfo класс DealInfo, который содержит информацию о сделке
public int GetAll(int serviceId, int status, string hash, out List<DealInfo> deals)
Входные параметры:
serviceId ID сервиса, сайта, магазина и т.д. который подключен для работы через
escrow-сервис. Выдается при подключении escrow-сервису.
status фильтр по статусу. 0 – нет фильтрации
hash Строка SHA1, которая формируется следующим образом:
serviceId + status + secretKey
Выходные параметры:
См. “Коды ошибок”
deals массив (List) классов DealInfo
public int GetList(int serviceId, int[] dealIds, int status, string hash,
out List<DealInfo> deals)
Входные параметры:
serviceId ID сервиса
dealIds массив ID сделок
status фильтр по статусу. 0 – нет фильтрации
hash Строка SHA1, которая формируется следующим образом:
serviceId + dealIds + status + secretKey
Выходные параметры:
См. “Коды ошибок”
Deals массив (List) классов DealInfo
Информация о сайте (сервисе), подключенному к escrow-сервису
public int GetServiceInfo(int serviceId, string hash, out ServiceInfo serviceInfo)
Входные параметры:
serviceId ID сервиса
secretKey SecretKey сервиса.
hash Строка SHA1, которая формируется следующим образом:
serviceId + secretKey
Выходные параметры:
См. “Коды ошибок”
ServiceInfo класс ServiceInfo, который содержит информацию о сайте
Проверка суммы залога при использовании SMS-подтверждения
_ public int CheckDepositForSMS(int serviceId, decimal amount, int currencyId)_
Входные параметры:
serviceId ID сервиса, сайта, магазина и т.д. который подключен для работы через
escrow-сервис. Выдается при подключении escrow-сервису.
amount сумма залога
currencyId ID валюты. Валюта (или несколько валют) выдается при подключении/регистрации к escrow-сервису
Выходные параметры:
См. “Коды ошибок”
Получение справочников
_ public string GetLocales(string culture)_
Входные параметры:
culture код языка (например, RU)
Выходные параметры:
data массив объектов в формате JSON
Возвращаемые классы
Класс DealInfo
Класс DealInfo содержит информацию о текущей сделке.
Свойства класса:
DealId ID сделки
Status статус сделки (см. ниже)
Type тип сделки (см. ниже)
ServiceId ID сервиса
Duration длительность сделки в днях
RequesterId ID инициатора сделки
RequesterDeposit залог инициатора сделки
ContractorDeposit залог 2-го участника сделки
Created дата создания сделки
ContractorId ID 2-го участника сделки
Comment комментарий
Updated дата обновления сделки (реакция на сделку 2-го участника)
CurrencyId ID валюты
Amount сумма сделки (см. ниже)
RequesterOutTransactionId ID транзакции, по которой произошел перевод средств
ContractorOutTransactionId ID транзакции, по которой произошел перевод средств
Коллекция DealType
Sell 1 (сдекла о продаже)
Buy 2 (сделка о покупке)
Коллекция DealStatus
OfferNew 1 (объявление создано, но не оплачено)
OfferApproved 2 (объявление оплачено)
OfferCancaled 4 (объявление отменено)
OfferTimeOut 8 (объявление просрочено)
OfferNotPaid 16 (объявление просрочено и не оплачено)
ContractNew 32 (получено согласие второго участника)
ContractAccepted 64 (деньги от второго участника пришли)
ContractCanceledByRequester 128 (инициатор отменил сделку, ждем второго)
ContractCanceledByContractor 256 (второй участник отменил сделку, ждем инициатора)
ContractCanceled 512 (оба участника сделки отменили сделку)
ContractSuccessByRequester 1024 (инициатор подтвердил сделку, ждем второго)
ContractSuccessByContractor 2048 (второй участник подтвердил сделку, ждем инициатора)
ContractSuccess 4096 (оба участника сделки подтвердили сделку) ContractCancelFailByRequester 8192 (инициатор не отменил сделку)
ContractCancelFailByContractor 16384 (второй участник не отменил сделку)
ContractSuccessFailByRequester 32768 (инициатор не подтвердил сделку)
ContractSuccessFailByContractor 65536 (второй участник не подтвердил сделку)
ContractTimeOut 131072 (сделка просрочена)
ContractNotPaid 262144 (сделку просрочена и не оплачена)
Коды валюты
0 WMZ
1 WMR
80 WMU
98 WME
Класс ServiceInfo
Класс ServiceInfo содержит информацию о сайте (сервисе), подключенному к escrow-сервису.
ServiceId ID сервиса
Name название сервиса
Url URL-сервиса
Comiss комиссия сервиса
Коды ошибок
В результате выполнения методы веб-сервиса возвращают код завершения операции.
| 0 | без ошибок |
| 1 | не верный хэш |
| 2 | не верные входные параметры |
| 3 | внутренняя ошибка |
| 4 | ошибка при использовании SMS-сервиса |
| 5 | неверный формат номера мобильного телефона |
| 6 | номер мобильного телефона уже используется в сделке |
| 7 | участник уже вступил в сделку |
| 8 | маленькая комиссия для SMS-подтверждения. Эта не критическая ошибка – операция считается завершенной. |
| 9 | сумма залога меньше минимальной. Минимальная сумма залога 0.02 |
RU
EN