FCI Especificación tecnica para los H2H con el protocolo ISO8583_v1.4.pdf

Especificación tecnica para los clientes H2H con el protocolo ISO8583

Copyright 2009 ® Fullcarga S.A.

Plataforma Fullcarga Especificación técnica para los clientes H2H con el protocolo ISO8583

Autor: Departamento: Fecha:

David Soria Ortiz Departamento de tecnología. 16 de abril de 2009

Asunto:

Especificación Especificación técnica para los clientes H2H con el protocolo ISO8583

Versión:

v1.2

Histórico:

Ver.

Fecha

Autor

1.0

16/04/2009

David Soria Ortiz

1.1

10/12/2009

Beatriz Brun

Revisión

1.2

16/12/2009

David Soria Ortiz

Códigos de error

1.3

30/05/2011

David Soria Ortiz

1.4

01/08/2011

David Soria Ortiz

Documento: FCI Especificación tecnica para los H2H con el protocolo ISO8583_v1.4.docx Fecha: 29/08/2011

Notas

Se añaden los campos de respuesta para los productos internacionales

2/25 v1.2/r1

Índice 1.

Introducción ........................................................ 4

2.

Protocolo de comunicación ...................................... 5 2.2. Seguridad en los datos. ........................................... 6 2.3. Versión de protocolo .............................................. 7

3.

Operaciones. ....................................................... 8 3.1. Operación Echo. .................................................. 11 3.2. Operación de venta .............................................. 12 3.3. Operación de Devolución ........................................ 17 3.4. Operación de Consulta ........................................... 19 3.5. Operación de consulta de saldo. ................ ............... 21 3.6. Respuesta Errónea ................................................ 23

4.

Consulta en caso de operación demorada o fallo de comunicación 25


3/25 v1.2/r1

1. Introducción En este documento se describirá el comportamiento en cuanto a funcionalidades y protocolo de comunicación que deben implementar los clientes H2H que se comuniquen con la plataforma transaccional de Fullcarga.


4/25 v1.2/r1

2. Protocolo de comunicación El protocolo utilizado para la comunicación entre el cliente H2H y el Host de la plataforma transaccional se basa en el protocolo ISO-8583. Además del contenido de los campos ISO las tramas incluirán una cabecera que consta de: 

2 Bytes en binario para la longitud de la trama (sin incluir los 2 bytes de este campo)



5 Bytes para el TPDU (El valor para los H2H será, 0x00, 0x00, 0x00, 0x00, 0x00 representado en hexadecimal).

Por lo tanto las tablas quedarán como: LEN (2 bytes)

2.1.1.

TPDU (5 bytes)

DATA

Protocolo básico para las operaciones

El protocolo básico de las operaciones constará de una petición realizada por el cliente H2H, y una respuesta enviada por el HOST antes de un time-out de 60 segundos.

TPV

Host

Petición Máx. 60 seg.

Respuesta

Tamaño de la tramas. Se ha definido un máximo de 1KB para el tamaño de las tramas. Por lo que en caso de que una respuesta necesite más cantidad de información, será necesario dividir la respuesta en varias tramas.

División de la respuesta en varias tramas.


5/25 v1.2/r1

En todas las operaciones en las que la información a enviar por parte del host de Fullcarga en la respuesta sea superior a un 1KB será necesario enviar varias tramas. Para ello el host de Fullcarga indicará en las tramas de respuesta que es necesario que el cliente H2H espere más tramas. A cada trama de respuesta del host de Fullcarga le seguirá una nueva trama de petición del cliente H2H siempre dentro de la misma conexión. En este caso el time-out de espera del cliente H2H se volverá a contar desde 0 después de cada petición enviada por el cliente H2H. En la última trama a enviar el Host de Fullcarga indicará al cliente H2H que ya no es necesario que espere más tramas, cerrando así la conexión.

TPV

Host

Petición Máx. 60 seg.

Respuesta Petición

Máx. 60 seg.

