Интерфейс взаимодействия

створив(ла) admin — Востаннє змінено: Бер 30, 2020 14:37

Содержание

1. Общие положения ............................................................................................................................3
2. Передача параметров авторизационного запроса серверу платёжного шлюза ....................................5
3. Возврат результатов обработки. NOTIFY_URL ................................................................................... 8
4. Подпись данных ..............................................................................................................................12
Генерация ключей и сертификата (*.crt) .................................................................................................12
Генерация подписи ...............................................................................................................................13
Проверка подписи ............................................................................................................................... 14
Запрос на возврат/реверсал ................................................................................................................ 15
Примеры формирования запроса ......................................................................................................... 16
5. Pre/Authorization транзакции ............................................................................................................. 19
6. Ввод терминала в эксплуатацию ...................................................................................................... 20
7. Просмотр и возврат транзакций ........................................................................................................ 23
8. Коды возврата результатов транзакций ............................................................................................. 24
9. Запрос состояния транзакции ........................................................................................................... 25
10. Запрос возврата ............................................................................................................................. 27
11. Сервис Токенизации ........................................................................................................................ 29
12. Платежи в рассрочку ...................................................................................................................... 31

1. Общие положения.

Взаимодействие торговой системы с платежным шлюзом на этапе проверки платежеспособности карты осуществляется на завершающем этапе – ‘checkout’ процесса. Этот этап, как правило, характерен тем, что плательщик уже определился с набором приобретаемых товаров или услуг, их стоимостью, условиями доставки и т.д., и готов произвести оплату с использованием платежной карты. Задача торговой системы (электронного магазина) – в этот момент переадресовать покупателя на защищенную страницу платежного сервера (как показано на рисунке), передав при этом необходимые параметры сделки в строке переадресации.

После переадресации на защищенную страницу шлюза, взаимодействие с покупателем осуществляется по безопасному протоколу https://. Для этого платежный шлюз снабжён SSL-сертификатом, полученным от сертификационного агентства (например, компания “VeriSign”). Однако,. для аутентификации торговой системы и защиты данных от модификации в процессе переадресации все критичные данные защищаются с применением MAC (Message Authentication Code).

Программное обеспечение торговой системы должно содержать обязательные настройки – страницы для взаимодействия со шлюзом:

.
1. Страница с подготовленными значениями для передачи запроса платежному шлюзу.
2. Страница SUCCESS_URL – для редиректа браузера пользователя в случае успешного проведения транзакции. В параметрах ответа передаются результаты обработки.
3. Страница FAILURE_URL – для редиректа браузера пользователя в случае неуспешного проведения транзакции. В параметрах ответа передаются результаты обработки.
4. Страница NOTIFY_URL – для передачи результатов транзакций напрямую торговой системе от защищённого платёжного шлюза
.
Применение страницы NOTIFY_URL позволяет напрямую передать результаты транзакции от платёжного шлюза торговой системе. Данный метод значительно повышает уровень безопасности обработки транзакций – торговая система напрямую доверяет соединению со стороны платёжного шлюза, так как адрес этого источника данных зафиксирован в её системе, в отличие от адреса браузера плательщика.

Помимо этого, после подтверждения транзакции методом NOTIFY, при редиректе плательщика после проведения транзакции (п. 2, 3), в параметрах ответа передается только некритичная часть результатов обработки, обеспечивая таким образом –скрытие наиболее критичных данных от плательщика. При игнорировании настройки страницы NOTIFY_URL - все результаты обработки транзакций передаются через страницу браузера плательщика на адрес торговой системы. Подобный алгоритм поведения торговой системы является недопустимым, поскольку есть вероятность потери данных транзакций через внешние факторы: ошибки браузера, некачественное Интернет-соединение и многое другое.

.
Информацию, которую передает сервер платёжного шлюза на страницы SUCCESS_URL и FAILURE_URL необходимо использовать только для отображения результатов оплаты плательщику. Анализировать или сохранять такие данные в локальное хранилище стоит только с массива данных полученных от страницы NOTIFY URL.

2. Передача параметров авторизационного запроса серверу платёжного шлюза.

Торговой системе необходимо передать ряд параметров при переходе на защищённую страницу платёжного шлюза:

табл 1

