Протокол взаимодействия терминального ПО и хоста Банка

Назначение

Настоящий документ представляет собой описание протокола взаимодействия терминального ПО (POS-терминалов) с эквайринговым хостом Банка согласно ISO 8583. Данный протокол совместим с протоколом SMARTVISTA версии 1.83A.

Описание протокола

Сообщение ISO 8583 состоит из следующих частей:

MTI	BIT MAP	DATA ELEMENTS
4 bytes	8-16 bytes binary	Variable

• MTI (Message Transaction ID) – это уникальный идентификатор, используемый для отслеживания транзакций сообщений при передаче данных по протоколу TCP/IP.
• BIT MAP - Битовая маска. Битовая маска определяет набор полей, которые должны присутствовать или отсутствовать в сообщении.
• DATA ELEMENTS – тело сообщения. Тело сообщения представляет собой блок данных, составленный путем конкатенации полей сообщения, заданных битовой маской.

Поддерживаемые типы сообщений MTI Message Type Indicator (MTI) — 4-значное числовое поле, которое определяет высокоуровневую функцию сообщения. Индикатор типа сообщения включает в себя версию стандарта ISO 8583, класс сообщения, функцию сообщения и источник сообщения, описанные ниже:

• 0xxx -> версия стандарта ISO 8583
• x1xx -> класс сообщения
• xx1x -> функция сообщения
• xxx0 -> кто начал взаимодействие Первая позиция MTI определяет версию стандарта ISO 8583, используемую для передачи сообщения. Текущая реализация протокола взаимодействия поддерживает оригинальную версию стандарта ISO 8583 от 1987 года. Вторая позиция MTI определяет общую цель сообщения:
• (1) Authorization Message - Проверяет доступность средств, получает одобрение, но проведение по счёту не производится.
• (2) Financial Message - Проверяет доступность средств, получает одобрение, производится проводка по счёту.
• (4) Reversal Message - Отменяет действие предыдущей авторизации.
• (5) Reconciliation Message - Используется для сверки итогов.
• (6) Administrative Message - Используется для передачи сообщений об ошибках.
• (8) Используется посылки эхо-тестов и для других функций сети. Третья позиция Индикатора сообщения (MTI) определяет функцию сообщения и способ его обработки в системе. Перечень поддерживаемых сообщений приведен в таблице ниже.

• MTI	Описание
  0200	Financial Transaction Request
  0210	Financial Transaction Response
  0400	Reversal Request
  0410	Reversal Response
  0520	Reconciliation Request
  0520	Reconciliation Response

Заполнение сообщений

Обозначения форматат полей

Обозначение	Описание
a	Символы латинского алфавита A–Z и a–z
n	Числовые символы 0–9
as	Символы латинского алфавита A–Z, a–z и специальные символы*, включая пробел
ns	Числовые символы 0-9 и специальные символы*, включая пробел
an	Алфавитные и цифровые символы
ans	Алфавитные, цифровые и специальные символы*, включая пробел
anp	Алфавитные, цифровые и символ пробела
b	Двоичные данные байтами по 8 бит. Например, "b4" обозначает двоичное поле с фиксированной длиной 4 байт
N	Дескриптор длины поля фиксированной длины. Например, "a8" — символьное поле длиной 8 байт
LL	2-х байтный дескриптор поля переменной длины (макс. 99 байт)
LLL	3-х байтный дескриптор поля переменной длины (макс. 999 байт)
VAR	Поле данных переменной длины
z	Tracks 2 в соответствии со стандартом ISO4909 и ISO7813
Bit-Map	8 байт (64 бит) в бинарном формате. Каждый бит означает наличие (1) или отсутствие (0) элемента данных
..19	Переменная длина до 19 символов

Field 1: Secondary Bit-Map

Формат Bit-Map

Описание Данное поле представляет собой битовую карту, указывающую на наличие или отсутствие полей во вторичной части сообщения, а именно биты 65-128. Это поле должно присутствовать только в том случае, если в сообщении есть хотя бы одно поле из вторичного диапазона.

Field 2: Primary Account Number (PAN)

