Directrices de la API

Consideraciones de desarrollo

Los siguientes cambios se consideran compatibles hacia atrás:

• Agregar una nueva solicitud de API.

• Agregar un nuevo parámetro opcional a una solicitud o respuesta de API existente.

  • Agregarlo en el cuerpo, como parámetro de consulta o como un encabezado HTTP.

• Agregar un nuevo valor de enumeración.

• Hacer opcionales los parámetros obligatorios.

• Ignorar campos o valores desconocidos recibidos en una solicitud o respuesta de API.

Gestión de errores

Respuestas y tipos de error

Las respuestas se agrupan en categorías. Maneje todas las respuestas en la misma categoría de la misma manera. La siguiente tabla enumera las categorías e indica:

• Los tipos de error en cada categoría.

• Cómo el backend del emisor debe manejar estos errores, incluida la política de reintentos.

CÓDIGO TIPO	CATEGORÍA	DESCRIPCIÓN Y POLÍTICA DE REINTENTOS
K	OK, no es un error	N/A
D	Error de datos	Los parámetros enviados por el solicitante de la función no coinciden con las reglas verificadas por el proveedor de la función.
S	Error de sistema	Este es un error inesperado causado por una falla temporal en una o más partes del sistema. El solicitante de la función puede reintentar la solicitud. Nota: Los errores HTTP 5xx se consideran errores de sistema.
F	Error funcional	Este es un error definitivo. Abortar el procesamiento. No reintentar. El token ya no se puede usar y debe eliminarse.

Errores

La tabla a continuación enumera los errores que pueden ocurrir.

Dependiendo del flujo, un error puede devolverse de forma sincrónica en la respuesta o de forma asincrónica en una devolución de llamada.

CÓDIGO DE ERROR	CÓDIGO TIPO	DESCRIPCIÓN
111	D	Falta un parámetro obligatorio
112	D	Formato de parámetro incorrecto
113	D	Emisor desconocido
114	D	Usuario final desconocido
115	D	Producto desconocido
116	D	Tarjeta desconocida
117	D	Almacenamiento de tokens desconocido
118	D	Solicitud desconocida
119	D	Tarjeta virtual desconocida
158	D	Parámetros inválidos: tarjeta expirada
159	D	Parámetros inválidos: tarjeta suspendida
160	D	Parámetros inválidos: tarjeta revocada o eliminada
161	D	El valor de autenticación es incorrecto. Código de seguridad de la tarjeta (CSC) incorrecto OTP criptográfico inválido
163	D	Producto no compatible con pago móvil
164	D	Se excedió el recuento de aprovisionamiento FPAN
166	D	Información de la tarjeta inválida (FPAN, fecha de vencimiento) o tarjeta no elegible
167	D	Tarjeta ya inscrita
168	D	No hay número de teléfono asociado con el usuario final
221	S	El proveedor del dispositivo o de la billetera no es accesible después de reintentos
222	S	El proveedor del dispositivo o de la billetera está ocupado
231	F	Error inesperado del dispositivo
232	F	Memoria insuficiente en el dispositivo para realizar la operación
321	S	La operación sobre un token ya está en curso
322	S	Tiempo de vida de la operación expirado
323	S	Operación parcialmente completada (típicamente cuando una operación apunta a múltiples tarjetas virtuales y una falla)
421	S	OTP o PIN bloqueado (límite de reintentos excedido)
422	S	OTP expirado
431	F	Datos de personalización inválidos
432	F	El estado actual del token/tarjeta no permite esta operación
501	D	El ID del método ID&V es inválido
502	D	El canal de comunicación no está disponible para enviar OTP
503	D	El método ID&V seleccionado por el usuario final es ya no válido. Esto puede ocurrir si, durante la inscripción, los datos del canal (por ejemplo, un número de teléfono) se vuelven inválidos para el proceso de ID&V.
510	F	Verificación de titular de tarjeta escalada rechazada (solo Visa CTF)
520	F	Verificación de titular de tarjeta escalada fallida (solo Visa CTF)
521	S	Error del servidor de push
531	F	Token de push ya no válido
911	F	Operación fallida
920	F	Se excedió el límite de generación de OTP
921	S	Error inesperado del servidor