Visión general – Servicio de Autorización de Pago

Actualmente, Diners Club, como parte de los servicios que presta a varias pasarelas (botones) de pago, expone una serie de servicios REST que permiten realiza transacciones financieras, específicamente transacciones con tarjetas de crédito y débito, de manera segura y eficiente.

Estos servicios incluyen funcionalidades clave como: - Consulta de llave RSA pública - Generación de OTP (One-Time Password) - Validación de OTP - Consulta de tipos de crédito - Cálculo de intereses - Autorización de consumo

Se describe las especificaciones técnicas necesarias para la integración de los servicios REST de Diners Club con pasarelas de pago, proporcionando a los desarrolladores la información detallada sobre los endpoints, los métodos HTTP, las estructuras de solicitud y respuesta, y la encriptación de datos, que será una prioridad en esta integración.

El objetivo principal es garantizar que las pasarelas de pago, como Place To Pay, puedan consumir estos servicios de forma segura, cumpliendo con altos estándares de seguridad, confiabilidad y eficiencia en las transacciones con tarjetas de crédito y débito.

Definiciones y Abreviaturas

- MICROSERVICIO: Servicio independiente y operativo que forma parte de una arquitectura de software distribuida. Cada microservicio maneja una función específica y se comunica con otros servicios a través de APIs, permitiendo escalabilidad y mantenimiento ágil. - API: Interfaz de Programación de Aplicaciones (Application Programming Interface). Las APIs permiten que los microservicios se comuniquen entre sí y con otros sistemas, facilitando la integración y la interoperabilidad. - REST: Transferencia de Estado Representacional (Representational State Transfer). Es un estilo arquitectónico utilizado por microservicios para la comunicación a través de HTTP, aprovechando los métodos estándar como GET, POST, PUT y DELETE para operar sobre los recursos. - JSON: Notación de Objetos de JavaScript (JavaScript Object Notation). Formato de intercambio de datos ampliamente utilizado en microservicios para transmitir información entre servicios debido a su simplicidad y legibilidad. - CIFRADO: Proceso de transformar datos en un formato ilegible para proteger su confidencialidad durante la transmisión o almacenamiento. - [ ] Cifrado Simétrico: Tipo de cifrado en el que la misma clave se usa tanto para encriptar como para desencriptar los datos. - [ ] Cifrado Asimétrico: Tipo de cifrado que utiliza un par de claves (pública y privada); la clave pública cifra los datos y la clave privada los descifra. - AES: Estándar de cifrado avanzado (Advanced Encryption Standard), utilizado ampliamente para proteger datos mediante cifrado simétrico. - AES-256 modo GCM: Algoritmo de cifrado simétrico que proporciona autenticación integrada mediante un MAC, permite cifrado paralelo. Utiliza un vector de inicialización (IV) único, incluso si los bloques de datos son idénticos, el resultado cifrado será diferente. Teniendo alta resistencia a ataques de manipulación y análisis de patrones. - RSA: Algoritmo de cifrado asimétrico utilizado para proteger información mediante claves públicas y privadas.

Descripción General de los Servicios

- Consultar Token: Los servicios se encuentran expuestos a internet asegurados mediante OAUTH, por lo que en una primera instancia se requeriría generar un token. Adicional para la encriptación de datos sensibles se requerirá un intercambio de llaves para el cifrado AES256/GCM. - [ ] Method: POST - [ ] Content-Type: application/json - Autorización de consumo: Este servicio autoriza o rechaza el consumo en el comercio basado en la tarjeta, el monto, el tipo de crédito y otros datos de entrada proporcionados. - [ ] Method: POST, - [ ] Content-Type: application/json

Campos del servicio de autorización de consumo

Campo codigoSeguridad Destinado a agrupar una serie de subcampos en formato trama, tiene la estructura y orden son descritos en las siguientes estructuras.

Estructura Principal. - formado por la categoría, código de marca y código de subcomercio Los datos de la categoría de la transacción o TCC tienen los siguientes valores posibles.