Формат n.. 19

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

Field 3: Processing Code

Формат n 6

Описание Первые два байта содержат идентификатор типа транзакции. Остальные байты всегда «0000». В таблице ниже представлен перечень допустимых значений.

Processing Code (bytes 1 and 2)	Описание
00	Purchase
13	Purchase with EC
20	Refund
23	Refund with EC
99	Network Management

Field 4: Amount, Transaction

Формат n 12

Описание Сумма операции, выраженная в валюте операции, которая указана в поле 049. Для операций в рублях (поле 049 = 643) сумма должна быть представлена в минимальных единицах, т.е. в копейках.

Field 7: Transmission Date and Time

Формат n 10

Описание В поле 007 указываются дата и время инициирования сообщения. Содержание поля 007 должно быть представлено в формате: "MMDDhhmmss", где:

• MM – месяц (01-12),

• DD – день (01-31),

• hh – часы (00-23),

• mm – минуты (00- 59),

• ss – секунды (00-59).

  Значение времени должно быть указано в часовой зоне GMT (Greenwich Mean Time).

Field 11: System Trace Audit Number (STAN)

Формат n 6

Описание Содержит номер, который присваивается инициатором операции. Необходимо поддерживать уникальные значения STAN для операций, инициируемых терминалом в течение 24 часов. Поле 011 не должно отсутствовать и не должно быть заполнено только нулями или пробела

Field 12: Time, Local Transaction

Формат n 12

Описание Локальное время в месте совершения операции. Время должно быть сформировано терминалом в момент начала операции и представлено в поле в формате «YYMMDDhhmmss», где:

• YY – год,
• MM – месяц (01-12),
• DD – день (01-31),
• hh – часы,
• mm – минуты,
• ss – секунды.

Field 15: Date, Settlement

Формат n 6

Описание Дата расчетов в формате «YYMMDD», где:

• YY – год,
• MM – месяц (01-12),
• DD – день (01-31).

Field 22: Point of Service Entry Mode

Формат n 3

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

Позиция 1-2: Тип ввода PAN карты

Код	Описание
00	Unknown (Способ ввода PAN неизвестен)
01	Manual (key entry) (Ручной способ ввода PAN)
02	Magnetic stripe read (PAN считан с магнитной полосы)
05	Integrated circuit card read; card data reliable (PAN с чипа через контактный интерфейс)
06	Track 1 Read
07	Contactless using chip rules (PAN с чипа через бесконтактный интерфейс)
71	Card present, magnetic stripe cannot be read (key-entered)
91	Contactless using magnetic stripe data rules (PAN магнитной полосы через бесконтактный интерфейс)

Позиция 3: Признак аутентификации

Код	Описание
0	Unknown (Неизвестно / не определено)
1	PIN
2	Signature (Подпись)
6	Используется для ручного ввода данных карты

Field 24: Function Code

Формат n 3

Описание Цель сообщения, возможные значения:

• 200 - Original financial request
• 400 - Reversal, transaction did not complete as approved
• 504 - Request for reconciliation totals

Field 25: Service Condition Code

Формат n 2

Описание Содержит код, определяющий условия сделки в торговой точке или точке обслуживания:

• 00 – attendant terminal
• 01 - cardholder not present
• 02 – unattendant terminal
• 08 - biometric identification

Field 35: Track 2 Data

Формат Llvar z.. 37

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

Field 37: Retrieval Reference Number

Формат anp 12

Описание Поле 037 содержит уникальный идентификатор банковской транзакции, который назначается при инициализации платежа.

Field 38: Approval Code

Формат anp 6

Описание Поле 038 содержит код авторизации, который присваивается Эмитентом в случае одобрения операции.

Field 39: Response Code

Формат n 3

Описание Содержит код, который определяет ответ на запрос. На терминал уходит только Code ответа. В столбце Log Message указан текст в логах системы Т-Банка.

Таблица кодов

