Campos requeridos para migrar a Pomelo

Envía tus datos en el formato exacto que necesitamos para migrar tu operación sin errores ni retrabajos.

Introducción

Cuando migras usuarios, tarjetas y transacciones a Pomelo, necesitamos que tus datos lleguen en un formato específico para poder validarlos y procesarlos correctamente.
En Pomelo, necesitamos que cada campo llegue con el tipo, la longitud y el formato exactos que detallamos a continuación para las tres entidades del proceso: Usuarios (USERS), Tarjetas (CARDS) y Transacciones (TRANSACTIONS).

Antes de enviar cualquier archivo, revisa que cada campo obligatorio esté completo y que los datos sensibles estén correctamente encriptados o tokenizados.

Alcance

Esta especificación aplica a cualquier institución que migre su operación a Pomelo, para tarjetas físicas y virtuales, en todos los países donde operamos.

Funcionamiento

El proceso de migración sigue estos pasos:

  1. Preparas los tres archivos CSV (uno por entidad) con la nomenclatura y el formato que detallamos en la sección Formato de archivos.
  2. Envías los archivos vía SFTP a nuestro servidor de migración.
  3. Nos notificas los nombres de archivo y la fecha de envío.
  4. Validamos los datos y te reportamos los errores encontrados en un plazo de 48 horas hábiles.
  5. Corriges y vuelves a enviar únicamente los registros con errores.

Formato de archivos

Envíanos los datos en tres archivos CSV separados, uno por entidad, con las siguientes especificaciones:

Especificación Valor
Encoding UTF-8
Delimitador Coma (,)
Primera fila Encabezados exactos según este diccionario
Datos sensibles Encriptados o tokenizados
Nomenclatura USERS-YYYYMMDDTHHMMSSz.csv, CARDS-YYYYMMDDTHHMMSSz.csv, TRANSACTIONS-YYYYMMDDTHHMMSSz.csv

Validaciones críticas

Antes de enviar, verifica que se cumplan estas condiciones:

Validación Detalle
Integridad referencial Todo card_id en TRANSACTIONS debe existir en CARDS. Todo id_user en CARDS debe existir en USERS.
Formatos estándar Fechas en ISO-8601, monedas en ISO-4217, países en ISO-3166.
Campos obligatorios Todo campo con ✓ en la columna "Req" debe contener un valor. Los campos opcionales se incluyen únicamente si tienes la información disponible (su ausencia no genera errores de validación).
Valores numéricos Montos mayores a 0; longitudes dentro de los máximos especificados.
Datos PCI pan, pvv y service_code nunca en texto plano. Encriptación obligatoria.

Usuarios

La entidad USERS contiene información demográfica y de contacto. Todos los campos son obligatorios salvo que se indique lo contrario. El campo address del formato original se desagrega en múltiples campos de dirección para mayor precisión.

Campo Descripción Tipo Long. Formato Req. Sensib. Validaciones Ejemplo
id_user Identificador del usuario String 128 Libre ✓ — Único, no nulo USR-00123456
name Nombre String 128 UTF-8 ✓ PII Trim, sin caracteres especiales María
surname Apellido String 128 UTF-8 ✓ PII Trim González
identification_type Tipo de documento String 16 Enum — PII Catálogo por país CEDULA
identification_value Número de documento String 32 Alfanumérico — PII Único por tipo + país 8-123-456
tax_identification_type Tipo de documento fiscal (campo nuevo) String 16 Enum ✓ PII Catálogo por país RUT
tax_identification_value Número de documento fiscal (campo nuevo) String 40 Alfanumérico ✓ PII Único por tipo + país 20423456789
tax_condition Posición impositiva frente al fisco (campo nuevo) String 16 Enum ✓ PII VAT_REGISTERED, OTHERS VAT_REGISTERED
birthdate Fecha de nacimiento Date — YYYY-MM-DD — PII Validación de mayoría de edad 1990-05-14
email Correo electrónico String 256 RFC 5322 ✓ PII Formato válido, en minúsculas [email protected]
gender Sexo/género String 16 Enum — PII MALE, FEMALE, OTHER, UNSPECIFIED FEMALE
street_name Nombre de la calle String 256 Texto libre ✓ PII — Calle 50 Este
street_number Número de la calle String 16 Alfanumérico ✓ PII — 27
floor Piso String 16 Alfanumérico — PII Opcional 3
apartment Apartamento/unidad String 16 Alfanumérico — PII Opcional B
zip_code Código postal String 16 Alfanumérico ✓ PII — 0816
neighborhood Barrio / colonia String 128 Texto libre — PII — Marbella
city Ciudad String 128 Texto libre ✓ PII — Ciudad de Panamá
region Región / provincia / estado String 128 Texto libre ✓ PII — Panamá
country País de residencia String 3 ISO-3166 alpha-3 ✓ — Catálogo ISO PAN
additional_info Información adicional de dirección String 512 Texto libre — PII Opcional Torre Pacific, piso 3
municipality_code Código de municipio String 16 Alfanumérico — — Opcional; aplica según requerimiento regulatorio del país PT-01
status Estado del usuario String 16 Enum ✓ — ACTIVE, BLOCKED ACTIVE
created_at Fecha de creación DateTime — ISO-8601 — — — 2023-01-15T10:30:00Z
phone Número de teléfono String 32 E.164 — PII +50761234567 (ejemplo) +50761234567

