Buenas prácticas

Envío de datos

Envía todos los campos disponibles. Cuantos más datos proporciones, mayor es la eficacia de las soluciones contratadas. Campos como card_bin, order_number, ip_address y addresses son especialmente importantes.
Usa el envío por lotes para grandes volúmenes. En lugar de enviar una transacción por solicitud, agrupa hasta 1000 transacciones en el endpoint /transactions/batch para reducir la sobrecarga de red.
Mantén external_source y external_id consistentes. Estos campos se usan para detectar duplicados. Usa identificadores únicos y estables de tu sistema de origen.
Envía las transacciones lo antes posible. Cuanto más cerca del momento de la venta, mejor es la cobertura de las soluciones de prevención.

transaction_date en ISO 8601. Usa el formato completo con zona horaria (ej.: 2026-04-01T15:30:00Z).
currency en mayúsculas. Usa el código ISO 4217 de 3 letras mayúsculas (ej.: USD, BRL, EUR).
card_last4 como string. Envíalo como string de exactamente 4 dígitos (ej.: "0042", no 42).
merchant_id como UUID. Usa el UUID del merchant tal como lo devuelve la API o el panel.

Nunca expongas tu client_secret. Trátalo como una contraseña. No lo incluyas en código frontend, repositorios públicos ni logs.
Usa siempre HTTPS. Todas las solicitudes deben hacerse por HTTPS.
Implementa reintentos con espera progresiva. Ante un error 500 (error interno), espera antes de intentar de nuevo: 1s, 2s y luego 4s entre intentos. En el 429 no hace falta adivinar: la respuesta trae el header Retry-After con los segundos exactos hasta que la ventana se reinicie (ver Rate limit).

Transacción única: revisa el campo data para los datos de la transacción creada y warnings para los avisos.
Envío por lotes: recorre results (éxitos con tx_id y warnings) y errors (fallas con external_id, status y mensaje).
Presta atención a los warnings. No bloquean la creación, pero indican campos ausentes que afectan la eficacia de las soluciones.
Guarda el id devuelto. Lo vas a necesitar para consultar, actualizar o eliminar la transacción.

Corrige los errores antes de la primera consulta. Las transacciones usadas por las soluciones (ej.: consultadas por la Prevención) se vuelven inmutables. Usa PATCH para corregir datos mientras la transacción todavía no fue usada.