Документация для ПО CyberPOS версии 2.0 (стр. 3 )

5. Интерфейс взаимодействия с АС по проведению транзакций reversal.

Общие сведения

В настоящее время взаимодействие с Авторизационным Сервером (АС) Cyberplat в процессе проведения транзакций по отмене платежей (reversal), ещё не прошедших финансовую авторизацию, магазин может осуществлять самостоятельно, придерживаясь нижеследующих правил. Передача данных осуществляется только по безопасному протоколу https. Для этого АС снабжён SSL-сертификатом известной компании. Однако для аутентификации магазина и защиты данных от модификации посторонними лицами в платёжной системе все существенные данные подписываются электронно-цифровой подписью определённого формата. Описанные ниже протоколы взаимодействия с АС могут быть использованы программистами веб-магазинов для написания собственного ПО для выполнения транзакций reversal. Также приведены примеры запросов и ответов АС.

Для магазинов, не желающих самостоятельно осуществлять данный механизм работы, существует специальное программное обеспечение (ПО), реализующее взаимодействие с АС Cyberplat, а также соответствующая документация.

Описание взаимодействия

На АС располагается cgi-приложение (скрипт) по приёму запросов:
https://card. *****/cgi-bin/ProcessTransaction. cgi. Параметры транзакции передаются методом HTTP POST, в единственном параметре запроса – message=<тело подписанного сообщения>

Параметры, передаваемые магазином внутри подписанного сообщения:

TransactionID	Код успешной транзакции. Берётся из ответа на авторизацию родительской транзакции. Обязательный параметр
Comment	Комментарий. Если возможно, магазин должен посылать комментарий по отменяемой транзакции – указание на причину отмены. Длина поля – не более 125 символов. Кодировка – win-1251. Необязательный параметр

Ответ авторизационного сервера на транзакцию Reversal:

Status	Статус транзакции. 0 – успешно проведена, любое иное число - код ошибки
ParentTransactionID	Код отменяемой транзакции. Равен полю TransactionID в запросе от магазина
ErrorCode	Код ошибки (если она была)
Description	Текстовое пояснение результата обработки. При положительном ответе – «Transaction completed», при ошибках – расшифровка ошибки

Все параметры в сообщении соединяются знаком «&» (амперсанд).

Примеры запроса на Reversal

SM

0mt

BEGIN

ParentTransactionID=1103883&TransactionType=Reversal

END

BEGIN SIGNATURE

iQBRAwkBAAAlljuq/usBAaiKAgCEP5oglRcaCQkgNPquCwnAR0YHlnY37ZDcUxRh

KF5xD2qAjhdf/cEE1v9eUbQT7U73u69OJKbcJuyfH2rTRw95

=7TfA

END SIGNATURE

Пример страницы с операцией Reversal

<form action="https://card. *****/cgi-bin/processtransaction. cgi"

method=post>

<input type=hidden name=message

value='SM

0mt0

BEGIN

TransactionID=1800739&TransactionType=Reversal

END

BEGIN SIGNATURE

iQBRAwkBAAArxjuu3E8BATY7Af4pEem/5cQVOEcbYZ8TAyKiev6yPfo3uWGTLiAr

vqK+Fg+OnHdFBNFIIisqE0XMyn8AHvdAY8wWyecvEngobuok

=5XXW

END SIGNATURE'>

<input type=submit>

</form>

Пример ответа об успешной обработке транзакции

SM

AutServer

BEGIN

Status=0&ParentTransactionID=1103883&Description=Transaction completed

END

BEGIN SIGNATURE

iQBRAwkBAAAlljurACsBAU6jAf4zPF2pjpO125YYfGtqPczGPUUkkSUNI5hUar8e

M1hOg2owBctzJFLJPY+GUFoK2AhAVrzJiQX7aKBwE2wZjDap

=0tg6

END SIGNATURE

Дополнение

Помимо выдачи ответа на запрос, Авторизационный Сервер формирует электронное письмо по адресу магазина с подписанным ответом. Описание сообщений по электронной почте приводится в соответствующем документе.

Кроме того, транзакции этого типа оператор магазина может просмотреть в журнале транзакций.

6. Модуль для проведения магазинами транзакций reversal .

Общее описание модуля

Модуль управления транзакциями reversal (далее «модуль») позволяет магазинам самостоятельно проводить операции по отмене платежей, не отправленных на финансовую авторизацию (reversal). Модуль реализован как часть ПО CyberPOS и использует некоторые его настройки и функции. Поэтому к его настройке рекомендуется приступать после настройки модуля оплаты заказов.