Respuesta … Petición

Máx. 60 seg.

Respuesta

En las tramas de respuesta en las que el host de Fullcarga indica que son necesarias más tramas el campo PROCESS CODE (campo ISO nº 3) es

xxxxx1

mientras que en las que el Host de Fullcarga indica

que ya no es necesario esperar más tramas el campo PROCESS CODE es

xxxxx0.

2.2. Seguridad en los datos. Para proteger la información que se envía en las tramas el campo 60 (Privado, datos de la operación) se enviaran de forma encriptada.


6/25 v1.2/r1

La encriptación utilizada será 3DES ECB. Debido al algoritmo 3DES es necesario que cada campo encriptado se ajuste previamente a una longitud múltiplo de 8 bytes, para rellenar los campos hasta dicha longitud se utilizaran tantos byte 0x00 como sean necesarios. La clave se informará a cada cliente H2H mediante mail. Además las tramas incluyen un campo password que se enviará encriptado, que se asignará a cada H2H, para asegurar la identificación del cliente H2H. Por otra parte también se validará la IP desde la que se conecta el H2H.

2.3. Versión de protocolo Para poder permitir posteriores cambios en el protocolo, se incluye en las tramas un identificador de versión. Cada vez que se realicen cambios que afecten a los campos de la tramas, se cambiará el número de versión. La versión actual del protocolo para H2H es “02”.


7/25 v1.2/r1

3. Operaciones. A continuación se describen las diferentes operaciones que debe implementar el cliente H2H, así como las tramas de petición y respuesta correspondientes.

Tipos de datos de los campos Los campos del protocolo pueden ser de estos tipos: 

HEXA: Indica un campo binario en valor hexadecimal.



BCD: Indica un número codificado en BCD.



ASCII: Indica un campo alfanumérico de tamaño fijo codificado en ASCII.



LLV: Indica un campo alfanumérico de tamaño variable codificado en ASCII. En este caso los 2 primeros Bytes indican la longitud del campo puesta en BCD.



V: Indica un campo alfanumérico.



LBCD: Indica un número codificado en BDC de longitud variable. El primer byte es la longitud.

Importes Tanto en las tramas de petición como en las tramas de respuesta de las operaciones se pueden incluir diversos importes. En cualquier caso un campo que contenga información de importe se incluirá sin separadores de miles ni de decimales. De esta forma se asumirá que los últimos X dígitos del importe corresponden a los decimales. El número de decimales a utilizar se informará por parte de Fullcarga al cliente H2H.

Campos comunes de petición Todas las tramas de petición tendrán una serie de campos comunes, que se describen a continuación: Nº ISO

Campo

Tipo

Tamaño (BYTES)

MESSAGE LENGHT

HEXA

2

TPDU

HEXA

5

TYPE

BCD

2

BITMAP

HEXA

8

03

PROCCES CODE

BCD

3

11

STAN

BCD

3

12

TIME (HHMMSS)

BCD

3

13

DATE (MMDD)

BCD

2

41

TERMINAL ID

ASCII

8

62

PRIVATE (Campos de control) BCD

2

Longitud del campo


8/25 v1.2/r1

Versión del protocolo

ASCII

2

Password (Encriptado)

HEXA

8

TYPE Es en identificador ISO de tipo de operación.

PROCCES CODE Es el identificador que corresponde al tipo de operación que se esta ejecutando.

STAN Es el identificador correlativo de operación que tiene enviará el TPV en las peticiones. No es el identificador que se utilizará como referencia del cliente H2H para la conciliación.

TIME y DATE Son los campos de hora y fecha. En la petición indicarán la hora del TPV y en la respuesta la hora del Host.

TERMINAL ID Es el código de TPV asignado por la plataforma de Fullcarga.

VERSIÓN DE PROTOCOLO Indica la versión del protocolo de la plataforma de Fullcarga utilizada.

PASSWORD Es un password que se asignará a cada H2H.

