Подключение Библиотеки для обслуживания банковских карт с помощью OLE AUTOMATION
(версия для Windows)

Краткое описание интерфейса

Оглавление

Оглавление
Общие сведения
Установка
Интерфейс с библиотекой
Общая схема реализации запроса
Краткое описание функций
Функция  SРaram
Функция  GРaramString
Функция  NFun
Функция  Clear
Печать чека (слипа)
Пример выполнения оплаты
Платежи с дополнительными реквизитами
Платеж с возможностью аварийной отмены
Классы функций
Класс 4 — финансовые операции по картам
Класс 5 — информационные операции по картам
Класс 6 — служебные операции по картам
Класс 7 — общие служебные операции

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

Библиотека предназначена для обслуживания международных банковских карт: Mastercard, Maestro, VISA, VISA Electron, Amex, Diner Club. 

Требования к оборудованию и программному обеспечению:
•	наличие COM– или USB-порта для подключения ПИН – клавиатуры 
•	сетевая карта с установленным TCP/IP или com – порт для подключения модема.
•	Windows 98/NT/2000/XP/Vista.
Установка

1.	Скопировать  на жесткий диск следующие файлы:

SB_KERNEL.DLL
GATE.DLL
SBRF.DLL
LOADPARM.EXE
RRDK.R
R003.R
PARAMS.TLV
 
2.	Зарегистрировать библиотеку  SBRF.dll с помощью команды (regsvr32 SBRF.dll). 
3.	Подключить ПИН-клавиатуру к порту СОМ1 или к USB-порту.
4.	Выполнить загрузку настроечных параметров библиотеки. Для этого запустить программу LOADPARM.EXE, зайти в меню «Служебные операции \ Настройки \ Техобслуживание \ Пароль 878787 \ Загрузка параметров», выбрать файл PARAMS.TLV и дождаться окончания загрузки.
Интерфейс с библиотекой
Общая схема реализации запроса
•	Создать объект типа  SBRFSRV.Server
•	Вызвать функцию SParam для каждого входного параметра и задать необходимые входные значения.
•	Вызвать функцию Nfun с нужным номером функции. 
•	Проанализировать код ошибки. Если он равен 0, операция успешно выполнена. В противном случае операция отклонена.
•	Вызвать функцию GParamString для нужных выходных параметров и получить выходные   значения.  
•	Вызвать функцию Clear.
Краткое описание функций
Функция  SРaram 
Функция  SParam  (Name, Value) предназначена для задания входных параметров.
Name - имя входного параметра. 
Value - значение входного параметра.
Возвращает S_OK при удачной реализации. 
Функция  GРaramString
Функция  GParamString(Name, Value)  предназначена для получения выходных параметров.
Name - имя выходных параметра. 
Value - значение выходного параметра.
Можно вызывать 2 способами: 
1.	GParamString(Name, Value) 
2.	Value =GParamString(Name)

Возвращает значение параметра с именем Name.

Функция  NFun
Функция  NFun(func) предназначена для запуска определенной функции в библиотеке (после того как необходимые входные параметры будут заданы).
Параметр func задает номер вызываемой функции. Подробное описание номеров функций библиотеки приводится в Приложении.
Возвращает код ошибки. 0 – успешное выполнение, любое другое – ошибка.

Функция  Clear
Функция  Clear()  предназначена очистки списка параметров.
Возвращает S_OK при удачной реализации.

Печать чека (слипа)
Одним из выходных параметров при успешном выполнении платежа является образ карточного чека (слипа). Он представляет собой длинную ASCII-строку, содержащую внутри переносы строк. Вызывающая программа должна отправить эту строку на печать в нефискальном режиме. Никаких предположений относительно содержимого этой строки вызывающая программа делать не должна.
Получить образ чека можно вызовом функции GParamString с параметром «Cheque».

Последовательность действий для выполнения оплаты
Для выполнения операции оплаты покупки необходимо:

1)	Создать объект типа SBRFSRV.Server.
2)	Установить параметр «Amount» в значение, соответствующее сумме покупки (в копейках).
3)	Вызвать функцию NFunc(4000).
4)	Проанализировать код результата. Если он равен нулю, операция успешно выполнена. В этом случае необходимо получить значение параметра «Cheque» и отправить его на печать.
5)	Если операция была успешно выполнена, но печать чека выполнить не удалось, или если на чеке имеется графа «Подпись клиента», а клиент отказался подписывать чек, то операцию следует отменить вызовом функции NFunc(6004).
6)	Удалить объект SBRFSRV.Server.

