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

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

1. Платёжный интерфейс взаимодействия с авторизационным сервером.

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

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

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

Перенаправление клиента для авторизации на АС Cyberplat

Для вызова cgi-программы необходимо обратиться по адресу https://card. *****/cgi-bin/GetForm. cgi и передать методом POST следующие параметры:

Параметр	Длина поля или значение	Пояснение
version	10 ,значение «2.0»	Версия протокола взаимодействия. Формат переменной создаётся по маске XX. XX. XX, все поля заполнять необязательно. Сейчас это версия 2.0. Эта переменная является справочной для скрипта getform. cgi. Принята в целях облегчения анализа работы скриптов и выбора способа обработки данных.
сryptotool	Ipriv / Verba	средство криптования подписанной строки, необязательный параметр, при отсутствии принимается равным «Ipriv».
message		Подписанная cgi-строка с указанными ниже параметрами.

Формирование подписанной строки данных транзакции

Все переменные в подписанной строке чувствительны к регистру символов. Это означает, что, например, переменные paymentdetails или PAYmentdetails не будут обработаны, в отличии от переменной PaymentDetails. Порядок следования параметров не существенен, но рекомендуется придерживаться указанной ниже очерёдности:

Наимено- вание параметра	Формат поля, максимальный размер или значение	Обязатель- ность параметров (+/–)	Пояснение
OrderID	255	+	Номер заказа в магазине, может быть уникальным или нет, в зависимости от настроек магазина в Платёжной системе
Amount	Numeric	+	сумма к оплате Сумма указывается в наименьших единицах валюты (копейка, цент)
Language	Значения из справочника. В настоящее время доступны следующие значения: ru – русский; en – английский	-	Язык ответа авторизационного сервера. При отсутствии принимается равным установленному по умолчанию на магазине. и сообщения клиенту возвращается в соответствии с этими установками
Currency	Значение из справочника. Код валюты соответствует ISO: RUR – рубли; USD – доллары; EUR - евро	+	Код валюты. Обязательный параметр, так как является необходимой характеристикой суммы транзакции. Обязательность параметра принята во избежание конфликтов с магазином
PaymentDetails	255	-	Описание (назначение) платежа. Это поле отражается в выписке по счёту магазина, что удобно бухгалтерии магазина для дальнейшего анализа, а также в электронном чеке, предъявляемом клиенту при успешной авторизации
CardType	Значение из справочника. Сейчас доступны следующие типы:AX – American Express DC –Diners ClubEP – E-PORTEU – EuroCard/ MasterCardJC – JCBUC – Union CardVI – VISAСписок может пополняться другими платёжными средствами	-	Тип платёжного средства. Может быть использован в случае, если магазин явно хочет предоставить клиенту выбор типа платёжного средства на своей стороне. Необходимо отметить, что при этом рекомендуется устанавливать соответствующее значение поля registered. Тогда клиент будет перенаправлен сразу на вторую авторизационную страницу. Кроме того, каждому магазину соответствует свой список карт, поскольку разные процессинги могут обрабатывать не все карты из приведённого списка
Registered	True / False	-	Зарегистрирован ли клиент в системе CyberPlatPay. Значение «true» используется только в случае, если необходимо авторизовать зарегистрированного клиента CyberPlatPay. В остальных случаях необходимость передачи параметра отсутствует
FirstName	Макс. длина поля 70 символов	+	имя покупателя
MiddleName	Макс. длина поля 70 символов	-	отчество покупателя
LastName	Макс. длина поля 70 символов	+	фамилия покупателя
Email	Макс. длина поля 70 символов	+	E-mail клиента
Phone	Макс. длина поля 70 символов	-	Телефон покупателя. Желательно передача этого параметра, если клиент ранее сообщил его магазину
Address	Макс. длина поля 255 символов	-	Адрес покупателя. Передаётся магазином, если клиент указал свой адрес или адрес доставки
POS	до 5 символов	-	Зарезервировано для будущего использования
Terminal	Макс. длина поля 80 символов	-	Код терминала – используется магазинами (биллингами) в случаях обслуживания веб-мастеров, или использования нескольких подразделов. Этот параметр возвращается в магазин после авторизации и может быть использован для отображения разных шаблонов
ShopIP		+	IP-адрес сервера магазина (берется из файла Paths, pm)
return_url		+	Адрес, на который необходимо вернуть клиента после завершения авторизации

Пример

<form method=post action=

"https://payment. *****/cgi-bin/Version1.5/

GetForm. cgi">

<input type=hidden name=version value="2.0">

<input type=hidden name=message

value="SM

0mt0

BEGIN

OrderID=&Amount=400&Currency=RUR&PaymentDetails=оплата

заказа #&Email=*****@***com&FirstName=cyberplat&

LastName=support&MiddleName=none&Phone=74

5-4060&Address=Moscow, Kutuzovsky pr.12&Language=

ru&return_url=http://mike. /cgi-bin/cyberpos/result. cgi

END

//BEGIN SIGNATURE

iQBRAwkBAAArxjyPLFgBARB4AgCRvBKq1eCmQ8Fh5Hr2NShLVbcRE0PqJTre0gd3

5MhUk86jOy8JTqjxGp5WYTEsJ4JZaJYRWK5FLmtIRZ05/BWj=l/qV

END SIGNATURE">

</form>

Возврат клиента на сервер магазина