TCC	Descripción
Space	A value of space in place of a valid TCC requests that the Authorization Platform perform the TCC assignment.
A	Auto/Vehicle Rental
C	Cash Disbursement
H	Hotel/Motel
O	Hospitalization, College
P	Payment Transaction
R	Retail Sale
T	Phone, Mail, or Electronic Commerce Order
U	Unique
X	Airline and other transportation Services
Z	ATM Cash Disbursement

Ejemplo: "R3734011100000246589031500004795 ", donde.

T o R	TCC
37	Longitud total de datos
34	Longitud de sub elementos
1	Sub elemento 01
11	Longitud de sub elemento 01
0000024 6589	Código de marca asignado por ella (para Diners o Discover deben enviar ceros = 00000000000)
3	Sub elemento 03
15	Longitud de sub elemento 03

Estructura secundaria. Principalmente transacciones con 3DS y Tokenizacion. Contiene los campos dentro de trama.

Orden	Campo Anterior	Subelemento	Longitud	Descripción
1	datoSeguridad3DS	Subelemento 43 datoSeguridad3DS (3–D Secure for Mastercard Identity Check)	32	(3–D Secure for Mastercard Identity Check) Contiene los datos UCAF, esta descrita para la implementación de Mastercard 3DS.
2	indicadorSeguridad3DS	Subelemento 42 indicadorSeguridad3DS (Electronic Commerce Indicators)	7	Contiene un indicador de comercio electrónico
3	idProtocolo3DS	Subelemento 66 idProtocolo3DS	16	Datos Adicionales para uso Privado. Protocolo de Programa
4	idTransaccionMastercard3DS	Subelemento 66 idTransaccionMastercard3DS	40	Datos Adicionales para uso Privado. Id Transacción
5	tRID (no existente / referencial)	Subelemento 33 (Token Requestor ID)	19	Nuevo Campo para Token Required ID (Identificación de Quien Solicita el Token). Contiene la Identificación asignada por el Proveedor de Servicios de Token al solicitante del Token (Token Requestor ID). Aplica para Mastercard y Visa.
6	tAVV (no existente / referencial)	Subelemento 44 (Token Authentication Verification Value (TAVV))	24	Nuevo Campo para TAVV 44 (Identificador de Transacción de Comercio Electrónico 3-D Secure [XID] [Visa y American Express]). Contiene el identificador de transacciones de comercio electrónico 3-D Secure (XID).

El orden de campos y sus valores concatenados sin espacios se expresan así: - datoSeguridad3DS+indicadorSeguridad3DS+idProtocolo3DS+idTransaccionMastercard3DS+tRID+tAVV Ejemplo campo datoSeguridad3DS (DE 48.43): 43205, donde.

43	Element ID
2	Longitud elemento
an-2	Representación
5	Valor

Ejemplo campo indicadorSeguridad3DS (DE 48.42): 42205, donde.

42	Element ID
2	Longitud elemento
an-2	Representación
5	Valor

Ejemplo campo idProtocolo3DS (DE 48.66.01): 6650121, donde.

66	Element ID
5	Longitud elemento
01	Subcampo
2	Longitud elemento
an-1	Representación
1 = 3–D Secure Version 1.0 (3DS 1.0) 2 = EMV 3–D Secure (3DS 2.0)	Valor

Ejemplo campo idTransaccionMastercard3DS (DE 48.66.02): 6602202, donde.

66	Element ID
2	Subcampo
2	Longitud elemento
ans-36	Representación
f38e6948-5388-41a6-bca4-b49723c19437	Valor

Ejemplo campo tRID (DE 48.33): 3316061140010051602, donde.

33	Element ID
16	Longitud elemento
6	Subcampo
11	Longitud elemento
n-11	Representación
40010051602	Valor

Ejemplo campo tAVV (DE 48.44): 4420YmFzZTY0IGRlY29kZXI=, donde.

44	Element ID
20	Longitud elemento
b-20	Representación
YmFzZTY0IGRlY29kZXI=	Valor

Campo montosAdicionales

Campo destinado para montos en formato trama. Tipo de campos:

Valor u Orden	Campo	Longitud	Ejemplo
1	IVA	12	000000000125
2	Servicio	12	000000001256
3	Propina	12	000000000001
4	Intereses	12	000000000012
5	# Autorización	6	00002306 000023
6	Monto Fijo	12	000000000658

El orden de campos y sus valores concatenados sin espacios respetando el orden, teniendo así: IVA+Servicio+Propina+Intereses+# Autorización+Monto Fijo Ejemplo solo iva: 0161112000000000652, donde.

016	longitud total
1	cantidad de campos a recibir
1	tipo de campo: iva
12	longitud
000000000652	valor

Ejemplo iva + monto interés: 0222112000000000652440150, donde.

22	longitud total
2	cantidad de campos a recibir
1	tipo de campo: iva
12	longitud
000000000652	valor
4	tipo de campo: interes
4	longitud
0150	valor

Campo informacionProductos

Campo destinado a información de productos en específico tipo de crédito, teniendo así.

Valor u Orden	Identificador	Longitud Fija
000	Transacción Corriente	03
001	Crédito Corriente	03
002	Crédito con Interés	03
003	Crédito sin Interés	03
004	Monto Fijo / Tipo de Comercio Gasolineras	03
005	Promociones	03
006	Tarjeta Propietaria	03
007	Tipo de crédito especial con interés	03
008	Tarjeta descuento	03
009	Tipo de crédito especial sin interés	03
021	Tipo de crédito plus cuotas	03
022	Tipo de crédito plus	03
101	Aereolíneas	03
102	Tarjeta Inteligente	03

Ejemplo tarjeta de débito: 00003001, donde.

000	Identificador del producto
03	Valor fijo
001	dato
No aplica	Longitud total
00003001	valor

Campo valoresAdicionales

Campo destinado a información de valores adicionales, productos en específico de valor campo 58 con el identificador de campo 70 correspondiente a “ID de Preautorización”, teniendo así de manera general los campos asociados a valoresAdicionales.

Campo	Identificador
Campo de Cedula	1
Campo de Bitácora	2
Campo de Cod comercio	3
Campo de Cod cierre	4
Campo de Teléfono	5
Campo de Factura	6
Campo de Puntos	7
Campo de Celular	8
Campo de Numero de Lote	9
Campo de CI Vendedor(cedula)	10
Campo de Código vendedor	11
Campo de Código comercio	12
Campo de CI Vendedor Gas	13
Campo de Vendedor	14
Campo de PC Vendedor	15
Campo de BG Vendedor	16
Campo de Numero Cupon	17
Campo de Cod Empleado	18
Campo de ID Vendedor	19
Campo de IVA	20
Campo de ICE	21
Campo de Impuesto	22
Campo de Placa	23
Campo de Otros	24
Campo de Tarjeta	25
Campo de Total Descuento	26
Campo AD1	27
Campo AD2	63
Identificador de Proveedor de servicio	63
Identificador de Interfaz fijo para OTT Pacifico (006)	67
ID Billetera (Diners)	68
ID de Preautorizacion	70
Identificador de recurrencia Boton	75
ID QR Billetera	79
Correo voucher digital	80
Identificador de tokenización Boton	81
Telefono de Subcomercio - Facilitador	82
Dirección de Subcomercio - Facilitador	83
Porcentaje de IVA de las Bases imponibles	84
Identificador de RequestID (TAG 9F19)	85
Identificador de Agregador	90
Identificador de tipo de tarjeta (Geopagos FP)	92
RED de Pos Ecuador (DATAFAST 99 - reservado BdP)	99

Para crear el campo tenemos la siguiente tabla de orden, longitudes y concatenación.

1	Longitud total	3
2	Longitud de los datos del campo	2
3	Identificador del camp	2
4	Datos o Valor

Ejemplo: valoresAdicionales: “0281282099089120512104578124578”, donde. Los campos concatenados sin espacios y respetando sus longitudes tenemos. LongitudTotal+(LongitudSumaIdentificadorCampo+LongDato)+IdentificadorCampo+Dato 028 = Longitud total del campo valoresAdicionales. 12 = Suma del identificador de campo + dato 82 = (Teléfono): identificador de campo 0990891205 = Dato o valor 12 = Suma del identificador de campo + dato 10 = (Cédula): identificador de campo 4578124578: = Dato o valor Ejemplo tarjeta de débito: 00003001, donde.