Campos comunes de respuesta Las respuestas contendrán los mismos campos que se han enviado en la petición, además de los propios campos de respuesta. Por lo tanto a los campos comunes de la petición se añaden los siguientes que serán comunes a las respuestas: Nº ISO

Campo

Tipo

Tamaño (BYTES)

39

RESPONSE CODE

61

PRIVATE (Mensaje vendedor) - Longitud del campo - Mensaje

ASCII

2

BCD

2

V


9/25 v1.2/r1

RESPONSE CODE Este campo indicará el código de respuesta. Si es 00 la respuesta será correcta, si es 01 indicará que la operación se ha demorado, por lo que será necesario consultar el resultado mediante la operación de consulta ver el capitulo 4 Consulta en caso de operación demorada . En cualquier otro caso se tomará la operación como errónea. Tener en consideración estas transacciones como correctas hasta que las defina la operadora a través de la consulta.

MENSAJE VENDEDOR En este campo se podrá incluir un mensaje para el H2H, o bien dejarlo vacío.


10/25 v1.2/r1

3.1. Operación Echo. Esta es una operación especial que se utiliza únicamente para testear la conectividad entre el H2H y el Host. Por lo tanto no se enviara el campo Termina ID (41). El campo STAN no puede ser 00000000 por definición del protocolo ISO 8583, por lo que se enviará el último valor utilizado en la operación anterior. Si no se recibe respuesta al echo, no se deberán enviar transacciones de venta, devolución o consulta y se seguirán aviando echos hasta recibir respuesta cada 2 minutos.

3.1.1.

Trama de petición.

La trama de petición tendrá estos campos. Nº ISO

Campo

Tipo

Tamaño (BYTES)

MESSAGE LENGHT

HEXA

2

TPDU

HEXA

5

TYPE (0800)

BCD

2

BITMAP

HEXA

8

03

PROCCES CODE (990000)

BCD

3

11

STAN

BCD

3

12

TIME (HHMMSS)

BCD

3

13

DATE (MMDD)

BCD

2

Tipo

Tamaño

3.1.2.

Trama de respuesta.

La trama de respuesta tendrá estos campos. Nº ISO

Campo

(BYTES)

MESSAGE LENGHT

HEXA

2

TPDU

HEXA

5

TYPE (0810)

BCD

2

BITMAP

HEXA

8

03


BCD

3

11

STAN

BCD

3

12

TIME (HHMMSS)

BCD

3

13

DATE (MMDD)

BCD

2

39

RESPONSE CODE (00)

ASCII

2


11/25 v1.2/r1

3.2. Operación de venta A continuación la descripción de las tramas involucradas en la operación de venta.

3.2.1.

Trama de petición.

La trama de petición será la siguiente. Nº ISO

Campo

Tipo

Tamaño (BYTES)

MESSAGE LENGHT

HEXA

2

TPDU

HEXA

5

TYPE (0200)

BCD

2

BITMAP

HEXA

8

03


BCD

3

11

STAN

BCD

3

12

TIME (HHMMSS)

BCD

3

13

DATE (MMDD)

BCD

2

41

TERMINAL ID

ASCII

8

60

PRIVATE (Datos operación) (Encriptado)

<= 900

- Longitud del campo

BCD

2

- Código de producto

ASCII

8

- Usuario

ASCII

10

- REF H2H

LLV

- Lista de parámetros Número de parámetros Valor del parámetro

62

HEXA

1

LLV

PRIVATE (Campos de control) Longitud del campo

BCD

2


ASCII

2


HEXA

8

REF H2H Es la referencia que asigna el cliente H2H a la venta, y que se utilizará para la conciliación.


12/25 v1.2/r1

Usuario El usuario se enviará fijo de longitud 10 con espacios a la derecha si fuese necesario.

Lista de parámetros Para cada producto se definirán una lista de parámetros que se incluirán en la petición, ya que esta información depende del tipo de producto, y de la información requerida por la operadora. Esta información se envía adjunto en el anexo.