После ввода данных клиентом cgi-приложение, расположенное по адресу https://card. *****/cgi-bin/putdata. cgi вернёт клиенту html-страницу c переадресацией на сайт магазина. После загрузки данной страницы браузер клиента вызовет скрипт на сервере магазина, указанный ранее в переменной return_url.

Пример

<BODY onLoad='document. forms[0].submit()'>

<FORM method=post action=

'http://mike. /cgi-bin/cyberpos1.5/

result. cgi'>

<INPUT type=hidden name=language value='ru'>

<INPUT type=hidden name=orderid value=''>

<INPUT type=hidden name=reply

value='SM

CyberCardServer

BEGIN

Status=0&SessionID=&OrderID=

&TransactionID=

&TransactionAmount=400&TransactionCurrency=

RUR&TransactionDate=13.03.2002 15:53:27

GMT+3&AuthCode=VS2E3A50D&CustomerName=support&PaymentDetails=

оплата заказа #&CustomerTitle=Платеж прошел.

&CustomerMessage=Ваш платеж успешно прошел авторизацию.

&Description=Ваш платеж успешно прошел авторизацию.

END

BEGIN SIGNATURE

iQBRAwkBAACOljyPS8cBAW82Af47HmobgtYKPon2yltrFUsaGDHyCocEMKHDQHrF

zz7W4DkzK2vir4lHqlGNN1NC6iTw4RrtTWSJyDOF6304r/6a=YtTH

END SIGNATURE'>

</FORM>

</BODY>

Пояснения по переменным:

Параметр	Пояснение
Action	Вызываемый скрипт на стороне магазина. Его значение равно return_url из подписанной входной строки
Language	Язык сообщений. Необходим магазину для возможности отображения шаблона на соответствующем языке. Равен соответствующему параметру во входящей подписанной строке
Ordered	Справочный параметр – номер заказа. Равен соответствующему параметру во входящей подписанной строке. Используется лишь для лог-файла. После проверки ЭЦП необходимо использовать параметр OrderID из исходящей подписанной строки
Reply	Подписанная cgi-строка с указанными ниже параметрами

Состав подписанной строки:

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

Положительный ответ

В случае необходимости магазин может обратиться в службу поддержки клиента для настройки списка передаваемых авторизационным сервером параметров – некоторые параметры являются настраиваемыми. В случае успешного ответа о результатах авторизации магазин обязан выдать на экран клиенту электронный чек.

Образец чека:

Название торговой точки АО «Стандарты образования» Наименование точки Books shop URL электронного магазина www. Контактные координаты *****@***com Сумма операции в валюте транзакции 30 RUR Дата заказа 10.11.2001 15:45:10 GMT+3 Код авторизации 165388 Идентификатор транзакции Имя покупателя Pupkin Vasily Тип операции Sale Описание услуг Оплата книги «Стандарты качества»

Для формирования электронного чека магазин должен выдавать следующие поля:

Отображаемое на экране сообщение на русском языке	Сообщение на английском языке	Подставляемый параметр из ответа АС или параметров магазина	Пояснение
Название торговой точки	Enterprise name		Торговое наименование предприятия (“Doing business as” name). Магазин самостоятельно выдаёт это значение
Наименование точки	Merchant name		Латинское наименование магазина в процессинге. Магазин самостоятельно выдаёт это значение. Его можно уточнить в Коммерческом Департаменте после регистрации торговой точки в процессинге. Это поле отображается в выписке по карте у клиента
URL электронного магазина	Shop URL		Магазин формирует это значение самостоятельно. Магазин самостоятельно выдаёт это значение
Контактные координаты	Help desk		Контактный электронный адрес предприятия или контактный телефон для связи с покупателями. Магазин самостоятельно выдаёт это значение
Сумма операции в валюте транзакции	Transaction Amount	TransactionAmount	Сумма операции в валюте, установленной эквайрером в договоре. В случае, если конвертации не было, совпадает со значением параметра Amount
		ТransactionCurrency	Валюта операции в валюте, установленной эквайрером в договоре, указывается сразу же после суммы операции
Дата заказа	Transaction Date	TransactionDate	Дата и время транзакции в формате «DD. MM. YYYY HH:MI:SS GMT+…»
Код авторизации	Code authorization	AuthCode	Код авторизации, полученный от процессингового центра
Идентификатор транзакции	Сode transaction	TransactionID	Код транзакции в системе CyberPlat
Имя покупателя		CustomerName	Имя клиента, введённое на авторизационной странице
Тип операции	Operation type		Константа, всегда пишется при успешной авторизации “Electronic commerce”
Описание услуг	Payment Details	PaymentDetails	Описание услуг. Формируется самим магазином при передаче входных параметров

Отрицательный ответ

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

if(!document. getElementById){ document. write("

Пример:

"); } else{ document. write("

Пример подписанной строки

"); document. write(""); } Пример подписанной строки

BEGIN Status=-10&SessionID=&OrderID=&PaymentDetails=оплата заказа #&ErrorCode=154478&CustomerTitle=Платеж не прошел&CustomerMessage=Вы ввели неверный номер карты.
Пожалуйста, вернитесь на страницу ввода карточных данных и введите правильный номер карты.&Description=Вы ввели неверный номер карты.
Пожалуйста, вернитесь на страницу ввода карточных данных и введите правильный номер карты. END if(!document. getElementById){} else{ document. write(""); }