К модулю прилагаются 2 htm-страницы, одна из которых предназначена для ввода информации по отменяемым платежам, а другая – для отображения результатов. Страницы находятся в каталоге /Templates магазина. Дизайн страниц может быть изменен клиентом или вовсе не использоваться. Во втором случае подразумевается использование модуля другим клиентским приложением, например, если магазин имеет интегрированную среду управления и может настроить ее для вызова модуля и получения результатов транзакций.

Рекомендации по безопасности

Важно: доступ к скрипту должен быть с аутентификацией, во избежание проведения транзакций посторонними лицами. Можно ограничить доступ средствами веб-сервера, установив права на запуск скрипта в файле. htaccess (для сервера Apache). Либо скрипт должен находиться во внутренней сети магазина. Эти меры безопасности необходимы для исключения мошеннических операций посторонними лицами. В скрипте содержится переменная $Security, которая по умолчанию установлена в ‘1’. После принятия мер безопасности установите её значение равной ‘0’.

Для безопасной передачи данных на сервере магазина должна быть установлена поддержка SSL протокола. Установка необходимого ПО описана в соответствующем приложении ниже. Для Unix систем требуется установить библиотеку OpenSSL и модуль Net-SSLeay, для Windows – Perl модуль Crypt-SSLeay. Прежде чем использовать ПО для реальных транзакций, следует отладить его работу в тестовой системе.

Описание работы модуля

1.  Модуль принимает параметры запроса, переданные ему из html-формы или другим приложением. Описание параметров модуля дано в таблице ниже.

2.  Проверяет корректность полученных параметров. Если ошибок нет, формирует строку запроса и подписывает ее электронно-цифровой подписью (ЭЦП) магазина. В случае обнаружения ошибок выдаётся соответствующее сообщение.

3. Передает запрос на Авторизационный Сервер (далее АС) и получает результат транзакции.

4.  Сохраняет ответ сервера в файле чека (с расширением. res) и файле сессии (с расширением. sta) в каталоге /Sessions/reversal, если это указано в настройках. В случае, если транзакция по платежу с таким кодом уже проводилась, результаты по следующим транзакциям будут дописываться в конец существующих файлов чеков/сессий.

5. Проверяет подпись АС и разбирает ответ.

6. Записывает результаты транзакции в файл сессии. В случае, если транзакция по платежу с таким кодом уже проводилась, результаты по следующим транзакциям будут дописываться в конец существующих файлов чеков/сессий.

7. Выводит результат в браузер или возвращает его вызвавшему приложению. Помимо ответа на запрос Авторизационный Сервер сформирует и отправит сообщение по электронной почте. Параметры сообщения описаны в соответствующем документе.

Описание параметров, передаваемых модулю:

TransactionID	Код успешной транзакции. Должен быть цифровым. Обязательный параметр
Comment	Комментарий. Если возможно, магазин должен посылать комментарий по отменяемой транзакции – указание на причину отмены. Длина поля – не более 125 символов. Кодировка – win-1251. Необязательный параметр

Использование модуля

Существует 2 варианта использования модуля:

1. Запуск скипта reversal. cgi в браузере. Будет загружена форма для ввода параметров запроса. Результат отображается в браузере.

2. Запуск скипта reversal. cgi из другого приложения. Передача параметров осуществляется в следующем формате:
TransactionID=<код транзакции> Comment =<ваш комментарий>.

Все параметры должны быть разделены пробелами. Результат будет возвращен вызывающей программе в виде строки параметров, например:
Status=0&ParentTransactionID=987654&Description=успешно проведена операция reversal
В случае ошибки при анализе входных параметров строка ответа будет содержать слово Error:
Error: Incorrect TransactionID, must be numeric.

В обоих вариантах результаты транзакции будут записываться в каталог сессий в соответствии с настройками, описанными в следующем параграфе.

Кроме того, магазин может самостоятельно взаимодействовать с АС, используя протокол, описанный в разделе «Интерфейс взаимодействия с АС по проведению транзакций reversal ».

Настройка пользовательских параметров модуля

Все настраиваемые пользователем переменные находятся в блоке USER DEFINED VARIABLES скрипта reversal. cgi. Настройка некоторых из них обязательна.