13/25 v1.2/r1

3.2.2.

Trama de respuesta.


Campo

Tipo

Tamaño (BYTES)

MESSAGE LENGHT

HEXA

2

TPDU

HEXA

5

TYPE (0210)

BCD

2

BITMAP

HEXA

8

03

PROCCES CODE (000100 ó 000101)

BCD

3

04

AMOUNT TRANS

BCD

6

06

AMOUNT DESTINO

BCD

6

11

STAN

BCD

3

12

TIME (HHMMSS)

BCD

3

13

DATE (MMDD)

BCD

2

37

REFERENCIA LOCAL

ASCII

12

39

RESPONSE CODE (00)

ASCII

2

41

TERMINAL ID

ASCII

8

51

MONEDA DESTINO

ASCII

3

48

PRIVATE (Referencia remota) BCD

2

- Longitud del campo - Referencia

60

V

PRIVATE (Datos operación) (Encriptado) Longitud del campo

<=900 BCD

2

HEXA

1

Lista de Parámetros

- Número de Parámetros - Valor de parámetro

61

LLV


BCD

2

V


14/25 v1.2/r1

AMOUNT DESTINO Y MONEDA DESTINO Estos campos indicarán el importe y la moneda en el que se ha hecho la operación en el país de destino del producto, en caso de que sea necesario informarlos.

Lista de parámetros Para cada producto se definirán una lista de parámetros que se incluirán en la respuesta, ya que esta información depende del tipo de producto, y de la información requerida por la operadora.


15/25 v1.2/r1

AMOUNT TRANS Es el importe de la venta. Como todos los importes ira sin separador de miles ni decimales, por lo que como decimales se tomaran tantos dígitos como se hayan definido.

REFERENCIA LOCAL (id de transacción de Fullcarga). Este campo se enviara rellenado de espacios en blanco a la izquierda del valor de la referencia. El H2H deberá eliminar estos espacios al leer este valor tanto para mostrarlo en el ticket, como para registrar la operación.

REFERENCIA REMOTA (id de transacción del operador). Este campo se enviara rellenado de espacios en blanco a la izquierda del valor de la referencia. El H2H deberá eliminar estos espacios al leer este valor tanto para mostrarlo en el ticket, como para registrar la operación.


16/25 v1.2/r1

3.3. Operación de Devolución A continuación la descripción de las tramas involucradas en la operación de devolución.

3.3.1.

Trama de petición.


Campo

Tipo

Tamaño (BYTES)

MESSAGE LENGHT

HEXA

2

TPDU

HEXA

5

TYPE (0200)

BCD

2

BITMAP

HEXA

8

03


BCD

3

11

STAN

BCD

3

12

TIME (HHMMSS)

BCD

3

13

DATE (MMDD)

BCD

2

41

TERMINAL ID

ASCII

8

60


<= 900


BCD

2


ASCII

8

- Usuario

ASCII

10

- REF H2H

LLV

- Lista de parámetros Número de parámetros Valor del parámetro

62

HEXA

1

LLV


BCD

2


ASCII

2


HEXA

8

REF H2H Es la referencia que asigna el cliente H2H a la devolución, y que se utilizará para la conciliación.


17/25 v1.2/r1

3.3.2.

Trama de respuesta.


Campo

Tipo

Tamaño (BYTES)

MESSAGE LENGHT

HEXA

2

TPDU

HEXA

5

TYPE (0210)

BCD

2

BITMAP

HEXA

8

03


BCD

3

04

AMOUNT TRANS

BCD

6

06

AMOUNT DESTINO

BCD

6

11

STAN

BCD

3

12

TIME (HHMMSS)

BCD

3

13

DATE (MMDD)

BCD

2

37

REFERENCIA LOCAL

ASCII

12

39

RESPONSE CODE (00)

ASCII

2

41

TERMINAL ID

ASCII

8

51

MONEDA DESTINO

ASCII

3

48


2


60

V


<=900 BCD

2

HEXA

