Medios, límites y sandbox

Medios aceptados en v1

En v1 el número de la tarjeta nunca viaja en claro: no hay campo para el PAN, ni para pistas, PIN, EMV o P2PE. Solo se aceptan tarjetas emitidas en FINORA (on-us).

medio.tipo	Estado	Formato	Notas
CREDENCIAL_FPW1	Implementado	FPW1.<número>.<vencimiento>.<mac>: número de 16 a 19 dígitos, vencimiento de 9 a 11 dígitos y MAC de 16 caracteres hexadecimales	Credencial de billetera de un solo uso que genera la app del titular. Usa entrada.modo: BILLETERA. No se guarda
TOKEN	Próximamente	tok_ seguido de 12 a 64 caracteres alfanuméricos	Requiere el servicio de tokenización, que aún no está disponible: hoy responde 403 OPERACION_NO_PERMITIDA

Ejemplo ficticio de credencial:

FPW1.9919000000000012345.1792512000.3f9a1c0e7b2d4a68

Consecuencias prácticas en v1:

• Como la credencial FPW1 es de un solo uso, cada intento nuevo necesita una credencial nueva.
• Las devoluciones necesitan el medio TOKEN y llegan con él (Próximamente). Una compra con FPW1 se deshace con un reverso.

Monedas e importes

Regla	Detalle
Monedas	928 (VES) y 840 (USD), siempre que estén habilitadas para tu cliente
Formato	Texto decimal con exactamente 2 decimales: "1250.00", nunca 1250 ni "1250.5"
Rango	Mayor que cero y hasta 10 enteros (9999999999.99), lo que cabe en el DE 4
Redondeo	Nunca. Un importe fuera de regla responde 400 MONTO_INVALIDO
Consulta de saldo	Sin monto, o con "0.00"
Captura	Una por preautorización, ≤ monto.aprobado, misma moneda
Devoluciones	Σ (aprobadas + en curso) + nueva ≤ monto.aprobado de la compra, misma moneda
Reversos	Siempre totales en v1

Otros límites

Límite	Valor
Plazo de respuesta del emisor	2.500 ms por defecto (configurable por cliente entre 1.000 y 2.999 ms)
Tamaño del cuerpo	16 KB
Idempotency-Key	16 a 64 caracteres [A-Za-z0-9_-], única por cliente
referenciaCliente	Hasta 64 caracteres
Cuotas (opciones.cuotas)	Entero de 2 a 48
Tolerancia del reloj	±60 s sobre X-Finora-Fecha por defecto (FINORA puede fijar entre 5 y 300 s para tu cliente)
Solicitudes por segundo	Las que fije tu registro, más un límite global del servicio. Por encima: 429 LIMITE_DE_TASA con Retry-After
Versión del contrato	"version": "2026-10" en todos los cuerpos

Sandbox

Próximamente

Todavía no hay sandbox. Cuando exista, se anunciará en Cambios con sus credenciales de prueba y su tarjeta ficticia (por ejemplo, la tarjeta de prueba 990500******0015). Mientras tanto, puedes preparar y probar tu firma JWS y tu manejo de estados contra los ejemplos de estas guías.

Lista de verificación antes de salir a producción

• Tu cliente HTTP presenta el certificado mTLS y su tiempo de espera es mayor que el plazo del autorizador.
• Firmas la ruta con su consulta y el SHA-256 de los bytes exactos del cuerpo.
• Generas un nonce nuevo por petición y tu reloj está sincronizado (NTP).
• Guardas idAutorizacion y tu Idempotency-Key antes de responder a tu usuario.
• Ante un fallo de red reintentas con la misma clave; nunca cambias de clave para «forzar» un reintento.
• Decides por resultado; tratas INDETERMINADA como no cobrada hasta verla REVERSADA.
• Respetas Retry-After en 429 y 503.