Diccionario JSON ↔ ISO 8583

El Autorizador JSON arma todos los data elements (DE) del mensaje a partir de tu JSON, de tu registro de comercio y de los datos de red que asigna él mismo. Antes de escribir un solo byte, valida el mensaje contra el formato del emisor: un campo que no cabe responde 400 y nunca llega al emisor.

Solicitud: de JSON a ISO 8583

DE	Nombre ISO	Origen	Valor
MTI	Tipo de mensaje	operacion	COMPRA y CONSULTA_SALDO → 0200; PREAUTORIZACION → 0100; captura → 0220; devolución → 0200; reverso → 0400
2	PAN	medio	Con CREDENCIAL_FPW1, el número de la credencial (no es el número de la tarjeta). Con TOKEN, el número resuelto en memoria (Próximamente). Nunca lo envías tú
3	Código de proceso	operacion	000000 compra, preautorización y captura; 310000 consulta de saldo; 200000 devolución; el reverso repite el de la original
4	Importe	monto.valor	12 dígitos en unidades menores, sin separador: 1250.00 → 000000125000. Nunca se redondea
7	Fecha y hora de transmisión	Autorizador	MMddHHmmss en UTC. Se calcula una vez y se guarda: el reverso la repite en el DE 90
11	STAN	Autorizador	6 dígitos por terminal. Cada mensaje lleva uno propio, también el reverso
12	Hora local	Autorizador	HHmmss en la hora de negocio de la instalación
13	Fecha local	Autorizador	MMdd en la hora de negocio de la instalación
18	MCC	Registro del comercio	Debe coincidir con comercio.mcc (si no, 403 MCC_NO_COINCIDE)
22	Modo de entrada	entrada.modo	ECOMMERCE → 010; BILLETERA → 031
25	Condición del punto de servicio	entrada.modo	ECOMMERCE → 59. La preautorización (0100) no lo lleva
37	RRN	Autorizador	12 dígitos: último dígito del año y día juliano en UTC (YDDD) más una secuencia de 8 dígitos
38	Código de autorización	Original	Solo en la captura: el de la preautorización
41	Terminal (TID)	Autorizador	Terminal virtual del grupo de tu comercio. Reverso, captura y devolución repiten el de la original
42	Código del comercio	comercio.codigo	15 caracteres; debe pertenecer a tu cliente (si no, 403 COMERCIO_AJENO)
43	Nombre y ubicación	Registro del comercio	No lo puedes cambiar
48	Datos privados	opciones y medio	Pares clave=valor; (ver más abajo)
49	Moneda	monto.moneda	ISO 4217 numérica: 928 (VES) o 840 (USD)
90	Datos del original	Autorizador	Solo en el reverso: MTI + STAN + DE 7 de la original, completado con ceros hasta 42 dígitos

DE 48: datos privados

El DE 48 viaja como pares clave=valor;. El autorizador solo escribe estas etiquetas:

Etiqueta	Origen JSON	Significado
wc	medio.credencial (solo CREDENCIAL_FPW1)	La credencial completa de la billetera
cu	opciones.cuotas (2 a 48)	Número de cuotas
pa	opciones.aprobacionParcial: true → pa=1	Admite aprobación parcial (respuesta 10)
rq	opciones.referenciaTasa: true → rq=1	Pide la referencia de tasa de cambio en la respuesta

Y solo lee de la respuesta rf (moneda de referencia), tr (tasa) y ra (monto en la moneda de referencia), que se publican en referenciaTasa. Ninguna otra etiqueta entra ni sale.

Por ejemplo, una compra con FPW1, 3 cuotas y aprobación parcial lleva:

DE 48 = wc=FPW1.9919000000000012345.1792512000.3f9a1c0e7b2d4a68;cu=3;pa=1;

Respuesta: de ISO 8583 a JSON

La respuesta se construye campo a campo con una lista blanca; nunca se copia el mensaje del emisor.

Campo JSON	DE	Notas
codigoRespuesta	39	Siempre 91 si resultado es INDETERMINADA; nulo si es NO_ENVIADA
codigoAutorizacion	38	Nulo si no hubo aprobación
rrn	37	El asignado por el autorizador
stan	11	El STAN de esta operación
monto.aprobado	4	Distinto de monto.solicitado en una aprobación parcial (10). Nulo si no se aprobó
referenciaTasa.moneda / .tasa / .monto	48 rf / tr / ra	Solo si pediste referenciaTasa y la operación se aprobó
iso.mtiRespuesta	MTI	0110, 0210, 0230 o 0410; nulo si no hubo respuesta del emisor

La consulta de saldo (CONSULTA_SALDO) devuelve el resultado, pero el saldo no se publica en v1.

Lo que nunca envías

• DE 7, 11, 12, 13, 37 y 41 los pone siempre el autorizador. Si los mandas en la vista ISO, 400 DE_NO_PERMITIDO.
• DE 2, 35, 45, 52, 55 y 127 (número de tarjeta, pistas, PIN, EMV y P2PE) están prohibidos en v1: 400 DE_NO_PERMITIDO.
• En el DE 48 de la vista ISO solo se admiten cu, pa y rq; otra etiqueta responde 400 ETIQUETA_DE48_NO_PERMITIDA.

Vista ISO por data element (bajo acuerdo)

Los integradores certificados pueden enviar el mensaje por número de DE en POST /v1/iso/messages. Solo se admiten los MTI 0100 y 0200, con los DE 3, 4, 18, 22, 25, 42, 43 (se sobrescribe con el registro), 48 y 49. Reversos, capturas y devoluciones van siempre por la vista semántica, para que el autorizador reutilice el terminal, el RRN y el DE 7 de la original.

{
  "version": "2026-10",
  "mti": "0200",
  "medio": { "tipo": "CREDENCIAL_FPW1", "credencial": "FPW1.9919000000000012345.1792512000.3f9a1c0e7b2d4a68" },
  "elementos": {
    "3": "000000",
    "4": "000000125000",
    "18": "5411",
    "22": "031",
    "42": "000000000012345",
    "49": "928",
    "48": { "cu": "3", "pa": "1" }
  }
}

Respuesta (200):

{
  "idAutorizacion": "01JBX3A7K2M4N6P8R0S2T4V6W8",
  "resultado": "APROBADA",
  "mti": "0210",
  "elementos": {
    "3": "000000",
    "4": "000000125000",
    "11": "000457",
    "37": "629300000123",
    "38": "A1B2C3",
    "39": "00"
  },
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "latenciaMs": 41
}

Con GET /v1/authorizations/{id}?vista=DE consultas cualquier autorización en esta misma forma.