Aclaraciones

  • El id_user debe ser único y estable a lo largo del tiempo.
  • Los nombres y apellidos deben estar libres de caracteres especiales (recomendamos aplicar trim automático).
  • El email se usa para comunicaciones y debe estar en minúsculas.
  • El campo phone debe seguir el formato E.164 (por ejemplo, +50761234567).
  • El campo municipality_code es opcional y aplica según el requerimiento regulatorio de cada país.
  • tax_identification_type, tax_identification_value y tax_condition son obligatorios y capturan la situación fiscal del usuario frente al fisco de su país.

Tarjetas

La entidad CARDS contiene los datos de las tarjetas emitidas. La mayoría de los campos son obligatorios por su importancia operativa y de seguridad.

Campo Descripción Tipo Long. Formato Req. Sensib. Validaciones Ejemplo
card_id ID externo único de la tarjeta (campo nuevo) String 64 Alfanumérico ✓ — Único, no nulo TKN-4A3F2B1C9D8E7F60
pan PAN tokenizado o encriptado String 64 Token/HSM ✓ PCI crítico Nunca en texto plano TKN-4A3F2B1C9D8E7F60
expiration_date Fecha de vencimiento String — YYYY-MM-DD ✓ PCI Fecha válida 2026-07-01
id_user ID del usuario asociado String 64 Alfanumérico ✓ PII indirecta Debe existir en USERS USR-00123456
type Tipo de tarjeta String 16 Enum ✓ — PHYSICAL, VIRTUAL PHYSICAL
service_code Código de banda magnética String 3 3 dígitos ✓ PCI ^\d{3}$ 201
status Estado de la tarjeta String 16 Enum ✓ — ACTIVE, BLOCKED, DISABLED, EMBOSSED, EXPIRED ACTIVE
pvv PIN Verification Value (encriptado) String 64 HSM/Encriptado ✓* PCI muy sensible Si no lo envías, regeneramos los PINs 0000
parent_pan PAN de tarjeta padre (si es adicional) String 64 Token/HSM — PCI Presente solo si es tarjeta adicional TKN-9Z8Y7X6W5V4U3T20
creation_date Fecha de creación String — YYYY-MM-DD ✓ — Fecha válida 2023-01-20
affinity_group_id Identificador del grupo de afinidad String 64 Alfanumérico ✓ — Identifica el grupo/programa de tarjeta (si aplica) afg-xxx
activation_code Código de activación (campo nuevo) String 10-20 Alfanumérico ✓* — Requerido si status es EMBOSSED AC1234567890

Aclaraciones

  • El pan debe estar tokenizado o encriptado bajo HSM. Nunca debe enviarse en texto plano.
  • El pvv es un dato crítico de seguridad. Si no está disponible o no podemos obtenerlo del Track2, regeneramos nuevos PINs.
  • Si parent_pan está presente, indica que la tarjeta es una tarjeta adicional.
  • card_id es el identificador externo único de la tarjeta, distinto del pan.
  • activation_code es obligatorio únicamente cuando la tarjeta se encuentra en estado EMBOSSED.