Пример реализации на Visual Basic:

Sub Payment()
Dim MyCheque As String
Dim MyServ As Server

Set MyServ = New Server

MyServ.Clear
MyServ.SParam "Amount", "123"          ‘ сумма оплаты 1 руб. 23 коп.

If MyServ.NFun (4000) = 0 then 

  MyCheque           = MyServ.GParamString("Cheque")

  If PrintCheque(MyCheque) <> 0 then
    Rem Сбой печати, отменяем транзакцию
    MyServ.NFun (6004)
  End If
End If
MyServ.Clear
Set MyServer = Nothing
End Sub

Последовательность действий для выполнения возврата
Возврат покупки выполняется как отдельная транзакция, совершенно никак не связанная с транзакцией оплаты. 

Последовательность действий при возврате такая же, как и при оплате, только на шаге 3) необходимо вызвать функцию NFunc(4002).

Последовательность действий при закрытии смены
При закрытии смены необходимо вызвать функцию NFunc(6000).  Никаких входных параметров ей не требуется. Единственный выходной параметр – переменная “Cheque”, содержащая текст контрольной ленты с карточными операциями. Ее необходимо отправить на печать или сохранить в виде текстового файла.

Пример кода:

Sub Settlement()
Dim MyCheque As String
Dim MyServ As Server

Set MyServ = New Server

MyServ.Clear

If MyServ.NFun (6000) = 0 then 

  MyCheque           = MyServ.GParamString("Cheque")
  PrintCheque(MyCheque)
End If
MyServ.Clear
Set MyServer = Nothing
End Sub

Платежи с дополнительными реквизитами
Иногда возникает необходимость внести в карточные чеки некоторую дополнительную информацию, связанную с текущим платежом. Например, при продаже авиабилетов это могут быть номера проданных билетов, при оплате услуг связи – номер мобильного телефона, и т.д. 
Для внесения в чек дополнительных реквизитов платежа предназначена функция 7005 и специальный входной параметр с именем PayInfo. Пример платежа с указанием дополнительных реквизитов будет выглядеть так:

Sub main()
Dim MyCheque, MyClientCard, MyClientExpiryDate, MyAuthCode, MyTermNum, MyCardName As String
Dim MyServ As Server

Set MyServ = New Server

MyServ.Clear
MyServ.SParam "Amount", "123"
MyServ.NFun (4000)

MyTermNum          = MyServ.GParamString("TermNum")
MyClientCard       = MyServ.GParamString("ClientCard")
MyClientExpiryDate = MyServ.GParamString("ClientExpiryDate")
MyAuthCode         = MyServ.GParamString("AuthCode")
MyCardName         = MyServ.GParamString("CardName")

Rem   Проводим оформление билетов во внешней программе,
Rem   получаем их номера и вносим их в чек

MyServ.SParam "PayInfo", "5551234567,5551234568"
MyServ.NFun (7005)

MyCheque           = MyServ.GParamString("Cheque")
Rem Отправляем строку  MyCheque на принтер. В чеке уже есть номера билетов

MyServ.Clear
Set MyServer = Nothing
End Sub