Параметр	Назначение	Описание	Формат
Version	Значение версии интерфейса SG	Версия протокола взаимодействия. Действующая версия в данный момент ‘1’. Этот параметр является справочным для обработчика входных данных шлюза.	N
MerchantID	Идентификатор торговца	Назначается обслуживающим банком	an15
TerminalID	Идентификатор терминала	Назначается обслуживающим банком	an8
TotalAmount	Сумма заказа	Всегда указывается в мелких единицах валюты (копейки, центы)	N1..12
Currency	Валюта	Определяется договором с обслуживающим банком-эквайером	n3
AltTotalAmount (опционально)	Сумма заказа (альтернативная валюта)	Необязательный параметр. Указывается в мелких единицах валюты (копейки, центы)	N1..12
AltCurrency (опционально)	Альтернативная Валюта	Используется торговой системой при необходимости отобразить сумму платежа в другой валюте(например €, $).	n3
PurchaseTime	Время запроса в формате: yyMMddHHmmss (yyMMddHHmmssZ)	yy- год (year) MM- месяц (month in year) dd- день (day in month) HH- hour in day (0-24) mm- minute in hour ss- second in minute Z (опционально)- совпадает с зоной шлюза по умолчанию. Указывается при необходимости в формате: Z- time zone (RFC 822) Формат зоны - [+\|-] Hours Minutes(например +0300,-0200)	n12..17
locale	Язык интерфейса (en, ru, uk )	Язык интерфейса защищенной страницы шлюза	a2
OrderID	Номер заказа	Идентификатор заказа (до 20 байт)	Ans…20
SD (опционально)	Session Data -данные сессии клиента, которые передаёт торговая система	Вспомогательный параметр, может быть использован системой для управления пользовательскими сессиями	an...99
PurchaseDesc (опционально)	Краткое описание покупки, товара	Необязательный параметр, предусмотренный спецификацией 3-D Secure. Может быть отображен на странице платежного сервера. Рекомендуется использовать для удобства покупателя.	ans...1 25
Signature	Электронно-цифровая подпись данных, участвующих в генерации запроса	Длина параметра зависит от выбранной схемы вычисления	Зависит от схемы
Delay	Идентификатор платежа Преавторизация	Используется для преавторизации, при значение равном 1=включено, при 0(пусто)=выключено	N1
Ref3 (O)	Передача доп параметра в n-файл, а потом в b-файл	При помощи данного параметра можно передавать поле, содержащее не карточную информацию.	ans..1 150

Прим. табл.1.1

Формат	Format description
n- numeric decimal digit	value 0..9
an - alphabetic or numeric character	value 0..9 or A..Z or ..z
ans - alphabetic	numeric or special character

Параметры AltTotalAmount, AltCurrency определяются, если торговой системе нужно показать покупателю сумму платежа в альтернативной валюте, отличной от той, что указана в договоре, заключённом с обслуживающим банком-эквайером. При этом, на платёжный шлюз необходимо посылать 4 параметра:
.
TotalAmount, Currency - сумма и валюта по условиям договора
AltTotalAmount, AltCurrency - сумма и валюта, указанная для оплаты на сайте торговой системы.

Коды валют:

980	Ukrainian Hryvnia
978	Euro
840	United States Dollar
643	Russian Ruble

Однако, обратите внимание, что транзакция будет производиться по параметрам TotalAmount, Currency. При этом, торговец сам отвечает за соответствие сумм между разными валютами, устанавливая эти параметры самостоятельно со стороны торговой системы (правильный перерасчет в соответствии с курсом).

.
Параметры, приведенные в табл.1, передаются методом HTTPS/POST на защищённую страницу платёжного шлюза в определенной HTML-форме для дальнейшего ввода реквизитов платежной карты покупателем (держателем платежной карты).

.
Пример:

.
<form action="https://ecg.test.upc.ua/go/enter" method="POST">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<input name="Version" type="hidden" value="1" />
<input name="MerchantID" type="hidden" value="1111111" />
<input name="TerminalID" type="hidden" value="E1111111" />
<input name="TotalAmount" type="hidden" value="1000" />
<input name="Currency" type="hidden" value="980" />
<input name="locale" type="hidden" value="ru" />
<INPUT TYPE="HIDDEN" NAME="PurchaseTime" VALUE="150611110821"/>
<input name="OrderID" type="hidden" value="121sdsdss2sd" />
<input name="PurchaseDesc" type="hidden" value="tran test" />
<input name="Signature" type="hidden" value=""/>
<input type="submit"/>
</form>

После передачи HTML-формы торговой системой на защищённую страницу платёжного шлюза, производится ряд проверок со стороны шлюза (наличие регистрационных параметров торговца в БД, соответствие типа валюты зарегистрированному значению, величину авторотационного лимита для торговца, а также проверку электронной подписи). Далее, на странице платёжного шлюза, принятые данные дополняются значениями CardType, CardNumber, ExpYear, ExpMonth, CVV2 (при необходимости). После чего, шлюз отображает в браузере покупателя страницу eCommerceConnect для ввода реквизитов карты. Покупатель также может ввести код CVV2 своей карты (для карт MAESTRO ввод данного кода не предлагается). На следующем этапе происходит обработка запроса с использованием 3D-Secure схемы.

3. Возврат результатов обработки авторизационного запроса торговой системе.

Перечень параметров, передающихся в ответе шлюза торговой системе:

Параметр	Назначение	Описание	Формат
MerchantID	Идентификатор торговца	Совпадает с переданными данными в запросе авторизации	an15
TerminalID	Идентификатор терминала	Совпадает с переданными данными	an8
TotalAmount	Сумма заказа	Совпадает с переданными данными	n..12
AltTotalAmount (опционально)	Сумма заказа (альтернативная валюта)	Совпадает с переданными данными	n..12
Currency	Валюта	Совпадает с переданными данными	n3
AltCurrency (опционально)	Альтернативная Валюта	Совпадает с переданными данными	n3
PurchaseTime	Время запроса сделки (YYMMDDhhmmss)	Совпадает с переданными данными	N12
OrderID	Order ID	Совпадает с переданными данными	ans..20
XID	Идентификатор транзакции (номер заказа, до 20 символов)	Совпадает с переданными данными	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

Результаты обработки (завершения транзакции) должны быть переданы шлюзом в ответе торговой системе по адресу NOTIFY_URL. Для настройки работы данной схемы, необходимо в интерфейсе администратора (раздел терминалы) прописать адрес страницы, на которую будет осуществляться отправка данных сообщений от платёжного шлюза методом 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 = 's.sichnoy@upc.ua'
SD = '24ee6084a5343e3d'
TranCode = '000'
TerminalID = 'E7880293'
TotalAmount = '500'

После чего, торговая система возвращает ответ в теле выполняемой страницы (вывод ответа на страницу 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";

Также, у администратора торговой системы есть выбор разрешать транзакции, по которым не приходит доставка сообщения по NOTIFY_URL, либо запретить их. Данная схема позволяет автоматизированным системам учёта предоставления услуг, которые используют информацию от платежного шлюза, избежать несоответствия данных, в случае недоставки сообщения по NOTIFY_URL. В данном случае, если по каким-то причинам схема доставки ответа со стороны шлюза не отработана – транзакция будет автоматически отменена и оригинальная транзакция будет иметь тип операции «покупка», а код транзакции – 504/Данный запрос на оплату не разрешен платежным шлюзом. Откат произведенный в автоматическом режиме платежным сервером имеет код транзакции 000/Транзакция завершена успешно.

Ниже представлена логика доставки ответа торговой системе со стороны шлюза:

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>

</head> <body onload="submit()"> <form action="https://secure.upc.ua/go/pay" method="POST">

</body>

</html>

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

Поместить значение подписи в файл signature, а значение данных для подписи – в файл datafile .

Выполнить команду проверки подписи :

[root@ecgtest test]# openssl dgst -sha1 -verify gateway.pub -signature signature datafile Verified OK

5.Pre/Authorization транзакции

Торговая система имеет возможность использовать такой вид оплаты, как «Преавторизация». Данный вид оплаты может применяться для торговых систем, с такими видами деятельности, для которых сначала необходимо забронировать определённую сумму по транзакции на карте плательщика, а в расчеты данную транзакцию передать с другой, отличной от забронированной, суммой (например, в гостиничном бизнесе при предварительной оплате номера и т.д.). Для этого, в запросе на шлюз передается дополнительный параметр с именем Delay. Параметр должен иметь значение, равное «1». Соответственно, при наложении и проверке подписи шлюзом, он указывается рядом с полем OrderID, через запятую.

Последовательность такая:

1. Торговая система шлет запрос с параметром Delay=1 и нужной суммой
2. Кардхолдер проходит обычную процедуру оплаты используя схему 3DSecure или ввод кода CVC2.
3. При успешной транзакции происходит блокировка средств по карте плательщика, транзакции присваивается тип операции «Преавторизация».
4. Далее, в расчеты эта транзакция не идет. Для совершения оплаты -перевода средств на счет торговой системы, в её интерфейсе необходимо выбрать: →Поиск: Тип операции=Преавторизация→Код транзакции=Успешно → указать окончательную сумму для оплаты
5. На данный момент эта операция имеет следующие ограничения –
- окончательная сумма платежа не может превышать 20% от суммы оригинальной транзакции
- после 30 дней транзакции «Преавторизация» автоматически удаляются.

6. Завершить оплату можно двумя способами:

- в админ.панели UPC открыть платеж, ввести сумму списания и подтвердить действие.
- для завершения платежа использовать XML запрос "Поставторизация"
7. После успешно завершённой оплаты, транзакция «Преавторизация» превращается в тип «Пост-авторизация», что говорит о факте совершения окончательной оплаты и формируется новая транзакция для расчетов с типом «Покупка».
8. Дополнительно, на успешную транзакция «Покупка» может быть выполнена только одна операция «Возврат».

Возможные коды ошибок:

506 – срок оплаты транзакции «Преавторизация» истек(более 30 дней )
507 – оплата транзакции «Преавторизация» уже была произведена (повторная попытка)
508 – неправильная сумма для оплаты (неправильное значение или значение больше, чем на 20% от суммы оригинальной транзакции)

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	yy- год (year) MM- месяц (month in year) dd- день (day in month) HH- hour in day (0-24) mm- minute in hour ss- second in minute	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";
.