4. Подпись данных.
.
.
Подпись данных торговой системой применяется для защиты данных транзакции при передаче их к защищённо странице платёжного шлюза и обратно. Это дает возможность обнаружить любые изменения данных, если они были произведены преднамеренно, и таким образом, защититься от постороннего вмешательства. Платежный шлюз всегда проверяет данные, принимаемые от торговой системы, на предмет целостности, путём проверки подписи(MAC-кода) торговой системы. Для этой операции администратор торговой системы должен сформировать значение этого MAC-кода на своей стороне и прислать его, как значение параметра «Signature». Подпись формируется путем выполнения криптографической операции с набором данных и секретным(pub)/приватным(pem) ключом.
.
Для начала работы необходимо скачать Win32 OpenSSL(оф.сайт https://www.openssl.org/source/)
.
После установки:
.
1. необходимо прописать в переменную Path путь к каталогу bin
2. правой кнопкой "Мой компьютер", "Свойства", "Дополнительно", "Переменные среды"
3. В системных переменных: PATH "Изменить" поставить в конце строки точку с запятой и прописать путь к папке bin: c:\OpenSSL\bin
.
.
Генерация ключей и сертификата (*.crt)
Генерация и обмен ключами осуществляется после подачи заявки на регистрацию и получения атрибутов торговой системы (MerchantID, TerminalID). Перед генерацией ключей необходимо отредактировать файл config.dat в соответствии с данными подключаемой торговой системы:
.
#Страна
CN=UA
#Область
ST=Kievskaya
#Город
L=Kiev
#Название организации
O=UPC
#Название отделения
OU=IT DEP
#Имя для сертификата (Ваше имя)
CN=SERG
#Email организации
emailAddress=ec@upc.ua
.
.
Данные в config.dat не должны строго соответствовать данным в заявке на подключение, они не участвуют в генерации или проверке подписи, и используются только для идентификации файла сертификата (*.crt), который необходимо отправить в технический отдел UPC, для проверки платёжным шлюзом аутентичности сообщения от торговой системы.
.
Приступая к непосредственной генерации сертификата (*.crt), приватного(*.pem) и публичного(*.pub) ключей в программе Win32 OpenSSL прописываем команду run.bat с присвоенным торговой системе параметром MerchantID (например,1775555):
run.bat 1770000
Запускаем команду, после чего генерируется три файла:
1770000.crt – сертификат
1770000.pem – приватный ключ
1770000.pub – публичный ключ
Полученный сертификат (*.crt) администратор торговой системы обязательно должен отправить в технический отдел UPC (ec@upc.ua), для проверки платёжным шлюзом аутентичности сообщения, а ключи оставить на стороне торговой системы и использовать для генерации подписи.
Генерация подписи
Подпись генерируется на основании двух файлов:
- (*.pem) – приватный ключ, сгенерированный на стороне торговой системы.
- datafile – предоставленный техническим отделом UPC.
datafile содержит определённые данные(поля), для которых непосредственно формируется подпись. Важно соблюдать последовательность полей, иначе запрос будет отклонен с ошибкой 405 (Signature is invalid). Поля записываются в datafile в представленном ниже порядке:
MerchantId;TerminalId;PurchaseTime;OrderId,Delay;CurrencyId,AltCurrencyId;Amount,AltAmount;SessionData(SD);
Количество знаков ; должно оставаться постоянным. Если какое-то поле отсутствует, то ставится два знака ;;.
Примеры:
Если отсутствует SessionData(SD), то datafile будет выглядеть следующим образом:
MerchantId;TerminalId;PurchaseTime;OrderId,Delay;CurrencyId,AltCurrencyId; Amount,AltAmount;;
Если отсутствуют поля Delay или AltCurrency, AltAmount, то запятая перед этими полями опускается:
MerchantId;TerminalId;PurchaseTime;OrderId ;CurrencyId,AltCurrencyId;Amount, AltAmount;;
MerchantId;TerminalId;PurchaseTime;OrderId,Delay;CurrencyId ;Amount;;
MerchantId;TerminalId;PurchaseTime;OrderId;CurrencyId;Amount ;;
Если в запросе на шлюз присутствует поле Ref3, то оно должно участвовать в формировании подписи:
MerchantId;TerminalId;PurchaseTime;OrderId;CurrencyId;Amount;SessionData(SD);Ref3;
Для правильной генерации подписи, обязательно нужно проверить datafile в редакторе (HEX, FAR, Notepad), он не должен содержал никаких лишних символов (пробелы, символы перевода каретки и возврата в начало строки). Также, в запросе нельзя писать название полей в нижнем регистре(то есть, поле с именем merchantid таковым не является).
Для генерации подписи необходимо запустить create_signature.bat с параметром *.pem. Например, create_signature.bat 1770000.pem.
В результате будут обновлены или созданы два файла: signature.bin (подпись) и signature (подпись в кодировке base64). Данные в файле signature отправляются в запросе как подпись.
.
.
Проверка подписи от шлюза
.
.
Для проверки подписи данных со шлюза необходимо в файл from_gateway записать поля в следующем порядке:
MerchantId;TerminalId;PurchaseTime;OrderId,Delay;Xid;CurrencyId,AltCurrencyId;Amount,AltAmount;SessionData;TranCode;ApprovalCode;
Для проверки подписи со шлюза ее необходимо поместить в файл signature. Все требования с предыдущего пункта, касательно формирования from_gateway здесь так же обязательны. Очень важно, чтобы количество значащих символов в одной строке файла signature не превышало 64 (длина строки).
Для проверки подписи выполнить check_signature.bat
openssl base64 -d -in signature -out signature.bin
openssl dgst -sha1 -verify test-server.pub - signature signature.bin from_gateway
Запрос на возврат/реверсал
Если выполняется запрос на возврат/реверсал, то данные должны быть дополнены следующими полями: ApprovalCode, RRN.
В случае, если запрос содержит поля RefundAmount и/или Ref3, то эти поля также должны участвовать в подписи.
Пример:
Рассмотрим datafile, c использованием всех возможных полей:
MerchantId;TerminalId;PurchaseTime;OrderId;CurrencyId;Amount;SessionData(SD);ApprovalCode;RRN;RefundAmount;Ref3;
Если отсутствует опциональное(необязательное) поле, например - RefundAmount или Ref3, то такое поле просто опускается:
MerchantId;TerminalId;PurchaseTime;OrderId;CurrencyId;Amount;SessionData(SD);ApprovalCode;RRN;Ref3;
MerchantId;TerminalId;PurchaseTime;OrderId;CurrencyId;Amount;SessionData(SD);ApprovalCode;RRN;RefundAmount;
MerchantId;TerminalId;PurchaseTime;OrderId;CurrencyId;Amount;SessionData(SD);ApprovalCode;RRN;
.
.
Примеры формирования запроса на шлюз
.
Пример на HTML :
Формирование запроса на шлюз с подготовленными данными:
<html>
<head>
<title> </title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head> <body onload="submit()"> <form action="https://secure.upc.ua/go/pay" method="POST">
<input name="Version" type="hidden" value="1" /> <input name="MerchantID" type="hidden" value="6290886" />
<input name="TerminalID" type="hidden" value="E0137498" />
<input name="TotalAmount" type="hidden" value="10000" />
<input name="Currency" type="hidden" value="980" />
<input name="locale" type="hidden" value="ru" /> <INPUT TYPE="HIDDEN" NAME="PurchaseTime" VALUE="130619150000"/>
<input id="order" name="OrderID" type="hidden"/> <input name="PurchaseDesc" type="hidden" value="Оплата @заказа" />
<input name="Signature" type="hidden" value=""/>
<button id="submit">go</button> </form>
</body>
</html>
<script type="text/javascript">
document.getElementById('order').value = Math.floor(Math.random() * 10000);
function submit()
{
document.getElementById("submit").click(); // Simulates button click
//document.submitForm.submit(); // Submits the form without the button
}
</script>
.
.
Проверка ответа шлюзом:
.
<html>
<head>
<title>Введите информацию платежной карточки</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta http-equiv="pragma" content="no-cache">
<meta http-equiv="Cache-Control" content="no-cache">
<meta http-equiv="Expiration" content="0">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link rel="stylesheet" href="/go/style/def/style.css?v=2.7.7" type="text/css">
<style nonce="4ead891ad314226c5fb68cd64d79e11b025c4bf5" id="antiClickjack">body{display:none;}</style>
<script nonce="4ead891ad314226c5fb68cd64d79e11b025c4bf5">
if (self === top) {
var antiClickjack = document.getElementById("antiClickjack");
antiClickjack.parentNode.removeChild(antiClickjack);
} else {
top.location = self.location;
}
</script>
</head>
Пример на PHP :
Формирование запроса на шлюз с подготовленными данными:
<?php
$OrderID = 12;
$PurchaseTime = date("ymdHis") ;
#строка для подписи
$data = "1752429;E7880229;$PurchaseTime;$OrderID;980;1200;;";
$fp = fopen("1752429.pem", "r");
$priv_key = fread($fp, 8192);
fclose($fp);
$pkeyid = openssl_get_privatekey($priv_key);
openssl_sign( $data , $signature, $pkeyid);
openssl_free_key($pkeyid);
#Подпись данных в формате base64
$b64sign = base64_encode($signature);
?>
<form action="https://ecg.test.upc.ua/go/enter" method="post" > - URL тестового сервера
<input name="Version" type="hidden" value="1" />
<input name="MerchantID" type="hidden" value="1234567" /><!--Тестовый Merchant Id
<input name="TerminalID" type="hidden" value="E1234567" /><!--
Тестовый Terminal ID <input name="TotalAmount" type="hidden" value="1200" />
<input name="Currency" type="hidden" value="980" />
<input name="locale" type="hidden" value="RU" />
<INPUT TYPE="HIDDEN" NAME="PurchaseTime" VALUE="<?php echo $PurchaseTime ?>">
<input name="OrderID" type="hidden" value="12" />
<input name="Signature" type="hidden" value="<?php echo "$b64sign" ?>"/>
-Подпись которую сервер проверит Вашим публичным ключом<input type="submit" />
</form>
<a href="index112.php">SUBMIT</a>
</body>
</html>
Проверка ответа ключом шлюза:
<?php
// $data содержит значение полей для проверки подписи
$signature = $HTTP_POST_VARS["Signature"];
$signature = base64_decode($signature) ;
// извлечь сертификат
$fp = fopen("/opt/deploy/certs/server.crt", "r");
$cert = fread($fp, 8192); fclose($fp);
$pubkeyid = openssl_get_publickey($cert);
// проверка подписи
$ok = openssl_verify($data, $signature, $pubkeyid); if ($ok == 1) { echo "good"; } elseif ($ok == 0) { echo "bad"; } else {
echo "ugly, error checking signature";
}
// free the key from memory openssl_free_key($pubkeyid); ?>
.
.
Пример на openssl :
.
Подпись запроса приватным ключом торговца
Файл datafile содержит данные для подписи, например:
6352045;ECI62791;031227105500;HV-923452;;980;12550;;
Команда cat datafile | openssl dgst -sha1 -sign 1751852.pem
либо openssl dgst -sha1 -sign 1751852.pem datafile
сгенерирует подпись в бинарном виде.
Для получения в BASE64 нужно віполнить дополнительные команды для обработки потока, например :
[root@ecgtest test]# cat datafile | openssl dgst -sha1 -sign 1751852.pem | uuencode -m AAA | tail 4 | head -3
U8jjhDRYamOxeIpGqvCH3IIItTFfSyegAfQcqdwLhzyKHevpsxMV3l1RTwYw
0V7X5HK7+lMaC08JE8AEogPkbNS/JiZu1yCL47jOgJUrfUjbu9Gbob/FiiB9
8M4RI3LHOUOoeFl1uxXkEsi9fAfdtUN+mXRDI8muKT+Xu2JP6wk=
[root@ecgtest test]#
Проверка ответа публичным ключом шлюза:
Для начала нужно извлечь из сертификата шлюза его публичный ключ, например :
[root@ecgtest test]# openssl x509 -in gateway.crt -noout –pubkey | tee gateway.pub
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC73xJq+BISfysLKT0Pc872Agm
irgNYWUYSnQd3gihhtF3ZrBmESqpoxebTGZX0iVXS4Ulb0NAGAIge6XpoIp6GQ3X4rtFw
CZTwFOSPtXhKA3dZBECI4UuoTY/Wvr4FXSzgOMF0Izubd4uPbE2O3gOFXha pYoNKC8
V+hN+rFDfmQIDAQAB
-----END PUBLIC KEY-----
Поместить значение подписи в файл signature, а значение данных для подписи – в файл datafile .
Выполнить команду проверки подписи :
[root@ecgtest test]# openssl dgst -sha1 -verify gateway.pub -signature signature datafile Verified OK
.
.
6. Ввод терминала в эксплуатацию
.
После завершения тестирования сотрудник EC UPC регистрирует торговую систему на рабочем шлюзе и отправляет зарегестрированные рабочие данные администратору данной торговой системы
Пример сообщения:
Порядок работы с рабочими данными:
.
1. Инсталляция сертификата work-server.cert
.
Для проверки сообщений от платёжного шлюза UPC необходимо разместить полученный во вложении файл work-server.cert в доступную директорию для скрипта рабочего кода (аналогично test-server.crt).
.
2. Инсталляция сертификата *.p12
.
Сертификат *.p12 используется для защищенного входа в интерфейс торговой системы. Его необходимо импортировать в браузер для получения доступа, используя полученный в сообщении пароль. Пример по загрузке сертификата в браузер можно найти, используя поисковые системы.
.
Google Chrome: http://infrastructure.kiev.ua/training/68/
Mozilla Firefox: http://infrastructure.kiev.ua/training/70/
.
3. Изменение настроек терминала.
.
Ссылка для перехода в интерфейс торговой системы (работает только при установленном сертификате *.p12): https://secure.upc.ua/go/merchant
.
Перед началом работы, в интерфейсе личного кабинета торговой системы, используя логин и пароль полученный в письме с рабочими данными, нужно изменить пароль для входа в кабинет. Далее, необходимо указать адрес страницы NOTIFY_URL для передачи результатов транзакций, а также, - адрес страницы для переадресации картхолдера в случае успешной SUCCESS_URL или неуспешной FAILURE_URL транзакции.
Сделать это нужно в разделе «Терминалы»:
.
.
Откроется окно «Параметры терминала»:
.
.
4. Генерация ключей и сертификата (*.crt)
.
Перед генерацией ключей необходимо отредактировать файл config.dat в соответствии с данными подключаемой торговой системы:
.
#Страна
CN=UA
#Область
ST=Kievskaya
#Город
L=Kiev
#Название организации
O=UPC
#Название отделения
OU=IT DEP
#Имя для сертификата (Ваше имя)
CN=SERG
#Email организации
emailAddress=ec@upc.ua
.
Заменив данные в config.dat на присвоенные торговой системе рабочие, можно приступая к генерации рабочих файлов - сертификата (*.crt), приватного(*.pem) и публичного(*.pub) ключей в программе Win32 OpenSSL прописываем команду run.bat с присвоенным торговой системе параметром MerchantID (например,1775555):
run.bat 1770000
.
Запускаем команду, после чего генерируется три файла:
.
1770000.crt – сертификат
1770000.pem – приватный ключ
1770000.pub – публичный ключ
.
После генерации файлов, полученный сертификат (*.crt) администратор торговой системы обязательно должен отправить в технический отдел UPC (ec@upc.ua), для проверки платёжным шлюзом аутентичности сообщения, а ключи оставить на стороне торговой системы и использовать для генерации подписи.
.
5. Первая рабочая транзакция.
.
После успешного выполнения выше указанных инструкций, можно провести тестовую транзакцию на небольшую сумму с использованием реальной карты(сумма всегда указывается в копейках 1 гривна=100). Для этого необходимо изменить настройки системы оплаты сайта торговой системы:
.
- Заменить ранее полученный тестовый MerchantID на рабочий;
- Заменить ранее полученный тестовый TerminalID на рабочий;
- Изменить адрес шлюза с тестового на рабочий: https://secure.upc.ua/go/pay
.
.
7. Просмотр и возврат транзакций в интерфейсе торговца.
.
Статус транзакции можно проверить в личном кабинете торговой системы https://secure.upc.ua/go/merchant, в разделе «Транзакции», используя необходимые параметры поиска, можно найти нужную транзакцию. Поиск возможно осуществлять по всем доступным параметрам в форме поиска.
.
К примеру, используя поиск по номеру карты, можно вносить следующие данные:
.
1. 123456* - поиск по первым 6 цифрам карты клиента;
2. 123456*7890 – поиск по первым 6 и последним 4 цифрам карты клиента;
3. *7890 – поиск по последним 4 цифрам карты плательщика.
.
При этом необходимо использовать символ, * как это указано выше в примерах. Максимальный размер символом данного поля – 9.
.
.
.
Также, можно использовать поиск в определенный промежуток времени и по статусу транзакции, как показано в примере выше - поиск будет осуществлен по всем успешным транзакциям за 10.02.2017 в период с 10:00 по 10:30.
.
Если есть необходимость, осуществить возврат средств по транзакции картхолдеру, то нужно найти и выбрать оригинальную транзакцию→ в появившемся поле внизу формы ввести сумму возврата → нажать кнопку «отправить». (Сумму возврата необходимо вводить в копейках: 100 = 1грн):
.
.
.
.
8. Коды возврата результатов транзакции
.
Коды возврата результата транзакции делятся на несколько классов и подклассов и служат для информирования торговой системы о результате ее проведения. Для индикации успешного завершения транзакции достаточно одного кода. Большая же часть кодов служит для предоставления торговой системе обобщенной информации о причине неудачного завершения транзакции. Ниже представлены коды ответов на основе авторизационного хоста банка(таб.4) и коды ответов, генерируемых платёжным сервером без обращения к хосту банка(табл.5):
.
табл.2
| Коды ответа |
Примерная интерпретация ответа |
Коды ответов в сообщении от обслуживающего банка |
| 000 |
Сделка авторизована |
00x |
| 105 |
Транзакция не разрешена банком-эмитентом |
100,103,104,105…107 |
| 116 |
Недостаточно средств |
116 |
| 111 |
Несуществующая карта |
111,125,200,202 |
| 108 |
Карта утеряна или украдена |
208,209 |
| 101 |
Неверный срок действия карты |
101,201 |
| 130 |
Превышен допустимый лимит расходов |
121,123 |
| 290 |
Банк-издатель недоступен |
905…908,910 |
| 291 |
Техническая или коммуникационная проблема |
9xx (кроме указанных выше) |
.
табл.3
| Внутренние коды ошибок платежного сервера |
Примерная интерпретация ответа |
| 401 |
Ошибки формата |
| 402 |
Ошибки в параметрах Acquirer/Merchant |
| 403 |
Ошибки при соединении с ресурсом платежной системы (DS) |
| 404 |
Ошибка аутентификации покупателя |
| 405 |
Ошибка подписи |
| 406 |
Превышена квота разрешенных транзакций |
| 407 |
Торговец отключен от шлюза |
| 408 |
Транзакция не найдена |
| 409 |
Несколько транзакций найдено |
| 410 |
Заказ уже был успешно оплачен В случае повтора |
| 411 |
Некорректное время в запросе |
| 412 |
Параметры заказа уже были получены ранее В случае повтора |
| 420 |
Превышен лимит дневной лимит транзакций |
| 421 |
Превышена максимально разрешенная сумма транзакции |
| 430 |
Транзакция запрещена на уровне платежного шлюза |
| 431 |
Не разрешена транзакция без полной аутентификации по схеме 3DSecure
(карта не зарегистрирована для 3DSecure операций) |
| 454 |
Шлюзом запрещено использование Ref3 |
| 455 |
Шлюзом запрещен запрос на возврат средств |
| 501 |
Транзакция отменена пользователем |
| 502 |
Сессия браузера устарела |
| 503 |
Транзакция отменена магазином |
| 504 |
Транзакция отменена шлюзом |
| 601 |
Транзакция не завершена |
.
.
9. Запрос состояния транзакции со стороны торговца
.
Для получения статуса оплаты торговой системе необходимо использовать схему с применением NOTIFY_URL. В данном случае платёжный шлюз доставляет результат обработки транзакции напрямую торговой системе, не надеясь на передачу параметров через браузер пользователя. Дополнительно, торговая система со своей стороны может послать запрос о состоянии транзакции на шлюз. Это может быть сделано передачей запроса POST на страницу шлюза со следующими параметрами:
.
MerchantID=
TerminalID=
OrderID=
Currency=
TotalAmount=
PurchaseTime=
.
Шлюз возвращает текстовую страницу с дополнительными параметрами
.
XID=
TranCode=
ApprovalCode=
.
Транзакция считается успешной, если значение поля TranCode = «000».
.
Пример:
.
<html>
<body>
<form method='POST' action="https://ecg.test.upc.ua/go/service/01">
<input type='hidden' name='MerchantID' value='6352045'>
<input type='hidden' name='TerminalID' value='ECI62791'>
<input type='hidden' name='OrderID' value='VHS-23684'>
<input type='hidden' name='Currency' value='980'>
<input type='hidden' name='TotalAmount' value='12550'>
<input type='hidden' name='PurchaseTime' value='031227105500'>
<input type='submit' value='go'>
</form>
</body>
<html>
.
.
10. Запрос возврата/отката транзакции со стороны торговой системы
(Функцию возврата можно активировать отправив соответствующий запрос на ec@upc.ua)
.
Запрос возврата/реверсала возможно осуществить только на операцию авторизации. Для выполнения возврата торговая система со своей стороны должна отправить запрос на защищённую страницу шлюза. Это может быть сделано передачей POST запроса, который содержит параметры, приведенные в таблице ниже(табл.6):
| Параметр |
Назначение |
Описание |
Формат |
| MerchantID |
Идентификатор торговца |
Назначается обслуживающим банком |
an15 |
| TerminalID |
Идентификатор терминала |
Назначается обслуживающим банком |
an8 |
| TotalAmount |
Сумма заказа |
Всегда указывается в мелких единицах валюты (копейки, центы) |
N1..12 |
| Currency |
Валюта |
Определяется договором с обслуживающим банком-эквайером |
n3 |
|
PurchaseTime
|
Время запроса в формате: yyMMddHHmmss
|
- MM- месяц (month in year)
|
n12..17
|
| OrderID |
Номер заказа |
Идентификатор заказа (до 20 байт) |
Ans…20 |
| Rrn |
Retrieval Reference Number |
Уникальный номер транзакции в системе авторизации и расчетов обслуживающего банка |
N12 |
| SD (опционально) |
Session Data -данные сессии клиента, которые передаёт торговая система |
Вспомогательный параметр, может быть использован системой для управления пользовательскими сессиями |
an...99 |
| Signature |
Электронно-цифровая подпись данных, участвующих в генерации запроса |
Длина параметра зависит от выбранной схемы вычисления |
Зависит от схемы |
| ApprovalCode |
Код авторизации хоста |
Код подтверждения операции, полученный от банка |
An6 |
| Ref3 (Oпционально) |
Передача доп параметра в n-файл, а потом в b-файл |
При помощи данного параметра можно передавать поле, содержащее не карточную информацию. |
ans..1 150 |
.
Шлюз формирует ответ в виде текстовой страницы, содержащей параметры(табл.7):
.
| Параметр |
Назначение |
Описание |
Формат |
| MerchantID |
Идентификатор торговца |
Назначается обслуживающим банком |
an15 |
| TerminalID |
Идентификатор терминала |
Назначается обслуживающим банком |
an8 |
| TotalAmount |
Сумма заказа |
Всегда указывается в мелких единицах валюты (копейки, центы) |
N1..12 |
| TranCode |
Код завершения транзакции |
Представлено в таб. 4 |
N3 |
| CardType |
VISA – Visa
MAST – MasterCard
MAES – Maestro |
Принадлежность карты к платёжной системе |
an4 |
| ERROR (опционально) |
содержит краткую информацию об ошибке |
опционально и формируется только при возникновении ошибки в процессе обработки запроса |
ans |
.
Возврат/реверсал считается успешным, если значение поля TranCode=000.
.
Пример:
.
<html>
<body>
<form method='POST' action="https://ecg.test.upc.ua/go/repayment">
<input type='hidden' name='MerchantID' value='1752493' />
<input type='hidden' name='TerminalID' value=' E7880293' />
<input type='hidden' name='OrderID' value='PAY160601124534' />
<input type='hidden' name='Currency' value='980' />
<input type='hidden' name='TotalAmount' value='12550' />
<input type='hidden' name='PurchaseTime' value='160601124534' />
<input type='hidden' name='ApprovalCode' value='123456' />
<input type='hidden' name='RRN' value='2222222222' />
<input type='hidden' name='RefundAmount' value='12000' />
<input type='hidden' name='Signature' value='45F345Fafde4455445Gvb550' />
<input type='submit' value='go'>
</form>
</body>
<html>
.
.
11. Сервис Токенизации
.
Сервис предназначен для предоставления торговым системам услуги по созданию цифрового аналога платежной карты (токен) на стороне Процессингового Центра, что позволяеи Non-PCIDSS мерчантам хранить цифровой аналог платежной карты (токен) и инициировать транзакции с использованием токена. Для активации Сервиса Токенизации администратору торговой системы необходимо отправить запрос на электронную почту ec@upc.ua с указанием Merchant_id, предварительно уведомив о данном запросе обслуживающий банк-эквайер, который должен присылает лимит с пороговыми суммами(относительно валют, используемых банком), свыше которых, запрос должен будет содержать CVC (карты, по которой был сформирован токен). Также, банк-эквайер имеет возможность устанавливать индивидуальные лимиты с пороговыми сумами для торговых систем. После активации сервиса, шлюз будет формировать ответ на транзакцию с параметрами представлены ниже:
Первоначальный платеж
.
Дальнейшие платежи продавец может инициировать с помощью токена. Оплата токеном - это списание средств с платежной карты без повторного ввода реквизитов карты.
.
Чтобы активировать сервис токенизации, продавец должен отправить запрос на ec@upc.ua и указать Merchant_id. Продавец также должен уведомить банк-эквайрер о таком запросе.
Банк-эквайрер отправляет лимит с пороговыми суммами (в отношении валют, используемых банком), в случае превышения лимита запрос должен содержать CVC (карты, для которой был создан токен). Банк-эквайрер может устанавливать индивидуальные лимиты с пороговыми суммами для продавцов.
Когда опция активирована, шлюз создает ответ на транзакцию с параметрами, указанными в Табл. 7.
Табл.7
| Параметр |
Назначение |
Описание |
Формат |
| MerchantID |
Идентификатор торговца |
Назначается банком |
an15 |
| TerminalID |
Идентификатор терминала |
Назначается банком |
an8 |
| TotalAmount |
Сумма заказа |
Указывается в мелких единицах валюты |
N1..12 |
| Currency |
Валюта |
Определяется договором с обслуживающим банком-эквайером |
n3 |
| AltTotalAmount (опционально) |
Сумма заказа (альтернативная валюта) |
Необязательный параметр.
Указывается в мелких единицах валюты
(копейки, центы) |
N1..12 |
| AltCurrency (опционально) |
Альтернативная Валюта |
Используется торговой системой при необходимости отобразить сумму платежа в другой валюте(например €, $). |
n3 |
| PurchaseTime |
Время запроса |
yyMMddHHmmss |
n12..17 |
| OrderID |
Номер заказа |
Идентификатор заказа (до 20 байт) |
Ans…20 |
| XID |
Идентификатор транзакции |
Совпадает с переданными данными |
ans28 |
| SD (опционально) |
Данные сессии клиента |
Совпадает с переданными данными |
an... 99 |
| ApprovalCode |
Код авторизации хоста |
Код подтверждения операции, полученный от банка |
An6 |
| Rrn |
Retrieval Reference Number |
Уникальный номер транзакции в системе авторизации и расчетов обслуживающего банка |
N12 |
| ProxyPan |
4 последние цифры номера карты |
Значение PAN ( 4 последние цифры ) с дополненными нулями впереди для индикации длины PAN. Пример: 499999******0011 |
N13…19 |
| Signature |
Электронно-цифровая подпись данных |
Длина параметра зависит от выбранной схемы вычисления |
An…40 |
| TranCode |
Код завершения транзакции |
Представлено в табл. 4 |
N3 |
| Delay |
Идентификатор платежа Преавторизация |
Используется для преавторизации, при значение равном 1=включено, при 0(пусто)=выключено |
N1 |
| UPCToken |
Карта/срок действия карты/Merchant_id |
Цифровой идентификатор платежной карты |
An…32 |
| UPCTokenExp |
Срок действия токена |
формат (MMYYYY) |
An…32 |
.
Результаты обработки передаются методом HTTP/HTTPS POST со стороны шлюза на страницу магазина.
.
Notify request message:
PurchaseTime = '090929152500'
ProxyPan = '499999*******0011'
Currency = '980'
ApprovalCode = '111111'
MerchantID = '1752493'
OrderID = '111111111111111111'
Signature = test'
Rrn = '2222222222'
XID = '333333-4444444'
Email = j.timoshenko@upc.ua'
SD = '24ee6084a5343e3d'
UPCToken = '254484kC162EEC13E5B012736288683AC'
TranCode = '000'
TerminalID = 'E7880293'
TotalAmount = '500'
.
Далее торговец может использовать полученный токен для проведения транзакции. Запрос для проведения транзакции должен быть в формате JSON Web Signature(Стандарт JWS (rfc7515. See https://tools.ietf.org/html/rfc7515#page-10 )). Все данные необходимо передавать в BASE64URL кодировке.
.
.
12. Платежи в рассрочку (Installment Payments)
.
Функционал позволяет клиентам - держателям платежных карточек осуществлять оплату покупок на условиях рассрочки платежа, выбирая условия с тех вариантов, которые для данного клиента предоставлены банком-эмитентом. Для активации Сервиса Installment Payments торговцу необходимо отправить запрос на ec@upc.ua с указанием Merchant_id, а также уведомить банк-эквайер, который должен установисть пороговую сумму (в валюте транзакций), при превышении которой в авторизационном запросе будет уходить флаг проверки installment для банка-эмитента.
.
После подтверждения активации опции Installment Payments со стороны UPC, администратор торговой системы устанавливает параметр «да» через Merchant interface в поле «отправка условий рассрочки с помощью Notify»
.
.
В этом случае результаты обработки транзакции и план рассрочки передаются методом HTTP/HTTPS POST со стороны шлюза на страницу торговой системы:
.
Notify request message:Installment = '{"type":21,"paymentOption":"B","options":[{"number":2,"interestRate":12345,"fee":127777777777,"annualPercentageRate":55555,"firstAmount":123333333333,"subsequentAmount":121212121212,"totalAmountDue":252525252525},{"number":22,"interestRate":12345,"fee":123451242222,"annualPercentageRate":78787,"firstAmount":636363663633,"subsequentAmount":787878787777,"totalAmountDue":787878787877},{"number":77,"interestRate":78787,"fee":787878787777,"annualPercentageRate":45455,"firstAmount":454555555555,"subsequentAmount":496969696699,"totalAmountDue":898989898989},{"number":88,"interestRate":44444,"fee":111111111111,"annualPercentageRate":12122,"firstAmount":777777777777,"subsequentAmount":888888888888,"totalAmountDue":666666666666},{"number":55,"interestRate":88888,"fee":757585858555,"annualPercentageRate":33333,"firstAmount":636363333333,"subsequentAmount":111111111111,"totalAmountDue":363636363636},{"number":85,"interestRate":47474,"fee":858585888888,"annualPercentageRate":66666,"firstAmount":889898989999,"subsequentAmount":858585858588,"totalAmountDue":969696969696},{"number":25,"interestRate":25252,"fee":858585858588,"annualPercentageRate":36636,"firstAmount":636363633365,"subsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":22,"interestRate":55555,"fee":123333333333,"annualPercentageRate":43434,"firstAmount":123333333333,"subsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":22,"interestRate":12355,"fee":123333333333,"annualPercentageRate":12333,"firstAmount":123333333333,"subsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":11,"interestRate":12335,"fee":123333333333,"annualPercentageRate":12333,"firstAmount":123333333333,"subsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":44,"interestRate":33333,"fee":123333333333,"annualPercentageRate":12333,"firstAmount":123333333333,"subsequentAmount":123333333333,"totalAmountDue":123333333333},{"number":22,"interestRate":33333,"fee":123333333333,"annualPercentageRate":12333,"firstAmount":123333333333,"subsequentAmount":123333333333,"totalAmountDue":123333333333}],
"receipt":"666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666
66666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666
66666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666666
6666666666666666666666666666666666666666666666666666666666666666"}'
.
Email = 'julia.timoshenko@upc.ua'
TranCode = '602'
MerchantID = '1754971'
TotalAmount = '15000'
OrderID = '844477'
ApprovalCode = '423488'
ProxyPan = '555949******0023'
Delay = '0'
Rrn = '825415352694'
PurchaseTime = '180907113626'
SD = ''
XID = '18091115-278639'
Currency = '980'
Signature = 'null'
TerminalID = 'E7882971'
.
После чего, торговая система возвращает ответ в теле выполняемой страницы (вывод ответа на страницу NOTIFY_URL, как текст). Параметр=Значение возвращаются в новой строке и должны быть разделены символом разделителя строк(\n). В данном ответе шлюзу, торговая система должна вернуть 3 дополнительных параметра (помимо стандартных: MerchantID, TerminalID, OrderID, Currency, TotalAmount, XID, PurchaseTime):
.
.
| Параметр |
Значение |
Описание |
| Response.action |
approve / reverse |
При значении approve – торговая система дает одобрение для успешности операции.
При значении reverse - шлюз делает откат успешной транзакции и устанавливает признак завершения 503 – «Транзакция отменена магазином» |
| Response.reason (опционально) |
An.. 255 |
Пояснение ответа магазина (опционально),
например – причина для значения Response.action |
| Response.forwardUrl |
An.. 255 |
Значение URL для редиректа браузера пользователя, вместо SUCCESS_URL или FAILURE_URL (предоставляет возможность использовать динамические ссылки) |
.
Пример:
.
echo "MerchantID="1752493"\n"; echo "TerminalID="E7880293"\n"; echo "OrderID="ID0009992"\n"; echo "Currency="980"\n";
echo "TotalAmount="980"\n";
echo "XID="333333-4444444"\n";
echo "PurchaseTime="090929152500"\n";
echo "Response.action="\n";
echo "Response.reason="\n";
echo "Response.forwardUrl="\n";
.