Платеж с возможностью аварийной отмены
В некоторых случаях программное или аппаратное обеспечение ККМ не гарантирует распечатку карточных чеков и/или корректное закрытие операции в кассовой базе данных после проведения платежа по карте. 
Если операция не была корректно завершена в ККМ, ее необходимо отменить по карте, чтобы восстановить авторизованную сумму на счете карты. Для этого в библиотеке Сбербанка предусмотрен механизм отката и подтверждения транзакции. 
Сразу после успешного завершения платежа (например, функции 4000) транзакция попадает в «нормальное» состояние. В этом состоянии она попадет в контрольную ленту и будет обработана в конце дня. 
Если кассовое ПО использует механизм отката и подтверждения транзакции, то сразу после успешного завершения платежа оно должно вызвать функцию 6003. Функция 6003 переводит транзакцию из «нормального» в «неподтвержденное» состояние. В этом состоянии транзакция не включается в контрольную ленту, а при ближайшем сеансе связи с банком (или при закрытии дня) она автоматически отменяется, восстанавливая средства на карте клиента. 
После этого кассовое ПО приступает к печати чеков и закрытию операции. Если чеки успешно распечатаны и операция корректно закрыта, кассовое ПО должно вызвать функцию 6001. Эта функция переводит транзакцию в «подтвержденное» состояние. «Подтвержденное» состояние отличается от «нормального» только тем, что в «подтвержденном» состоянии аварийный откат платежа (например, с помощью функций 6003 и/или 6004) уже невозможен.
Если же кассовое ПО убедилось, что корректно завершить операцию по кассе невозможно, оно должно вызвать функцию 6004. Эта функция вызывает немедленную отмену платежа (с восстановлением средств на карте клиента) и переводит транзакцию в  «отмененное» состояние. Из «отмененного» состояния, как и из «подтвержденного», переход в другие состояния невозможен.
В случае, если в процессе закрытия операции кассовое ПО «зависло» и касса была перезагружена, транзакция остается в «неподтвержденном» состоянии. Это значит, что при любом следующем платеже (неважно, по этой же карте или по другой) она автоматически отменится.
Пример кода на Visual Basic:

Sub main()
Dim MyCheque, MyClientCard, MyClientExpiryDate, MyAuthCode, MyTermNum As String
Dim MyServ As Server

Set MyServ = New Server

MyServ.Clear
MyServ.SParam "Amount", "123"
If MyServ.NFun (4000) = 0 then 

  MyServ.NFun (6003)

  MyTermNum          = MyServ.GParamString("TermNum")
  MyClientCard       = MyServ.GParamString("ClientCard")
  MyClientExpiryDate = MyServ.GParamString("ClientExpiryDate")
  MyAuthCode         = MyServ.GParamString("AuthCode")

  MyCheque           = MyServ.GParamString("Cheque")

  If PrintCheque(MyCheque) = 0 then
    Rem Печать выполнена успешно, фиксируем транзакцию
    MyServ.NFun (6001)
  Else
    Rem Сбой печати, отменяем транзакцию
    MyServ.NFun (6004)
  End If
End If
MyServ.Clear
Set MyServer = Nothing
End Sub

Приложение. Используемые номера функций и имена параметров
Классы функций

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

Операции, которые библиотека позволяет выполнять с картами, можно условно разделить на финансовые (оплата, выдача наличных, возврат покупки, отмена операции, завершение расчета после предавторизации и т.д.), информационные (запрос остатка на счете, загрузка неотраженных средств, предавторизация и т.д.) и служебные (открытие операционного дня, закрытие операционного дня, инкассация и т.д.).

В таблице приведены классы функций:

Класс	Диапазон номеров функций	Описание	
0	0 – 999	- не используется	
1	1000 – 1999	- не используется	
2	2000 – 2999	- не используется	
3	3000 – 3999	- не используется	
4	4000 – 4999	Финансовые операции по картам 	
5	5000 – 5999	Информационные операции по картам	
6	6000 – 6999	Служебные операции по картам 	
7	7000 – 7999	Общие служебные операции	

Ниже приводится список функций текущей реализации.

Класс 4 — финансовые операции по картам 

Входные параметры:

 Число  Amount -сумма операции, если 0 - запрашивается библиотекой
 Строка Track2 -2-я дорожка карты, если пустая - считывается библиотекой
 Число  CardType -тип карты

Внимание! Когда это возможно, следует использовать считывание карты библиотекой.

По умолчанию заданы определены следующие возможные значения параметра CardType:
0 – выбор типа осуществляется из меню оператором,
1 – Visa,
2 – Mastercard,
3 – Maestro,
4 – VISA Electron
Могут быть определены дополнительные типы карт.

Функции данного класса могут принимать дополнительные параметры.

  строка RRN  -RRN для операции 4012
  Число  Currency  -код валюты, 
                    если 0 – запрашивается библиотекой
  Число  RecvCard -Номер карты получателя
  строка RecvValidDate -Срок действия карты получателя
  Число  Department – номер отдела (от 0 до 4).

Выходные параметры:

Число   AmountClear  - сумма операции без учета комиссии / скидки
Число   Amount - сумма операции с учетом комиссии / скидки
строка  CardName - название карты (Visa, Maestro и т.д.)
число   CardType - тип карты  
строка  TrxDate - дата операции  (ДД.ММ.ГГГГ)
строка  TrxTime - время операции (ЧЧ:ММ:СС)
строка  TermNum - номер терминала
строка  MerchNum - номер мерчанта
строка  AuthCode - код авторизации
строка  RRN -номер ссылки 
число   MerchantTSN  - номер транзакции в пакете терминала
число   MerchantBatchNum  - номер пакета терминала по магн.картам
строка  ClientCard - номер карты клиента
строка  ClientExpiryDate  - срок действия карты клиента 

Реализованы следующие функции класса 4.

Функция	Описание	
4000	Оплата покупки 	
4001	Выдача наличных	
4002	Возврат покупки	
4003	Отмена операции	
4004	Безналичный перевод при наличии карты клиента	
4005	Безналичный перевод при отсутствии карты клиента	
4006	Ввод слипа по картам Amex	
4007	Слип оплаты	
4008	Слип выдачи наличных	
4009	Предавторизация	
4010	Завершение расчета	
4011	Взнос наличных (предварительное зачисление)	
4012	Взнос наличных (подтверждение)	
4013	Погашение кредита	
4014	Перевод с карты на карту	
4015	Коммунальный платеж	
4016	Арест средств	
4017	Списание по аресту	
4018	Снятие (отмена) ареста	
4019	Выдача наличных без карты	
4020	Списание по требованию	
4021	Создание ПИН-кода	
4022	Смена ПИН-кода	
4023	Оплата услуг банка	
4024	Запись отпечатков пальцев на карту ПРО100	
4025	Установка оффлайн-лимита карты ПРО100	
4026	Распечатка истории операций по карте ПРО100	

Класс 5 — информационные операции по картам 

Входные параметры:

строка Track2 -2-я дорожка карты, если пустая - считывается библиотекой
Число  CardType -тип карты  

Внимание! Когда это возможно, следует использовать считывание карты библиотекой.

Параметр CardType такой же, как для класса 4.

Выходные параметры:

строка  CardName   - название карты
число   CardType   - тип карты  
строка  TrxDate    - дата операции  (ДД.ММ.ГГГГ)
строка  TrxTime    - время операции (ЧЧ:ММ:СС)
строка  TermNum    - номер терминала
строка  ClientCard - номер карты клиента
строка  ClientExpiryDate - срок действия карты клиента 

Функции данного класса могут возвращать дополнительные параметры. 

  строка  Hash     - Хэш–значение номера карты
  строка  CardData - Данные карты для функции 5002

Хэш–значение номера карты заполняется только при вызове функции 5002.

Реализованы следующие функции класса 5.

Функция	Описание	
5000	Запрос баланса	
5001	Разблокировка международных карт с чипом	
5002	Получение идентификатора карты	
5003	Блокировка карты	
5004	Считывание карты и проверка ПИН-кода	
Класс 6 — служебные операции по картам 

Входные параметры: НЕТ

Выходные параметры:

строка  TrxDate -дата операции  (ДД.ММ.ГГГГ)
строка  TrxTime -время операции (ЧЧ:ММ:СС)
строка  TermNum -номер терминала
строка  MerchNum	-номер мерчанта
число   MerchantBatchNum -номер пакета терминала
Реализованы следующие функции класса 6.

Функция	Описание	
6000	Итоги дня по картам с магнитной полосой 	
6002	Х-отчет по картам с магнитной полосой	

Дополнительные операции, предназначенные для аварийной отмены платежа в случае невозможности распечатки кассового чека (или при срочном отказе от операции по иным причинам):

Входные параметры:

Число   Amount   – сумма операции в копейках (для контроля)
строка  AuthCode – код авторизации (для контроля)

Выходные параметры: НЕТ

Функция	Описание	
6003	Установить транзакцию в «неподтвержденное» состояние	
6001	Установить транзакцию в «подтвержденное» состояние	
6004	Отменить транзакцию немедленно	

Класс 7 — общие служебные операции

Входные параметры:

строка  PayInfo – Дополнительные реквизиты платежа

Выходные параметры: НЕТ
 
Реализованы следующие функции класса 7.

Функция	Описание	
7000	Формирование текущего отчета по всем типам карт	
7001	Повторное формирование последнего чека	
7002	Печать старой контрольной ленты из резервной копии	
7005	Установить дополнительные реквизиты платежа (например, номера авиабилетов)