Описание интерфейса сервиса Idram

Описание интерфейса сервиса Idram Merchant Interface
Данный документ описывает схему взaимодействия магазина с системой Idram Merchant
Interface.
Для любого магазина, работающего через систему Idram, устанавливаются 3 адреса(URL) ,
один секретный ключ и один email адрес.





SUCCESS_URL
FAIL_URL
RESULT_URL
SECRET_KEY
EMAIL
На данный момент эти 4 параметра устанавливаются техническим персоналом платежной
системы Idram, при заключении договора с владельцем магазина.
URL скрипта или html страницы, на которую нужно
SUCCESS_URL перенаправить пользователя в том случае если
операция успешна завершена
URL скрипта или html страницы, на которую нужно
перенаправить пользователя в том случае если не
FAIL_URL
удалось произвести операцию
RESULT_URL URL скрипта-оброботчика запросов системы Idram.
Секретный ключ, известный только магазину
SECRET_KEY
продавца и системе Idram
Email адрес, на который будет высылаться
подверждение платежа, в том случае если не получен
EMAIL
ответ "OK" от магазина во время процедуры
подтверждения факта оплаты
Магазин должен сгенерировать html форму, содержащую следующие hidden поля :
Поле
Описание
(RU,EN,AM)
EDP_LANGUAGE
В этом поле продавец выбирает язык
интерфейса Idram.
IdramID продавца, на который покупатель
EDP_REC_ACCOUNT
должен совершить платеж.
Описание товара или услуги. Формируется
продавцом.
EDP_DESCRIPTION
Если присутствует, добавляется в назначение
платежа в операцию перевода Idram.
Сумма платежа, которую продавец желает
получить от покупателя. Сумма должна быть
EDP_AMOUNT
больше нуля, дробная часть отделяется
точкой.
EDP_BILL_NO
EDP_EMAIL
Дополнительные
параметры продавца
В этом поле продавец задает номер покупки
в соответствии со своей системой учета.
Email адрес, на который будет высылаться
подверждение платежа, в том случае если не
получен ответ "OK" от магазина во время
процедуры подтверждения факта оплаты.
Если присутствует, переопределяет значение
EMAIL для данной операции.
Все поля формы, не имеющие в названии
префикса "EDP_", обрабатываются
сервисом Idram автоматически и передаются
на веб-сайт продавца после выполнения
платежа.
Форма должна отправлять запрос на URL https://money.idram.am/payment.aspx (параметр
action) используя метод POST. Интерфейс Idram использует кодировку utf-8. Это означает,
что поле EDP_DESCRIPTION должно содержать текст в кодировке utf-8. Если магазин
продавца использует кодировку win1251, то нужно направлять форму на URL
https://money.idram.am/1251/payment.aspx. Ниже приведен пример html формы запроса
платежа.
<form action="https://money.idram.am/payment.aspx" method="POST">
<input type="hidden" name="EDP_LANGUAGE" value="RU">
<input type="hidden" name="EDP_REC_ACCOUNT" value="100000114">
<input type="hidden" name="EDP_DESCRIPTION" value="Описание товара">
<input type="hidden" name="EDP_AMOUNT" value="1900">
<input type="hidden" name="EDP_BILL_NO" value="1806">
<input type="submit" value="submit">
</form>
После того, как пользователь нажимает на кнопку "Submit", он перенаправляется на страницу
платежной системы Idram и проходит аутентификацию. После этого система Idram дважды
направляет запрос по указанному URL (RESULT_URL, см. выше), в первый раз (а) для
подтверждения подлинности заказа, во второй раз (б) для подтверждения факта оплаты.
(а) Подтверждение подлинности заказа(предварительный запрос)
До того, как перечислить средства со IdramID покупателя на IdramID продaвца, система Idram
Merchant Interface инициирует http запрос на URL RESULT_URL(см. выше). Этот запрос
проверяет подлинность представленного к оплате счета. Эта форма передает продавцу
параметры выполняемого платежа непосредственно перед его выполнением. Она имеет
следующие поля:
значение - "YES". Этот параметр указывает,
EDP_PRECHECK
что запрос предварительный
В этом поле передается номер покупки в
соответствии с системой учета продавца,
EDP_BILL_NO
полученный сервисом с веб-сайта продавца.
IdramID продавца(в системе Idram), на который
EDP_REC_ACCOUNT
покупатель совершил платеж
Сумма, которую должен заплатить покупатель.
Дробная часть отделяется точкой.
Магазин должен проверить все полученные данные, и в случае если данные соответстуют
действительности(т.е. такой заказ действительно имел место) отправить сообщение "OK" (без
html!). Если система не получит "OK", Idram не позволит покупателю уплатить
счет, т.е. деньги перечислены не будут, и система перенаправит покупателя на URL
FAIL_URL.
EDP_AMOUNT
(б)Подтверждения факта оплаты
Этот http запрос передает продавцу реквизиты выполненного платежа в момент его
совершения. Она имеет следующие поля:
В этом поле передается номер покупки в
соответствии с системой учета продавца,
EDP_BILL_NO
полученный сервисом с веб-сайта продавца.
IdramID продавца(в системе Idram), на
EDP_REC_ACCOUNT
который покупатель совершил платеж
IdramID покупателя(в системе Idram), с
EDP_PAYER_ACCOUNT
которого был произведен платеж
EDP_AMOUNT
Сумма, которую заплатил покупатель.
Дробная часть отделяется точкой.
(format-0.00)
Номер операции выполненого платежа в
EDP_TRANS_ID
системе Idram. Является уникальным в
системе Idram.
format - char(14)
EDP_TRANS_DATE
Дата операции выполненого платежа.
format -dd/mm/yyyy
Контрольная подпись оповещения о
выполнении платежа, которая используется
для проверки целостности полученной
EDP_CHECKSUM
информации и однозначной идентификации
отправителя.(подробное описание см. ниже)
EDP_CHECKSUM : Контрольная подпись данных о платеже позволяет продавцу проверять
как источник данных, так и целостность данных, переданных на RESULT_URL через запрос
"Подтверждения факта оплаты".
При формировании контрольной подписи сервис Idram Merchant Interface "склеивает"
значения следующих полей :







