Información extra (metadata)

Ripei te deja adjuntar pares clave/valor libres a tus registros para que los webhooks lleguen con los identificadores que tu sistema ya usa. Así mapeas cada evento a tu base de datos sin llamadas adicionales.

Hay dos mecanismos independientes, y puedes usar los dos a la vez:

Mecanismo	Se configura en	Dónde llega en el webhook
Metadata del cliente	Cada cliente (`metadata`)	Aplanado en el nivel raíz del JSON
Metadata del método de pago	Cada método de pago (`integrationMetadata`)	Aplanado dentro de cada pago

Metadata del cliente

Responde a “¿de quién es este evento?”. Guarda aquí el identificador que tu sistema le da a esa persona.

Se define al crear o actualizar un cliente, en el campo metadata, y también puedes cargarlo masivamente con la columna metadata de la plantilla de Excel (escribiendo un JSON válido en la celda).


{ "metadata": { "idClienteERP": "CLI-00042" } }

Sus llaves suben al primer nivel del payload, junto a bill, payments y companyUser:


{
  "idClienteERP": "CLI-00042",
  "bill": { "id": 9902, "amount": 25, "status": "PAID" },
  "payments": [ … ],
  "companyUser": { "id": 4275 }
}

Metadata del método de pago

Responde a “¿por dónde entró la plata?”. Guarda aquí el código con el que tu contabilidad identifica ese método (tu cuenta contable, el código del banco, el canal, etc.).

Se configura desde el dashboard, en Métodos de pago → editar el método → sección Información para integraciones. Cada método tiene su propio juego de llaves.

Sus llaves se aplanan dentro del objeto de cada pago, junto a amount y paymentMethodName:


{
  "payments": [
    {
      "id": 830,
      "amount": 25,
      "reference": "11111111",
      "validatedAt": "2026-08-10T14:22:05.000Z",
      "paymentMethodId": 19,
      "paymentMethodName": "Pago Móvil",
      "codigoContable": "PM-01",
      "banco": "0105"
    }
  ]
}

Va dentro del pago —y no en la raíz— porque una factura puede recibir varios pagos con métodos distintos: así cada uno llega con el código que le corresponde, sin pisarse.

No se envían los datos de la cuenta. Cada método de pago guarda además los datos con los que tu cliente te paga (banco, teléfono, cédula y, en métodos con tarjeta, los datos de la tarjeta). Esa información nunca sale en un webhook: solo viajan las llaves que tú defines en Información para integraciones.

Reglas comunes

Aplican igual a los dos mecanismos.

Regla	Detalle
Tipos de valor	`string`, `número` o `boolean`. Desde el dashboard todos se guardan como texto.
Nombres de llave	Libres. Usa exactamente los que tu sistema espera recibir.
Actualización	Es reemplazo total, no fusión: lo que envías sustituye al objeto completo.
Borrar	Envía un objeto vacío `{}`.
Sin metadata	No se agrega ninguna llave extra al payload.

Colisiones de llaves. Si usas una llave que ya existe en el payload (por ejemplo amount o id), tu valor gana y sobrescribe el original — el metadata es libre y manda. Para evitar sorpresas, prefija tus llaves (erpAmount, idClienteERP) en vez de reutilizar nombres del payload.

Buenas prácticas

Guarda en el cliente el identificador de la persona, y en el método de pago el código contable del canal. Con esos dos datos casi siempre puedes asentar el pago automáticamente.
Usa nombres de llave estables: si los cambias, tu receptor deja de encontrarlos.
Prefija tus llaves para no chocar con los campos del payload.
Revisa el resultado real con el evento de prueba desde el dashboard antes de salir a producción.