000	Identificador del producto
03	Valor fijo
001	dato
No aplica	Longitud total
00003001	Valor

Campo datosPOS

Campo destinado a información de valores adicionales, productos en específico de valor campo 61 con el subcampo 7 correspondiente a “Indicador Status transacción” accediendo al valor 4 correspondiente a “Preautorizaciones”.

Subcampo	Posición	Atributo	Valor
1 Indicador atención Terminal	1	n=1	Terminal Atendida por operador Terminal manejada por Tarjeta habiente No se usa terminal, (audiorespuesta etc) Información no disponible
2 Capacidad de entrada de la terminal	2	n=1	0 No usado (POS) 8 Contactless Proximity-Read-Capable terminal
3 Indicador ubicación Terminal	3	N=1	0 En oficinas de Comercio 1 Ubicación remota Comercio 2 En oficina Tarjetahabiente (PC usuario) 3 No se usa terminal 6 Sin presencia Tarjetahabiente 9 Información no disponible
4 Indicador presencia Tarjetahabiente	4	N=1	0 Tarjetahabiente presente 1 Tarjetahabiente no presente 2 Tarjetahabiente no presente (orden correo) 3 Tarjetahabiente no presente (Audiorespuesta) 4 Transacciones recurrentes preautorizadas 5 Tarjetahabiente no presente (Internet) 9 Información no disponible
5 Indicador presencia Tarjeta	5	N=1	0 Tarjeta presente 1 Tarjeta no presente 9 Información no disponible
6 Indicador retención Tarjeta	6	N=1	0 El Operador o la terminal no tienen capacidad de retener tarjetas 1 El Operador o la terminal tienen capacidad de retener tarjetas 9 Información no disponible
7 Indicador Status transacción	7	N=1	0 Transacción normal 1 Compra aprobada por comercio 3 Pago preautorizado recurrente 4 Preautorización 5 Standin Mastercard débito 7 Compra con vueltas
8 Indicador Seguridad Transacción	8	N=1	0 Sin problemas de seguridad 1 Sospechoso de fraude 2 Identificación verificada
9	9	N=1	0 No usado
10 Terminal type	10	N=1	0 No es un CAT 1 ATM o máquina dispensadora con PIN 2 Terminal de autoservicio 3 Terminal de cantidad limitada 4 Comercio de aerolínea 5 Dispositivo script 6 Comercio Electrónico 7 Transponder 8 Mobile acceptance solution (Visa – SoftPOS)
11 Tipo lector Terminal	11	N=1	0 Desconocido 1 No se usa terminal 2 Lector de banda 3 Lector de Proximidad CHIP Contactless 4 Lector de Proximidad Banda 5 Lector banda y CHIP 6 Teclado únicamente 7 Lector banda y teclado 8 Lector banda y chip, y teclado 8 Contactless Proximity-Read-Capable Terminal (Visa – SoftPOS) 9 Lector CHIP
12 Indicador ciclo autorización	dic-13	N=2	Número de días de preautorización
13 Código País	14-16	N=3	Código del País donde está ubicado el terminal
14 Código Postal	17-26	Ans-10	Código Postal de ubicación del terminal, ceros si se desconoce

Para crear el campo tenemos la siguiente tabla de orden, longitudes y concatenación.

1	Longitud total	3
3	Identificador del campo	2
4	Datos o Valor

Ejemplo: datosPos con Preautoriaciones: “0000004000000218”, donde.

Subcampo/ Posición	1	2	3	4	5	6	7	8	9	10	11	12	13	14
Valor	0	0	0	0	0	0	4	0	0	0	0	0	0	218

Campo nombreEstablecimiento

El campo está compuesto por los siguientes sub campos: - Nombre de comercio: Largo 22 - Espacio: Largo 1 - Código de ciudad (Ej. GYE): Largo 13 (Si hiciera falta rellenar con espacios) - Espacio: Largo 1 - Código de país: Largo 3