Code	Log Message
000	APPROVED
001	CONTACT ISSUING BANK
002	REJECTED
003	APPROVED
005	SYSTEM ERROR
005	Error while generate mac response
020	APPROVED
095	RECONCILIATION MISMATCH
095	Need reconcile for device
100	NOT SERVICED
101	CARD EXPIRED
102	SUSPICION OF FRAUD
103	CONTACT BANK
103	EC Invalid status
104	CARD HAS RESTRICTIONS
104	Invalid extId
104	Invalid extOperationID
105	CONTACT BANK
105	extId does not match the extId of the original payment
106	EXCEEDED MAXIMUM NUMBER OF INCORRECT PIN ATTEMPTS
107	PLEASE CONTACT THE ISSUER
108	CONTACT BANK FOR AUTHORIZATION
109	UNKNOWN SERVICE POINT
109	Terminal blocked
110	INVALID TRANSACTION AMOUNT
110	Amount of the cancel exceeds the balance of the operation
110	Amount of the cancel exceeds the transaction
111	UNKNOWN CARD
111	Card number for cancel does not match original transaction card number
112	PIN IS MISSING IN REQUEST
113	UNACCEPTABLE COMMISSION
114	INVALID CARDHOLDER ACCOUNT NUMBER
115	REQUESTED TRANSACTION TYPE NOT SUPPORTED
116	TRANSACTION AMOUNT EXCEEDS CARD LIMIT
117	INVALID PIN
118	TRACK2 DATA IS MISSING IN REQUEST
119	TRANSACTION PROHIBITED FOR CARDHOLDER
120	TRANSACTION PROHIBITED FOR TERMINAL
120	PayService.execution forbidden
120	Final authorization amount error
121	ACTIVITY LIMIT EXCEEDED (AMOUNT)
122	SECURITY VIOLATION
123	ACTIVITY LIMIT EXCEEDED (NUMBER OF TRANSACTIONS)
123	Transaction limit exceeded
124	LAW VIOLATION
125	INVALID CARD
126	PIN KEYS DO NOT MATCH
127	INVALID PIN LENGTH
128	PIN KEYS NOT ACTIVATED
129	SUSPICION THAT THE CARD IS COUNTERFEIT
130	PayService.execution forbidden, token or parameters invalid
180	CASH WITHDRAWAL WITH THIS CARD IS PROHIBITED
181	CURRENCY CONVERSION FOR CASH WITHDRAWAL IS PROHIBITED
182	CARD PAYMENT IS PROHIBITED
183	CURRENCY CONVERSION FOR CARD PAYMENT IS PROHIBITED
184	ELECTRONIC AUTHORIZATION WITH THIS CARD IS PROHIBITED
185	MANUAL AUTHORIZATION WITH THIS CARD IS PROHIBITED
186	INVALID CARD USAGE AREA
187	ISSUER IS BLOCKED
188	ISSUER ACTIVITY LIMIT EXCEEDED
189	ACQUIRER IS BLOCKED
190	CARD TEMPORARILY BLOCKED
191	INVALID CARD TYPE SELECTED
196	CARD IS BLOCKED
197	RESPONSE TIMEOUT
197	Timeout after the operation time expires
198	SYSTEM ERROR
199	SYSTEM FAILURE
200	RETAIN: NOT SERVICED
201	RETAIN: EXPIRED
202	RETAIN: COUNTERFEIT
203	RETAIN: CONTACT ACQUIRER
204	RETAIN: RESTRICTIONS
205	RETAIN: CONTACT ACQUIRER SECURITY
206	RETAIN: PIN ENTRY ATTEMPTS EXCEEDED
207	RETAIN: SPECIAL CONDITIONS
208	RETAIN: LOST
209	RETAIN: STOLEN
210	RETAIN: COUNTERFEIT
285	RETAIN
300	SUCCESSFUL
302	RECORD NOT FOUND
306	FAILED
306	The terminal of the original operation is unlinked
308	DUPLICATE, TRANSACTION DECLINED
308	Multiple original operations found for the current search criteria
380	SYSTEM ERROR
381	NO CONTROLLED PARTICIPANT FOUND
383	PARTICIPANT LIMIT NOT FOUND
384	NO PARTICIPANT FOUND FOR THE GIVEN ACCOUNT
385	BASE CARD PAYMENT LIMIT NOT FOUND
386	CARD PAYMENT LIMIT NOT FOUND
387	A8, A9 MESSAGE TYPE IS MULTICURRENCY
388	INVALID DATE OF THE LAST TRANSACTION FILE
389	INVALID STATUS OF THE RECEIVED LIMIT
390	INVALID VALUE OF THE GLOBAL LIMIT FLAG
485	ORIGINAL TRANSACTION NOT FOUND
486	DOES NOT MATCH ORIGINAL TRANSACTION
487	NO ACTION WAS TAKEN ON THE CANCELED MESSAGE
487	No action was taken on the canceled message
490	CANCELLATION PROHIBITED (REASON NOT SPECIFIED)
490	The cancellation operation with manual card entry is prohibited for regular purchases
800	NO CONNECTION TO SERVICE PROVIDER
801	TIMEOUT. TRANSACTION NOT COMPLETED
802	PHONE NUMBER NOT FOUND
803	PAYMENT PROHIBITED BY HOME OPERATOR
803	PAYMENT PROHIBITED. PLEASE CONTACT YOUR ISSUING BANK
803	Payment prohibited. Please, contact with bank-issuer
804	INVALID TERMINAL REGISTRATION
805	Card bin is blocked, contact the issuing bank
806	PAYMENT PROHIBITED FOR TECHNICAL REASONS
806	Payment prohibited by technical reasons
902	INVALID TRANSACTION
902	extRequestId in field 48 should be empty for pre-authorization
903	PLEASE REPEAT TRANSACTION
904	INVALID MESSAGE FORMAT
904	Invalid message format
905	ACQUIRER NOT SUPPORTED BY SWITCH
906	CUTOVER PROCESS IN PROGRESS
907	ISSUER OR SWITCH SYSTEM IS UNAVAILABLE
908	MESSAGE RECIPIENT UNKNOWN
909	SYSTEM FAILURE. TRANSACTION NOT COMPLETED
909	Update message of addition date failed
909	Operation canceled
910	ISSUER IS IN SIGNED OFF STATE
911	ISSUER TIMEOUT
912	ISSUER UNAVAILABLE
913	DUPLICATE, TRANSACTION DECLINED
914	ORIGINAL TRANSACTION NOT FOUND
914	Missing previous operation
915	ERROR DURING CUTOVER PROCESS
916	INVALID MAC
917	INVALID MAC KEY
918	COMMUNICATION KEYS MISSING
918	CRYPTOGRAPHIC KEY ERROR
920	SOFTWARE OR HARDWARE ERROR
921	SOFTWARE OR HARDWARE ERROR
922	MESSAGE NUMBER OUT OF SEQUENCE
923	REQUEST IS BEING PROCESSED
927	FINGERPRINTS DO NOT MATCH
940	SYSTEM ERROR
949	AUTHORIZATION DENIED - CO-BRAND CARD