1



61

LLV


BCD

2

V


18/25 v1.2/r1

3.4. Operación de Consulta A continuación la descripción de las tramas involucradas en la operación de consulta.

3.4.1.

Trama de petición.


Campo

Tipo

Tamaño (BYTES)

MESSAGE LENGHT

HEXA

2

TPDU

HEXA

5

TYPE (0800)

BCD

2

BITMAP

HEXA

8

03


BCD

3

11

STAN

BCD

3

12

TIME (HHMMSS)

BCD

3

13

DATE (MMDD)

BCD

2

41

TERMINAL ID

ASCII

8

60


<= 900


BCD

2


ASCII

8

- Usuario

ASCII

10

HEXA

1

- Lisa de parámetros Número de parámetros Valor del parámetro

62

LLV


BCD

2


ASCII

2


HEXA

8


19/25 v1.2/r1

3.4.2.

Trama de respuesta.


Campo

Tipo

Tamaño (BYTES)

MESSAGE LENGHT

HEXA

2

TPDU

HEXA

5

TYPE (0810)

BCD

2

BITMAP

HEXA

8

03


BCD

3

11

STAN

BCD

3

12

TIME (HHMMSS)

BCD

3

13

DATE (MMDD)

BCD

2

37

REFERENCIA LOCAL

ASCII

12

39

RESPONSE CODE (00)

ASCII

2

41

TERMINAL ID

ASCII

8

48


2


60

V


<=900 BCD

2

HEXA

1



61

LLV


BCD

2

V


20/25 v1.2/r1

3.5. Operación de consulta de saldo. Esta es la operación de consulta de saldo del cliente. Como resultado de esta operación se devolverá el saldo del cliente H2H en el campo ISO 4 de la respuesta.

3.5.1.

Trama de petición.


Campo

Tipo

Tamaño (BYTES)

MESSAGE LENGHT

HEXA

2

TPDU

HEXA

5

TYPE (0800)

BCD

2

BITMAP

HEXA

8

03


BCD

3

11

STAN

BCD

3

12

TIME (HHMMSS)

BCD

3

13

DATE (MMDD)

BCD

2

41

TERMINAL ID

ASCII

8

62


BCD

2


ASCII

2


HEXA

8


21/25 v1.2/r1

3.5.2.

Trama de respuesta.

La trama de respuesta será la siguiente. Nº ISO

Campo

Tipo

Tamaño (BYTES)

MESSAGE LENGHT

HEXA

2

TPDU

HEXA

5

TYPE (0810)

BCD

2

BITMAP

HEXA

8

03


BCD

3

04

AMOUNT TRAS (SALDO)

BCD

6

11

STAN

BCD

3

12

TIME (HHMMSS)

BCD

3

13

DATE (MMDD)

BCD

2

39

RESPONSE CODE (00)

ASCII

2

41

TERMINAL ID

ASCII

8

61

PRIVATE (Mensaje vendedor) BCD

2

- Longitud del campo - Mensaje

V

AMOUNT TRANS (SALDO) Es el saldo del cliente H2H. Como todos los importes ira sin separador de miles ni decimales, por lo que como decimales se tomaran tantos dígitos como se hayan definido.


22/25 v1.2/r1

3.6. Respuesta Errónea En caso de error en cualquier operación el Host enviará una trama indicando el error. Los campos de la trama serán: Nº ISO

Campo

Tipo

Tamaño (BYTES)

MESSAGE LENGHT

HEXA

2

TPDU

HEXA

5

TYPE (XX10 según de la petición)

BCD

2

BITMAP

HEXA

8

03

PROCCES CODE (igual a la petición)

BCD

3

11

STAN

BCD

3

12

TIME (HHMMSS)

BCD

3

13

DATE (MMDD)

BCD

2

37

REFERENCIA LOCAL

ASCII

12

39

RESPONSE CODE (Distinto de 00 y de 01)

ASCII

2

41

TERMINAL ID

ASCII