Transacciones

La entidad TRANSACTIONS contiene el historial de operaciones. Esta información es crítica para la conciliación y la auditoría.

Campo Descripción ISO Mastercard ISO Visa Tipo Long. Formato Req. Validaciones Ejemplo
id_transaction ID único de la transacción — — String 64 Alfanumérico ✓ Único, no nulo TXN-20230115-000987
card_id ID de la tarjeta — — String 64 Alfanumérico ✓ Debe existir en CARDS TKN-4A3F2B1C9D8E7F60
authorization_response_code Código de respuesta DE 39 Field 39 String 2 Numérico/alfanumérico ✓ Catálogo ISO 8583 00
life_cycle_trace ID único en Visa/MC DE 63.2 Field 62.2 String 64 Alfanumérico ✓ Único en red VLC202301150009871
mti_type Tipo de mensaje ISO DE 0 Field 0 String 4 Enum ✓ 0100, 0200, 0420 0200
processing_code Código de procesamiento ISO 8583 DE 3 Field 3 String 6 Numérico ✓ 000000, 010000, 400000 000000
transaction_amount Monto en moneda del comercio DE 4 Field 4 Decimal — 99999999.99 ✓ Mayor a 0 125.50
transaction_currency_code Moneda de la transacción DE 49 Field 49 String 3 ISO-4217 ✓ 840, 032, 170 (entre otros) 840
cardholder_billing_amount Monto en moneda del tarjetahabiente DE 06 Field 06 Decimal — 99999999.99 ✓ Mayor a 0 125.50
cardholder_billing_currency_code Moneda del tarjetahabiente DE 51 Field 51 String 3 ISO-4217 ✓ 840, 032, 170 (entre otros) 840
transmission_date_time Fecha/hora UTC DE 07 Field 07 DateTime — ISO-8601 ✓ No futura 2023-01-15T14:30:00Z
card_acceptor_local_date_time Fecha/hora local del comercio DE 12+13 Field 12+13 DateTime — ISO-8601 ✓ Coherente con UTC 2023-01-15T09:30:00
retrieval_reference_number Número de referencia único DE 37 Field 37 String 12 Numérico — Único por adquirente 230115000987
merchant_name Nombre del comercio DE 43.1 Field 43 String 128 UTF-8 — Trim Supermercado Rey
merchant_id ID del comercio DE 42 Field 42 String 64 Alfanumérico ✓ Único por adquirente 9876543210
merchant_category_code MCC del comercio DE 18 Field 18 String 4 Numérico ✓ Catálogo MCC 5411
merchant_country_code Código de país del comercio DE 43.5 Field 43 String 3 ISO-3166 alpha-3 ✓ Por ejemplo, PAN, ARG, USA PAN
approval_number Número de aprobación DE 38 Field 38 String 6 Numérico ✓ Catálogo ISO 8583 482015
stan System Trace Audit Number DE 11 Field 11 String 6 Numérico ✓ Único por sesión de red 000987
point_of_service_condition_code Código de condición del POS — Field 25 String 2 Numérico ✓ (solo Visa) Catálogo ISO 8583 00
market_specific_data_id ID de datos específicos de mercado DE 48.96 Field 62.4 String — Alfanumérico — Variable según red/mercado VFLOW-2023-001
pos_entry_mode Modo de ingreso del POS DE 22 Field 22 String — Numérico ✓ Catálogo ISO 8583 051
point_of_service_data Datos del punto de servicio (campo nuevo) DE 61 — String 26 Alfanumérico ✓ (solo Mastercard) Formato de subcampos DE 61 12345640000
replacement_amount Monto de reemplazo DE 95 Field 95 Decimal — Numérico — Mayor a 0 si aplica 5.00
settlement_amount Monto de la liquidación (campo nuevo) — — Decimal — 99999999.99 — Mayor a 0 125.50
settlement_currency_code Moneda de la liquidación (campo nuevo) — — String 3 ISO-4217 — Catálogo ISO 840
presentment_status Estado de la presentación (campo nuevo) — — String 32 Enum ✓ SETTLED, PENDING, PARTIAL_SETTLED SETTLED
presentment_transaction_amount Monto en moneda del comercio de la presentación (campo nuevo) — — Decimal — 99999999.99 — Mayor a 0 125.50
presentment_transaction_currency_code Moneda de la transacción en la presentación (campo nuevo) — — String 3 ISO-4217 — Catálogo ISO 840
presentment_billing_amount Monto de facturación en la presentación (campo nuevo) — — Decimal — 99999999.99 — Mayor a 0 125.50
presentment_billing_currency_code Moneda de facturación en la presentación (campo nuevo) — — String 3 ISO-4217 — Catálogo ISO 840
presentment_settlement_amount Monto de la liquidación en la presentación (campo nuevo) — — Decimal — 99999999.99 — Mayor a 0 125.50
presentment_settlement_currency_code Monto de la liquidación en la presentación (campo nuevo) — — String 3 ISO-4217 — Catálogo ISO 840