my $Security = 1;	Блокирует запуск скрипта. Установите в ‘0’ для снятия блокировки (предварительно приняв меры по защите скрипта от несанкционированного запуска)
my $ShowPage = 1;	Выводить или нет результаты запроса в браузер. ‘0’ - нет, ‘1’ - да. '0’ используется при вызове модуля другим приложением
my $SaveChecks = 1;	Сохранять ли чек (результат транзакции, подписанный сервером). ‘0’ - нет, ‘1’ - да. По умолчанию - ‘1’. Чеки сохраняются в файлах формата id_транзакции. res в подкаталоге или /Sessions/reversal в зависимости от типа транзакции
my $LogTolerance = 1;	Степень детализации сообщений в лог-файле reversal. log. ‘1’ – записывать все сообщения (рекомендуется при отладке), ‘2’ – отражать только основные этапы транзакции, ‘3’ – не вести лог
# my $BasePath = 'C:/Apache/cgi-bin/reversal';	Путь к каталогу модуля. Используйте эту переменную, только если модуль не определяет путь самостоятельно. В этом случае просто удалите знак комментария ‘#’ перед именем переменной и укажите правильный путь (не ставьте заключительный ‘/’ в конце)
my $ServerURL = “https://card. *****/cgi-bin/processtransaction. cgi;” (реальный сервер) my $ServerURL = “https://payment. *****/cgi-bin/ProcessTransaction. cgi;” (тестовый сервер)	Переменная настраивается, только если она установлена некорректно. Правильный URL можно узнать обратившись в службу поддержки по *****@***ru

Приложение: Интерпретатор языка Perl и дополнительные модули CPAN для Windows и Unix

Для работы ПО магазина необходимо иметь установленный интерпретатор языка Perl версии 5.005 и выше для Unix, ActivePerl версии 5.22 и выше для Windows. Более подробно об установке и настройке Perl следует читать в документе по установке ПО магазина. В этом приложении описана установк дополнительных модулей для взаимодействия магазина с Авторизационным Сервером. Для этого на сервере магазина должна быть установлена поддержка SSL протокола - Crypt-SSLeay для Windows и Net-SSLeay для Unix-платформ.

Описание установки библиотеки Crypt-SSLeay для ActivePerl для Windows

Библиотека построена на основе кода проекта OpenSSL и представляет собой свободно распространяемую реализацию протокола SSL для языка Perl. Для ActivePerl она существует в виде скомпилированного бинарного файла и может быть взята из дистрибутива ПО магазина, либо с сайта ActiveState и установлена следующим образом:

1.  Разархивируйте архив во временный каталог

2.  Удалите в файле Crypt-SSleay. ppd строку <ARCHITECTURE NAME="MSWin32-x86-object" />

3.  Запустите утилиту ppm (ppm install crypt-ssleay. ppd)

Описание установки модуля Net-SSLeay для Unix

Для Perl под UNIX-системы необходима установка дополнительного модуля Net-SSLeay. Его можно взять из дистрибутива ПО магазина или с сайта Perl Modules. Для его установки потребуется библиотека проекта OpenSSL (версии 0.95а и выше). Установку см. ниже.

Установка библиотеки OpenSSL

Необходимо наличие на компьютере компилятора С (желательно gcc).

1.  выполнить распаковку архива: gunzip < openssl-0.9.5a. tar. gz | tar xvf>, при этом создается подкаталог openssl-0.9.5a, куда разархивируется содержимое файла

2.  Перейти в созданный каталог: cd openssl-0.9.5a

3.  Выполнить из командной строки скрипт конфигурации: ./config

О возможных (необязательных) параметрах можно прочитать в файле INSTALL в этом каталоге.

§  Один из полезных параметров: - prefix=DIR, где DIR – корневой каталог, куда будут установлены библиотеки и файлы openssl (DIR/bin, DIR/lib, DIR/include/openssl). Например - /usr/local

4.  Последовательно выполнить из командной строки

make make test make install

Установка модуля Net-SSLeay

Необходимо наличие компилятора С (желательно gcc) и Perl, версии не ниже 5.005.

Выполнить распаковку архива: gunzip < имя архива | tar xvf > Перейти в созданный каталог (cd имя-каталога) Последовательно выполнить из командной строки следующие команды:

perl Makefile. PL make make test make install

____________________________________________________________________________________

7. Принципы оповещения о транзакциях по электронной почте.

Основной задачей оповещения является передача сообщения об авторизации операторам магазина. При этом письмо может быть отправлено одновременно по нескольким адресам.