Field 41: Card Acceptor Terminal Identification

Формат n 8

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

Field 42: Card Acceptor Identification Code

Формат ans 15

Описание Идентификатор торговой точки, соответствует MID.

Field 48: Additional Data

Формат lllvar ans 999, формат тегов: 3 байта для обозначения тега + 3 байта для обозначения длины тега + содержание тега.

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

Тег	Назначение
001	UUID платежной сессии
002	Уникальный Межбанковский Идентификатор Транзакции (УМИТ). Генерируется платежным центром. Это UUID+доп.данные с применением шифрования HMAC
003	Платежная система операции. Прим.: MIR, VISA, MASTERCARD, UNION_PAY
004	тэг зарезервирован. Не используется
031	Поддерживаемый формат ключа на терминале: «VARIANT», «KEYBLOCK»
076	Basket ID. Используется только для операций с использованием ЭС
081	Идентификатор процесса определения данных карты Контакта (extId). Используется только для операций с использованием лицевой биометрии
090	Наименование ЮЛ (рус.). Только в ответе
091	Адрес торговой точки.
093	Наименование ЮЛ (англ.). Только в ответе
096	Имя держателя карты
097B	Внешний IP-адрес softpos-устройства (softPos)
097C	Платежный JWT-токен (softPos)
098	Поддерживаемый формат PIN блока на терминале: «2DES», «AES»
169	ext-request-id оригинальной операции
170	tid терминала транзакции
175	stan оригинальной транзакции (для отмены без карты)
176	Дата-время оригинальной транзакции (для отмены без карты)