Aclaraciones

  • Los códigos DE (Mastercard) y Field (Visa) corresponden a campos estándar de cada red y no siempre coinciden numéricamente entre ambas.
  • mti_type: tipo de mensaje ISO (0100 = autorización, 0200 = transacción, 0420 = reverso).
  • Usa siempre códigos ISO-4217 para las monedas (ARS, USD, COP, MXN, entre otras).
  • life_cycle_trace: ID único asignado por Visa/Mastercard, crítico para las vinculaciones.
  • presentment_status: refleja si la transacción fue liquidada (SETTLED), está pendiente (PENDING) o fue liquidada parcialmente (PARTIAL_SETTLED).
  • stan (Field 11): System Trace Audit Number, identificador único que asigna el emisor para rastrear la transacción cuando no cuenta con el approval_number.
  • point_of_service_condition_code (Field 25): describe las condiciones bajo las cuales se realiza la transacción en el punto de servicio. Es un campo de Visa; en Mastercard esa información viaja en point_of_service_data.
  • point_of_service_data (DE 61): equivalente en Mastercard del point_of_service_condition_code de Visa. Agrupa varios subcampos del punto de servicio; su séptimo carácter indica si la transacción es una preautorización (valor 4). Se envía como columna adicional al final del archivo y solo aplica a clientes Mastercard: en un archivo Visa la columna no se incluye y el campo queda vacío.
  • pos_entry_mode (Field 22): modo de captura de los datos de la tarjeta en el POS (chip, banda, contactless, manual, entre otros).
  • merchant_country_code: código ISO-3166 alpha-3 del país donde está ubicado el comercio.
  • replacement_amount (Field 95): monto de reemplazo o propina; solo está presente cuando aplica.
  • market_specific_data_id: datos específicos de mercado o red; varía según el programa.

Preguntas frecuentes

¿Qué pasa si no tengo el pvv?

Procesamos la migración igual, pero regeneramos nuevos PINs para todas las tarjetas afectadas. Tus tarjetahabientes deberán configurar un PIN nuevo después de la migración, desde la app o un ATM.

¿Puedo enviar el pan en texto plano?

No. Debe estar encriptado bajo HSM o tokenizado. Si necesitas ayuda con el proceso de encriptación, ponte en contacto con nosotros.

¿Qué formato debo usar para las fechas?

ISO-8601 en ambos casos: YYYY-MM-DD para fechas simples (por ejemplo, 2024-06-15) e ISO-8601 completo para timestamps (por ejemplo, 2024-06-15T14:30:45Z).

¿Necesito migrar todas las transacciones?

No. La mayoría de los clientes migra los últimos 180 días por si surgen contracargos. Si tienes dudas sobre el alcance, contáctanos antes de preparar los archivos.

¿Debo incluir transacciones reversadas?

Sí. Las reversiones y los ajustes son importantes para la auditoría y la conciliación. Las procesamos con el mti_type correspondiente (0420).

Pomelo AI

Asistente de inteligencia artificial para consultas sobre la API de Pomelo
¡Hola!¿Cómo puedo ayudarte hoy?
Formato para la migración