8

48


2


60

V

PRIVATE (Datos operación) Longitud del campo

<=900 BCD

2

HEXA

1



LLV

En caso error, el campo RESPONDE CODE indicará sólo que la operación es errónea, la descripción del error se incluirá en el primer parámetro de la Lista de parámetros del campo 60. En esta respuesta no se enviará el campo 60 encriptado.

La plataforma de Fullcarga enviará dos tipos de mensajes de error dependiendo de si el error se ha detectado en las validaciones de los datos o en la propia operación de la plataforma de Fullcarga, o bien si el error es enviado por la propia operadora. En caso de que el error sea enviado por la propia operadora el mensaje empezará siempre por “NAKGW”.


23/25 v1.2/r1

La lista de los diferentes errores internos en la plataforma de Fullcarga es la siguiente:

Errores

HS0500 El sistema esta ocupado intentelo mas tarde HS0502 El sistema esta ocupado intentelo mas tarde HS0505 La operacion no se ha podido realizar HS0506 Ha habido problemas con la operacion, consulte el estado de la misma HS1000 El POS no esta activo o no existe HS1001 La operacion no es valida HS1002 El cliente no esta activo o no existe HS1003 Operacion no esperada HS1004 La version utilizada no es valida HS1005 La diferencia horaria no permite la operacion HS1006 El tipo de comunicacion no es valido HS1008 El importe no es un valor permitido HS1009 El importe esta fuera del rango minimo-maximo HS1010 Error en la trama de confirmacion HS1012 Error en la sincronizacion HS1014 La referencia no existe HS1021 El telefono es incorrecto HS1026 El estado del producto no permite operar HS1027 El producto no esta habilitado HS1031 La trama es incorrecta HS1032 El POS no tiene mensajes pendientes HS1033 El tipo de aviso no es valido HS1050 Los datos del cliente no son correctos HS2002 No existen pines disponibles en este momento HS3005 No dispone de saldo suficiente para operar HS4003 La referencia de la venta no es valida HS4005 Error en la validacion HS4006 La venta todavia esta en proceso, consulte cal l center HS4007 La venta esta anulada


24/25 v1.2/r1

4. Consulta en caso de operación demorada o fallo de comunicación En el caso de que en una operación de Venta ó Devolución no llegue al respuesta al cliente, o la plataforma responda al cliente una respuesta con el campo RESPONSE CODE con valor ‘01’ (Operación demorada), el cliente deberá enviar una petición de consulta (Ver apartado 3.4 Operación de Consulta) utilizando el producto CONSULIVR, para consultar en qué estado se ha quedado la operación. En el IVR la consulta ser realizará 2 veces antes de rechazar la venta.

Este producto tiene como único parámetro para la operación de consulta la referencia que el cliente ha enviado en la venta en el campo REF IVR.

Los parámetros de respuesta incluidos en el campo 60 serán los siguientes: 1.- CODIGO DE PRODUCTO Igual que en la petición

2.- RESULTADO OK: Indicará que la operación es correcta. En este caso el campo 37 tendrá la referencia para la operación de la plataforma Fullcarga. KO: Indicará que la operación no ha sido correcta: bien porque no se ha recibido la petición; bien porque ha habido algún fallo en las validaciones; bien porque la operadora ha indicado un error para la operación o bien porque en el caso de una venta se haya podido anular. PE: Indicará que la operación todavía sigue pendiente, por lo que se tendrá que seguir consultando. Si la operación ha pasado las validaciones previas en la plataforma de Fullcarga y se ha podido registrar, el campo 37 también incluirá la referencia de la operación.

3.- INSTRUCCIONES Incluirá un mensaje que indicará el motivo por el q ue la operación consultada no fue correcta.

4.- MSJ CLIENTE Incluirá cualquier otro tipo de mensaje para el cliente.


25/25 v1.2/r1

FCI Especificación tecnica para los H2H con el protocolo ISO8583_v1.4.pdf

Recommend Documents