Field 49: Currency Code, Transaction

Формат n 3

Описание Поле содержит трехзначный цифровой код валюты операции согласно стандарту ISO-4217. В указанной валюте выражены суммы, приводимые в поле 004.

Field 52: PIN Block

Формат b 8

Описание Используется для идентификации держателя карты в точке обслуживания. Для устройств с подключенным пин-падом это поле должно содержать информацию о PIN-коде.

Field 53: Security Related Control Information

Формат llvar b .. 16

Описание Содержит рабочие (TPK,TAK) или мастер (TMK) ключ.

Field 54: Additional Amounts

Формат an.. 120

Описание Используется для указания суммы ЭС. Заполнение обязательно для операций с использованием ЭС.

Позиции	Описание	Допустимые значения	Пример
1-2	Тип счета	00 Default 10 Saving 20 Cheque 30 Credit	00
3-4	Тип баланса	01 Ledger 02 Available 03 Electronic Certificate amount	03
5-7	Код валюты (ISO 4217)	3-значный код валюты (например: 643 — RUB)	643
8	Знак суммы	D (дебет) C (кредит)	D
9-20	Сумма (n12)	12-значное числовое поле (дополняется нулями слева)	00000000034

Field 55: EMV Data

Формат LLLVAR b ... 255

Описание Поле содержит блок данных, передаваемый в случае выполнения операции с использованием микропроцессорной (чиповой) карты. Блок данных включает в себя последовательность элементов, представленных в формате BER-TLV (Basic Encoding Rules - Tag Length Value) согласно стандарту ISO/IEC 8825. Необходимо учитывать специфику EMV в зависимости от платежной системы (см. Приложение). В таблице ниже приведен перечень элементов, которые могут быть включены в поле 055. На поле действует регулярное выражение \"^[0-9A-F]+$\

Тег	Название	Описание
4F	Application Identifier (AID)	Идентификатор приложения
57	Track 2 Equivalent Data	Эквивалентные данные дорожки 2
5F24	Application Expiration Date	Срок действия приложения
5F2A	Transaction Currency Code	Код валюты транзакции
5F34	Application PAN sequence number	Порядковый номер основного номера счета приложения
82	Application Interchange Profile	Профиль взаимодействия приложения
95	Terminal Verification Result (TVR)	Результат проверки терминала
9A	Transaction Date	Дата транзакции
9B	Transaction Status Information	Информация о статусе транзакции
9C	Transaction Type	Тип транзакции
9F02	Amount, Authorized	Авторизованная сумма
9F03	Amount, Other	Дополнительная сумма
9F08	Application Version Number	Версия приложения
9F09	Terminal Application Version Number	Версия приложения терминала
9F10	Issuer Application Data (IAD)	Данные приложения эмитента
9F1A	Terminal Country Code	Код страны терминала
9F26	Application Cryptogram (AC)	Криптограмма приложения
9F27	Cryptogram Information Data	Информационные данные криптограммы
9F34	Cardholder Verification Method (CVM) Results	Результаты проверки держателя карты
9F36	Application Transaction Counter (ATC)	Счетчик транзакций приложения
9F37	Unpredictable Number	Непредсказуемое число
84	Dedicated File Name	Имя выделенного файла
9F1E	Interface Device Serial Number	Серийный номер интерфейсного устройства
9F33	Terminal Capabilities	Возможности терминала
9F35	Terminal Type	Тип терминала
9F40	Additional Terminal Capabilities	Дополнительные возможности терминала
9F4E	Merchant Name and Location	Название и местоположение мерчанта
9F41	Transaction Sequence Number	Порядковый номер транзакции
9F4C	ICC Dynamic Number	Динамический номер ICC
9F53	Transaction Category Code	Код категории транзакции
9F63	Application Transaction Counter	Счетчик транзакций приложения
9F66	Terminal Transaction Qualifiers	Квалификаторы транзакции терминала
9F6E	Form Factor Indicator	Индикатор форм-фактора
DF31	Issuer Script Results	Результаты скрипта эмитента