EDP_REC_ACCOUNT
EDP_AMOUNT
SECRET_KEY
EDP_BILL_NO
EDP_PAYER_ACCOUNT
EDP_TRANS_ID
EDP_TRANS_DATE
В качестве разделителя берется знак двоеточия(":").
Далее берется md5 от сформировавшейся строки, и полученное значение приписывается
параметру EDP_CHECKSUM. Магазин должен произвести те же действия для того чтобы
проверить источник и целостность данных.
Ниже приводиться пример php скрипта, который обеспечивает работу RESULT_URL:
<?php
define("SECRET_KEY", "FakeKey"); // Idram Payment System provide it
define("EDP_REC_ACCOUNT", "FakeID");
// Idram Payment System provide it
if(isset($_REQUEST['EDP_PRECHECK']) && isset($_REQUEST['EDP_BILL_NO']) &&
isset($_REQUEST['EDP_REC_ACCOUNT']) && isset($_REQUEST['EDP_AMOUNT']))
{
if($_REQUEST['EDP_PRECHECK'] == "YES")
{
if($_REQUEST['EDP_REC_ACCOUNT'] == EDP_REC_ACCOUNT)
{
$bill_no = $_REQUEST['EDP_BILL_NO'];
// check if $bill_no exists in your system orders if
exists then echo OK otherwise nothing
echo("OK");
}
}
}
if(isset($_REQUEST['EDP_PAYER_ACCOUNT']) && isset($_REQUEST['EDP_BILL_NO']) &&
isset($_REQUEST['EDP_REC_ACCOUNT']) && isset($_REQUEST['EDP_AMOUNT'])
&& isset($_REQUEST['EDP_TRANS_ID']) && isset($_REQUEST['EDP_CHECKSUM']))
{
$txtToHash =
EDP_REC_ACCOUNT . ":" .
$_REQUEST['EDP_AMOUNT'] . ":" .
SECRET_KEY . ":" .
$_REQUEST['EDP_BILL_NO'] . ":" .
$_REQUEST['EDP_PAYER_ACCOUNT'] . ":" .
$_REQUEST['EDP_TRANS_ID'] . ":" .
$_REQUEST['EDP_TRANS_DATE'];
if(strtoupper($_REQUEST['EDP_CHECKSUM']) != strtoupper(md5($txtToHash)))
{
// code to handling payment fail
}
else
{
// code to handling payment success
echo("OK");
}
}