Заголовок сообщения содержит общую информацию о платеже и не является основанием для принятия решения. Детализация ответа содержится непосредственно в теле письма. При этом ответ, содержащийся в теле письма подписан электронно-цифровой подписью (ЭЦП). Таким образом, проверив подпись под письмом, можно твёрдо знать о результате авторизации.

Формат сообщения может отличаться по количеству передаваемых параметров от сообщения, выданного через web-интерфейс. Это обусловлено тем, что в письме можно дать более подробную информацию, нежели при передаче ответа через браузер клиента. Компания Cyberplat оставляет за собой право изменять сообщение, основываясь на пожеланиях клиентов и пользователей и планами дальнейшего развития системы.

Заголовок сообщения (subject)

Для каждого типа авторизации формируется отдельный заголовок.

Для транзакции типа sale (e-commerce) заголовок выглядит следующим образом: «Payment for order #NNNN. Result=code», где

NNNN – входящий номер заказа (формируется магазином); code – код результата обработки транзакции.

Пример заголовка: «Payment for order #1156-78/12. Result=0».

Для транзакций refund (credit), reversal (void), rebilling заголовок должен формироваться следующим образом:«TYPE for transaction #NNNN. Result=code», где

TYPE – тип транзакции, формируется магазином при отправке транзакции на авторизацию; NNNN – номер родительской транзакции; code – код результата обработки транзакции.

Пример заголовка: «reversal for transaction #9091156. Result=0».

Тело сообщения (body)

При авторизации транзакции типа sale (e-commerce) Авторизационный Сервер (АС) формирует тело письма из следующих параметров:

Наименование параметра	Формат поля, макс. размер	Наличие параметра: + – всегда - – может отсутствовать E(error) – при ошибке, отказе в авторизации S(successfully) – при успешной авторизации * – возможно при соответствующей настройке магазина в системе	Пояснение
Status	Numeric	+	Статус транзакции. 0 – успешно проведена, -1 – принята на исполнение, любое иное число - категория ошибки
OrderID		+	Номер заказа, равен входящему параметру, переданному магазином
SessionID	Numeric	+	Номер сессии
TransactionID	Numeric	-	Код транзакции. При Status<>0 может отсутствовать (в случаях ошибок или отказов до авторизации в платёжных системах)
Amount		+	сумма транзакции (в копейках/центах, напр. 10руб – 1000), равна входящему параметру, переданному магазином
Currency	Значение из справочника. Код валюты соответствует ISO: RUR – рубли; USD – доллары	+	Код валюты, равен входящему параметру
TransactionAmount		S	Сумма операции в валюте (в копейках/центах), установленной эквайрером в договоре. Возвращается при положительном ответе. В случае, если конвертации не было, совпадает со значением параметра Amount
ТransactionCurrency	Значение из справочника. Код валюты соответствует ISO: RUR – рубли; USD – доллары	S	Валюта операции в валюте, установленной эквайрером в договоре. Возвращается при положительном ответе. В случае, если конвертации не было, совпадает со значением параметра Currency
ErrorCode	30	E	В случае возникновения ошибок при обработке транзакции или отказе процессинга в обработке возвращается код ошибки – текстовое значение до 30 знаков. Отсутствует при положительном ответе и может отсутствовать в случае ошибок криптографического характера
Description	255	+	Текстовое пояснение результата обработки. Берётся из базы данных в соответствии с языковыми настройками магазина или переданным параметром lang. В случае ошибки или отказа – связано с полем ErrorCode, поясняет его
CustomerName	35	S	Имя покупателя, обязательно передаётся в случае положительного ответа
PaymentDetails		+	Описание услуг. Этот параметр используется для отображения в электронном чеке. Равен входящему параметру PaymentDetails
TransactionDate		S	Дата транзакции в формате «DD. MM. YYYY HH:MI:SS GMT+3». Возвращается при положительном ответе
AuthCode	10	S	Код авторизации в соответствующем процессинге. Возвращается при положительном ответе
Terminal	80	+	Совпадает со значением соответствующего входного параметра
POS	5	+*	Совпадает со значением соответствующего входного параметра. Сейчас этот параметр зарезервирован

Пример

От: " Support"

Кому: *****@***biz

Тема: Status=-99&SessionID=&OrderID=&

Amount=400&Currency=RUR& ErrorCode=-20647&Description=-20647

Тело письма:

SM

CyberCardServer

BEGIN

Status=-99&SessionID=&OrderID=&