Campo datosOriginales

Campo datosOriginales mensajeId+ fechaHoraTrasmision + numeroSeguimientoAuditoria+ idDatafast+ idEmisor - Autorización: Se envía cero (0). Ejemplo: 0 - Anulación: Se concatena en base a la indicación inicial. Ejemplo: 020014051301012309080000047329300000473293

0200 + 1405130101 + 230908 + 00000473293 + 00000473293 Donde: 0200 -> mensajeId: Largo 4 (Anulación) 1405130101 -> fechaHoraTransmision: Largo 10 230908 -> numeroSeguimientoAuditoria: Largo 6 00000473293 -> idDatafast: Largo 11 00000473293 -> idEmisor: Largo 11

Para formar el request de la anulación de una preautorizacion tomar en cuenta: El campo datosOriginales, se forma concatenando los siguientes datos - 0200 - CAMPO 11 (numeroSeguimientoAuditoria) de autorización original - CAMPO 7 (fechaHoraTransmision) de autorización original - CAMPO 32 (idDatafast) de autorización original - CAMPO 33 (idEmisor) de autorización original

Para formar el request de la anulación de un incremento tomar en cuenta: El campo datosOriginales, se forma concatenando los siguientes datos - 0200 - CAMPO 11 (numeroSeguimientoAuditoria) del incremento - CAMPO 7 (fechaHoraTransmision) del incremento - CAMPO 32 (idDatafast) del incremento - CAMPO 33 (idEmisor) del incremento

Campo valorCampo61

Para preautorizaciones se requiere los valores de los campos marcados en rojo, los demás valores deberán ser 0.

Ejemplo: 000000400000218

Subcampo	Posición	Atributo	Valor
1 Indicador atención Terminal	1	n=1	Terminal Atendida por operador Terminal manejada por Tarjeta habiente No se usa terminal, (audiorespuesta etc) Información no disponible
2 Capacidad de entrada de la terminal	2	n=1	0 No usado
3 Indicador ubicación Terminal	3	N=1	0 En oficinas de Comercio 1 Ubicación remota Comercio 2 En oficina Tarjetahabiente (PC usuario) 3 No se usa terminal 6 Sin presencia Tarjetahabiente 9 Información no disponible
4 Indicador presencia Tarjetahabiente	4	N=1	0 Tarjetahabiente presente 1 Tarjetahabiente no presente 2 Tarjetahabiente no presente (orden correo) 3 Tarjetahabiente no presente (Audiorespuesta) 4 Transacciones recurrentes preautorizadas 5 Tarjetahabiente no presente (Internet) 9 Información no disponible
5 Indicador presencia Tarjeta	5	N=1	0 Tarjeta presente 1 Tarjeta no presente 9 Información no disponible
6 Indicador retención Tarjeta	6	N=1	0 El Operador o la terminal no tienen capacidad de retener tarjetas 1 El Operador o la terminal tienen capacidad de retener tarjetas 9 Información no disponible
7 Indicador Status transacción	7	N=1	0 Transacción normal 1 Compra aprobada por comercio 3 Pago preautorizado recurrente 4 Preautorización 5 Standin Mastercard débito 7 Compra con vueltas
8 Indicador Seguridad Transacción	8	N=1	0 Sin problemas de seguridad 1 Sospechoso de fraude 2 Identificación verificada
9	9	N=1	0 No usado
10 Terminal type	10	N=1	0 No es un CAT
11 Tipo lector Terminal	11	N=1	0 Desconocido 1 No se usa terminal 2 Lector de banda 3 Lector de Proximidad CHIP Contactless 4 Lector de Proximidad Banda 5 Lector banda y CHIP 6 Teclado únicamente 7 Lector banda y teclado 8 Lector banda y chip, y teclado 9 Lector CHIP
12 Indicador ciclo autorización	12-13	N=2	Número de días de preautorización
13 Código País	14-16	N=3	Código del País donde está ubicado el terminal