Field 61: AES PIN Block

Формат lllvar ans 999

Описание Это поле используется для передачи PIN Block под алгоритмом шифрования AES

Field 63: PrivateData

Формат lllvar ans 999, формат тегов: 3 байта для обозначения тега + 3 байта для обозначения длины тега + содержание тега.

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

Тег	Содержание тега
097	Кей-блок ключ
	• Длина: 2DES или AES (для softPos)
	• Алгоритм шифрования: 3DES или AES (для softPos)
	• Формат: TR-31
	- Key Version ID: B или D (только для AES алгоритма в softPos)

Field 64: MAC

Формат ans …999

Описание Содержит MAC (Message Authentication Code) подпись в соответствии с ISO 9797-1. Вычисляется от вычисленного хеша от всего сообщения, не включая длину сообщения. В случае если MAC не верный в ответе в поле 039 будет код ответа 005.

Приложение

Обязательность заполнения тегов 55-ого поля в разрезе ПС

TAG	Название	Описание	МИР	UnionPay	MasterCard	VISA
5F2A	Transaction Currency Code	Код валюты транзакции (ISO 4217)	Да	Да	Да	Да
5F34	Application PAN Sequence Number	Порядковый номер основного номера счета	Да*	Да*	Да*	Да*
82	Application Interchange Profile	Возможности карты	Да	Да	Да	Да
84	Dedicated File (DF) Name	Имя выделенного файла (ISO/IEC 7816-4)	Да	Опциональный	Да	Опциональный
95	Terminal Verification Results	Результаты проверки терминала	Да	Да	Да	Да
9A	Transaction Date	Дата транзакции	Да	Да	Да	Да
9C	Transaction Type	Тип транзакции (первые 2 цифры кода ISO 8583:1987)	Да	Да	Да	Да
9F02	Amount Authorized	Авторизованная сумма (без корректировок)	Да	Да	Да	Да
9F03	Amount, Other (Numeric)	Дополнительная сумма (например, кэшбэк)	Да	Да	Да	Условно обязательный.При операции с кэшбэком
9F10	Issuer Application Data	Данные приложения эмитента	Да	Да	Да	Да
9F1A	Terminal Country Code	Код страны терминала (ISO 3166)	Да	Да	Да	Да
9F1E	IFD Serial Number	Серийный номер интерфейсного устройства	Нет	Условно обязательный.Если идентификатор не был передан в других полях авторизационного запроса	Нет	Нет
9F26	Application Cryptogram	Криптограмма приложения	Да	Да	Да	Да
9F27	Cryptogram Information Data	Тип криптограммы и действия терминала	Да	Да	Да	Да
9F33	Terminal Capabilities	Возможности терминала	Нет	Да	Нет	Да
9F34	CVM Results	Результаты проверки держателя карты	Да	Опциональный	Да	Опциональный
9F36	Application Transaction Counter (ATC)	Счетчик транзакций приложения	Да	Да	Да	Да
9F37	Unpredictable Number	Непредсказуемое число	Да	Да	Да	Да
DF31	Issuer Script Results	Скрипт эмитента (только UPI)	Нет	Условно обязательный.При отмене обязательный.	Нет	Нет
9F63	Card Product Identification Information	Идентификация продукта карты (только UPI)	Нет	Условно обязательный.Если при чтении чипа этот тег вернулся картой.	Нет	Нет
9F6E	Third Party Data	Данные третьих сторон (тип устройства и др.)	Нет	Нет	Нет	Условно обязательный.Этот тег обязательно должен быть отправлен при операции по бесконтакту.

Условные обозначения:

• Да* — обязательный, если карта передала данные