Получение курсов валют, установленных по провайдерам
Для получения установленных курсов валют по провайдерам, а так же настроек того, в какой валюте провайдер принимает сумму к зачислению, используется команда ratesCommand.
Формат запроса
Стандартный запрос к XML шлюзу, содержащий команду ratesCommand.
Пример:
3392
fEqNCco3Yq9h5ZUglD3CZJT4lBs=
Подписываемая строка для сообщения формируется путем склеивания строки «Rates» и значения атрибута guid корневого тега request.
Для примера, приведенного выше, подписываемая строка будет следующей:
«Rates54249320-9ca7-42a8-81d8-5f475b121a6c»
Формат ответа
Ответ от XML шлюза приходит в стандартном виде и содержит список объектов ProviderRate в виде XML.
Пример успешного ответа:
guid="54249320-9ca7-42a8-81d8-5f475b121a6c">
sund
710">1
utst" currency_id="643">
978">0.0215224286361577
skpe" currency_id="978">
368">10.00
В данном примере возвращены правила конвертации по 2м провайдерам: sund и utst.
При проведении платежа в пользу провайдера sund в поле amount указывается сумма в валюте с кодом 710 (Африканские Ранды) о чем свидетельствует атрибут currency_id тега payment. При этом зачисление провайдеру происходит так же в 710 валюте, 1 к 1 (тег provider_rate). С дилерского счета при этом списывается 643 валюта (Российские рубли) по курсу 4.03818 (тег dealer_rate).
При проведении платежа в пользу провайдера utst в поле amount указывается сумма в валюте 643. При этом непосредственно провайдеру отсылается сумма в валюте с кодом 978 (Евро) с курсом 0.0215224286361577. С дилерского счета списывается сумма в валюте с кодом 643, 1 к 1 с переданной суммой в поле amount.
На примере двух этих провайдеров можно увидеть 2 стандартные схемы.
В первой (провайдер sund) по шлюзу передается сумма к зачислению в валюте провайдера, конвертация касается только расчета суммы, которая будет списана со счета дилера. Схема удобна для онлайновой схемы проведения платежа (интернет кошельки), когда пользователь может вводить любую сумму в валюте дилера (подразумевается что дилер и пользователь работают в одной валюте). Еще можно сказать, что по шлюзу XML клиент говорит – зачисли пользователю вот столько и посчитай, сколько с меня за это спишут.
Во второй схеме (провайдер utst) по шлюзу передается сумма к зачислению в валюте дилера, конвертация касается только зачисляемой суммы провайдеру. Схема удобна для терминальных сетей, когда пользователь вставил определенную сумму в терминал и хочет на всю эту сумму получить услугу провайдера. Можно сказать, что шлюзу говорится в этом случае – спиши с меня столько рублей, а провайдеру зачисли столько, сколько получится при конвертировании.
Так же стоит помнить, что метод возвращает описание только тех провайдеров, у которых необходимо осуществлять конвертацию во время обработки. Т.е. если у вас есть подключенный провайдер, принимающий по шлюзу рубли, зачисляющий конечному пользователю рубли и списывающий с вашего счета так же рубли, описание этого провайдера методом возвращено не будет (в целях экономии трафика).
Получение установленных комиссий по провайдерам
Для получения установленных комиссий по провайдерам используется команда commissionCommand.
Формат запроса
Стандартный запрос к XML шлюзу, содержащий команду commissionsCommand.
Пример:
3392
fEqNCco3Yq9h5ZUglD3CZJT4lBs=
Подписываемая строка для сообщения формируется путем склеивания строки «Commissions» и значения атрибута guid корневого тега request.
Для примера, приведенного выше, подписываемая строка будет следующей:
«Commissions54249320-9ca7-42a8-81d8-5f475b121a6c»
Формат ответа
Ответ от XML шлюза приходит в стандартном виде и содержит объект commissionsResult в виде XML.
Пример успешного ответа:
guid="54249320-9ca7-42a8-81d8-5f475b121a6c">
В скором времени планируется добавлять дополнительное поле для фиксированного размера комиссии - fix.
Проведение платежей
Обработка объекта PaymentStatus
Все ответы на запросы по проведению платежей содержат объект PaymentStatus, который содержит информацию о текущем состоянии платежа на сервере X-plat. Именно поэтому понимание обработки этого объекта XML клиентом является важным для понимания всего процесса проведения платежа.
Ниже представлена схема обработки объекта PaymentStatus:
Двухфазное проведение платежа
Двухфазная обработка платежа состоит из двух фаз. На первой фазе проверяется возможность проведения платежа. Если она прошла успешно (платеж корректен и может быть проведен), то выполняется вторая фаза, после которой платеж непосредственно выполняется.
При выполнении первой фазы, на балансе дилера блокируются средства, необходимые для выполнения платежа. Если первая фаза прошла неуспешно, то средства возвращаются дилеру. После успешного проведения второй фазы, средства списываются окончательно. При неуспешном выполнении второй фазы, средства возвращаются дилеру.
Общая схема проведения платежа
Первая фаза. Проверка возможности проведения платежа
Формируется запрос для отсылки команды checkCommand с описанием проверяемого платежа. После этого запрос посылается на XML шлюз. В случае получения не финального состояния платежа, необходимо через некоторый промежуток запросить статус зарегистрированного платежа и повторять это до тех пор, пока состояние платежа не будет финальным. Затем полученный ответ обрабатывается XML клиентом.
Пример запроса для проведения первой фазы:
guid="c17d8aae-ba95-46eb-911d-0b7d649c9a6b" >
3392
fEqNCco3Yq9h5ZUglD3CZJT4lBs=
6437282" provider="bee" amount="1.00">
Пример успешного ответа (состояние конечное):
290361">
83401874
2008-09-16T00:27:18.95
Схема проведения первой фазы двухфазного платежа:
Вторая фаза. Проведение платежа
Если первая фаза прошла удачно (состояние платежа PsChecked), то для подтверждения проведения платежа необходимо выполнить вторую фазу.
Для этого формируется запрос для отсылки команды payCommand с описанием зарегистрированного платежа. После этого запрос посылается на XML шлюз. В случае получения не финального состояния платежа, необходимо через некоторый промежуток запросить статус зарегистрированного платежа и повторять это до тех пор, пока состояние платежа не будет финальным. Затем полученный ответ обрабатывается XML клиентом.
Пример запроса для проведения второй фазы:
guid="c17d8aae-ba95-46eb-911d-0b7d649c9a6b" >
3392
fEqNCco3Yq9h5ZUglD3CZJT4lBs=
100">
290361" />
Пример успешного ответа (состояние конечное):
290361">
83401874
2008-09-16T00:27:18.95
Схема проведения второй фазы двухфазного платежа:
Обработка ответа и ошибок
Все используемые для двухфазного проведения платежа команды (check, pay, status) возвращают один тип ответа, который содержит объект PaymentStatus.
В случае возвращения ошибки обработки запроса (тег response.result), необходимо разрешить возникшую проблему. После разрешения проблем можно повторить запрос снова.
В случае возвращения ошибки обработки платежа, действовать в соответствии с типом ошибки.
В случае возвращения неуспешного финального состояния платежа, платеж можно попытаться перепровести с новым идентификатором со стороны клиента, если тип состояния был FinalNotFatal (означает, что платеж не удалось провести, но при повторной посылке он может и пройти).
Однофазное проведение платежа
Однофазное выполнение платежа проходит в одну фазу. В отличие от двухфазного проведения платежа, от XML клиента не требуется подтверждения платежа, после того, как возможность оплаты будет проверена проводящим сервером X-plat, платеж автоматически будет послан на отправку.
При однофазном проведении платежа средства необходимые на проведение платежа, блокируются на счете дилера. Если проведение платежа завершилось ошибкой, то средства возвращаются на счет дилера. При успешном проведении платежа, средства списываются окончательно.
Общая схема проведения однофазного платежа
Посылка запроса
Формируется запрос для отсылки команды cashinCommand с описанием платежа на оплату. После этого запрос посылается на XML шлюз. В случае получения не финального состояния платежа, необходимо через некоторый промежуток времени запросить статус зарегистрированного платежа и повторять это до тех пор, пока состояние платежа не будет финальным. Затем полученный ответ обрабатывается XML клиентом.
В случае возвращения ошибки обработки запроса (тег response.result), необходимо разрешить возникшую проблему. После разрешения проблем можно повторить запрос снова.
В случае возвращения ошибки обработки платежа, действовать в соответствии с типом ошибки.
В случае возвращения неуспешного финального состояния платежа, платеж можно попытаться перепровести с новым идентификатором со стороны клиента, если тип состояния был FinalNotFatal (означает что платеж не удалось провести, но при повторной посылке он может и провестись).
Пример запроса для однофазного проведения платежа:
guid="c17d8aae-ba95-46eb-911d-0b7d649c9a6b" >
3392
fEqNCco3Yq9h5ZUglD3CZJT4lBs=
6437282" provider="bee" amount="1.00">
Пример успешного ответа (состояние не конечное):
290361">
83401874
2008-09-16T00:27:18.95
Пакетная обработка платежей
Иногда возникает необходимость воспользоваться пакетной обработкой запросов (например, когда XML шлюз был некоторое время недоступен). Для этого существует команда batchCommand. В команде передается список платежей, для которых необходимо выполнить команду check, pay, status или cashin. Все эти команды поочередно асинхронно выполняются XML шлюзом в рамках одного запроса. Результат возвращается в виде объекта batchResult, который содержит список объектов PaymentStatus. Каждый объект PaymentStatus затем обрабатывается XML клиентом.
Пример пакетного запроса (два платежа по однофазной схеме + запрос статуса):
guid="c17d8aae-ba95-46eb-911d-0b7d649c9a6b" >
3392
fEqNCco3Yq9h5ZUglD3CZJT4lBs=
6437282" provider="bee" amount="1.00">
6437283" provider="bee" amount="15.00">
6430361" />
Контактная информация
[email protected]
Служба технической поддержки
+7 (3532) 588899
<предыдущая страница