Amount=400&Currency=RUR& ErrorCode=-20647&Description=-20647

END

BEGIN SIGNATURE

iQBRAwkBAACOljyF/hEBAcrSAf48UnIzVlMXWMG1IYon75orinGv+

bWQ3t5QzAwOFLyNkWnyAPUJCHxHXn+Xkg4OonL2LD55E4Q0eU9yofQSA0wd

=plCI

END SIGNATURE

При авторизации транзакции типа refund (credit), reversal (void), rebilling АС формирует тело письма из следующих параметров:

Наименование параметра	Формат поля, максимальный размер	Наличие параметра: + – всегда - – может отсутствовать E(error) – при ошибке, отказе в авторизации S(successfully) – при успешной авторизации * – возможно при соответствующей настройке магазина в системе	Пояснение
Status	Numeric	+	Статус транзакции. 0 – успешно проведена, -1 – принята на исполнение, любое иное число - категория ошибки
OrderID		+(только для транзакций rebilling)	Номер заказа, равен входящему параметру, переданному магазином
TransactionID	Numeric	+	Код транзакции. При Status<>0 может отсутствовать (в случаях ошибок или отказов до авторизации в платёжных системах)
ParentTransactionID	Numeric	+	Код транзакции. При Status<>0 может отсутствовать (в случаях ошибок или отказов до авторизации в платёжных системах)
ErrorCode	30	E	В случае возникновения ошибок при обработке транзакции или отказе процессинга в обработке возвращается код ошибки – текстовое значение до 30 знаков. Отсутствует при положительном ответе и может отсутствовать в случае ошибок криптографического характера
Description	255	+	Текстовое пояснение результата обработки. Берётся из базы данных в соответствии с языковыми настройками магазина или переданным параметром lang. В случае ошибки или отказа – связано с полем ErrorCode, поясняет его

8. Описание журнала транзакций.

Для работы операторов магазинов с прошедшими транзакциями на авторизационном сервере (card. ***** - для реальной системы, payment. ***** – для демонстрационной) реализован журнал платежей (транзакций). В нём оператор может просмотреть список транзакций по своему магазину с использованием разнообразных фильтров, а также узнать текущее состояние транзакций.

Вход в систему осуществляется с помощью логина и пароля, введённых ранее при регистрации магазина.

После авторизации оператора он попадает на страницу журнала, где может выбрать условия фильтрации платежей. Следует отметить, что необходимо максимально точно указывать условия отбора платежей. Это даст наиболее быстрый результат.

Возможные способы фильтрации

1. За период – здесь доступны для одновременной настройки следующие способы выбора:

период c:	необходимо выбрать интервал дат для отображения платежей
тип платежа:	выбрать интересующий тип транзакции – Sale (обычная покупка), Refund (перечисление средств клиенту), Reversal (отмена транзакции и снятие блокировки средств со счёта клиента)
статус транзакции	можно выбрать успешные или неуспешные транзакции
платежные средства:	можно выбрать определённый тип платёжного средства
валюта платежа:	возможен выбор определённой валюты платежа (если магазин практикует отправку платежей в разных валютах)

2. По номеру заказа

3. По номеру сессии

Второй и третий способы используются для случаев, когда оператору требуется выяснить статус конкретных транзакций. Эти способы наиболее быстрые.

Оператор может выбрать способ сортировки транзакций. При сортировке по убыванию наверху отражаются самые новые транзакции. Минимально в журнале транзакций отображаются следующие поля: номер платежа (заказа); сумма и код валюты; дата платежа; номер сессии; номер транзакции; имя клиента.

Оператор может выбрать дополнительные поля для отображения:

Код терминала	это поле можно использовать, если магазин отправляет платежи по разным терминалам
Описание платежа	В этом поле содержатся данные, переданные магазином в поле PaymentDetails (Description)
Дата on-line авторизации	дата проведения платежа
Дата финансовой авторизации	дата отправки транзакции на финансовую авторизацию. Обычно – это следующий рабочий день
Успешный/неуспешный платеж	результат авторизации
Статус транзакции	текущее состояние платежа – прошёл on-line авторизацию, отправлен на финансовую авторизацию (ФА), прошёл ФА, получены денежные средства (только для магазинов, работающих через банк «Платина»)
Тип кредитной карты	отображение типа платёжного средства, использованного при оплате платежа
Номер карты	номер карты покупателя (отображается последние 4 цифры, например ***0017)
Тип транзакции	возможные значения – sale, reversal, refund