# Glosario de campos

## Enlace de pago

| Campo | Tipo | Qué es |
|---|---|---|
| `id` | texto (UUID) | Identificador del cobro. Guárdalo junto a tu pedido |
| `url` | texto | Dónde paga tu cliente |
| `wa_deeplink` | texto o `null` | Reservado para abrir el cobro en el WhatsApp de ePlaza. **Hoy llega en `null`**: para mandarle el cobro a tu cliente usa `url` |
| `qr_png` | texto o `null` | QR de `wa_deeplink` (imagen PNG en `data:` URL). **Hoy llega en `null`** |
| `comercio` | texto | El código de tu comercio |
| `monto` | número | Monto en bolívares que pide el cobro. No cambia aunque tu cliente agregue propina |
| `propina` | número | Propina que agregó tu cliente al pagar, en bolívares (`0` si no agregó). Sólo aparece si activaste propinas en el portal → [Propinas](/developers/propinas) |
| `total` | número | Lo que se le debitó a tu cliente: `monto` + `propina`. Sin propina es igual a `monto` |
| `moneda` | texto | `VES` |
| `concepto` | texto | Lo que ve tu cliente al pagar |
| `estado` | texto | `pendiente`, `cobrando`, `procesando`, `revision`, `pagado`, `expirado` o `cancelado` → [Estados](/developers/ciclo-de-vida) |
| `expires_at` | fecha (ISO, UTC) | Cuándo vence |
| `paid_at` | fecha (ISO, UTC) | Cuándo se pagó |
| `txn_id` | texto | Id de la transacción del pago |
| `created_at` | fecha (ISO, UTC) | Cuándo se creó |
| `metadata` | objeto | Tus datos (al crear) |
| `success_url` | texto | A dónde vuelve el cliente (al crear) |
| `failure_url` | texto | A dónde vuelve el cliente si el pago no puede continuar: el cobro venció, lo cancelaste o él elige "Cancelar y volver" tras un rechazo (al crear). → [Volver a tu web](/developers/volver-a-tu-web) |
| `idempotency_key` | texto | Tu llave para no duplicar (al crear) |
| `mode` | texto | `test` o `live`: el ambiente del cobro. Viene en la respuesta de crear y dentro de `data` en los avisos `link.pagado` y `link.acreditado` |
| `codigo_verificacion` | texto | Código del comprobante (`QP-XXXXX-XXXXX`) de un cobro `pagado`. Quien lo reciba puede comprobar en [eplaza-qa-pay.pagaconquickpay.com/verificar](/developers/enlaces-de-pago#verificar-un-comprobante) que el comprobante es auténtico. Viene al consultar o listar un enlace pagado (`null` en los demás estados) y dentro de `data` en el aviso `link.pagado`. Es `null` si por ahora no se pudo generar |
| `pagador` | objeto | Lo que sabemos de quien pagó. Hoy trae sólo `alta_cliente` |
| `alta_cliente` | sí/no | Dentro de `pagador`. `true` si quien paga marcó en la página de pago "Quiero ser cliente de *tu comercio* y recibir sus novedades" (la casilla viene desmarcada). Con el cobro `pagado`, esa persona aparece en **Clientes** del portal → [Página de pago](/developers/enlaces-de-pago#quiero-ser-cliente). No trae su cédula, teléfono ni nombre |
| `idempotent_replay` | sí/no | `true` cuando repetiste la creación con la misma `idempotency_key` y te devolvemos el enlace que ya existía |
| `split` | lista | Sólo en enlaces con [pago dividido](/developers/pago-dividido) (piloto): las reglas del reparto que mandaste al crearlo. Viene al crear y al consultar el enlace |
| `donacion` | objeto | Sólo en enlaces con [donación](/developers/donaciones) (piloto): `donataria` (código de la fundación), `nombre`, `monto` (Bs que van a la fundación, sin comisión), `estado` (`pendiente`, `pagada`, `en_revision` o `descartada`) y `referencia_bancaria` (de la transferencia a la fundación, sólo `pagada`). Viene al crear y al consultar el enlace y dentro de `data` en los avisos `link.pagado` y `link.acreditado`. `monto` del enlace ya la incluye |
| `reparto` | objeto o `null` | Sólo en enlaces con pago dividido: al consultar el enlace, `null` hasta que el pago se liquida y después lo que se llevó cada cuenta (`estado`: `pendiente`, `repartido`, `en_revision` o `cerrado`; `monto_comercio`, `monto_repartido`, `beneficiarios`). También dentro de `data` en el aviso `link.acreditado` → [Pago dividido](/developers/pago-dividido#ver-el-reparto) |

## Respuesta de `POST /links/:id/simular` (sólo cobros de prueba)

| Campo | Qué es |
|---|---|
| `id` | El `id` del cobro |
| `estado` | Estado en que queda el cobro: `pagado`, `pendiente` o `expirado` |
| `resultado` | Lo que pediste simular: `pagado`, `rechazado` o `expirado` |
| `simulado` | Siempre `true` |

## Respuesta de `POST /links/:id/cancelar`

| Campo | Qué es |
|---|---|
| `id` | El `id` del cobro |
| `estado` | `cancelado` |

## Aviso `link.pagado` (campo `data`)

| Campo | Qué es |
|---|---|
| `link_id` | El `id` del cobro |
| `txn_id` | Id de la transacción |
| `estado` | `pagado` |
| `monto`, `moneda`, `concepto` | Del cobro (`monto` es el del enlace, sin propina) |
| `propina` | Propina que agregó tu cliente (`0` si no agregó) |
| `total` | Lo debitado: `monto` + `propina` |
| `referencia` | Referencia del banco (`SIMULADO` en un cobro de prueba) |
| `mode` | `live` o `test`: si el pago fue de producción o simulado |
| `codigo_verificacion` | Código del comprobante, para que tu cliente (o tú) lo verifique en eplaza-qa-pay.pagaconquickpay.com/verificar |
| `pagador` | `{ "alta_cliente": true }` si quien pagó pidió ser tu cliente y recibir tus novedades; `false` si no |
| `metodo` | Sólo viene si tu cliente pagó con tarjeta (piloto): `"tarjeta"`. Sin este campo, el pago fue con débito inmediato → [Pagar con tarjeta](/developers/enlaces-de-pago#pagar-con-tarjeta-piloto) |
| `recargo_tarjeta` | Sólo con `metodo: "tarjeta"`: recargo por pago con tarjeta que pagó tu cliente además del `total`. No es tuyo ni se te liquida |
| `donacion` | Sólo en enlaces con [donación](/developers/donaciones): la fundación, el monto y su `estado` (normalmente `pendiente`: se transfiere cuando el banco confirma el pago) |

## Aviso `link.acreditado` (campo `data`)

| Campo | Qué es |
|---|---|
| `link_id` | El `id` del cobro |
| `txn_id` | Id del pago del cliente |
| `liquidacion_txn_id` | Id de la transferencia a tu cuenta |
| `monto_bruto` | Lo que pagó tu cliente (con la propina, si agregó una) |
| `comision` | Comisión descontada |
| `monto_acreditado` | Lo que llegó a tu cuenta |
| `estado` | `acreditado` |
| `moneda` | `VES` |
| `referencia_bancaria` | Referencia del banco de la transferencia a tu cuenta |
| `banco_destino` | Código del banco de tu cuenta |
| `referencia_cobro` | Referencia del banco del pago de tu cliente |
| `mode` | `live` o `test`: si la acreditación fue real o simulada |
| `reparto` | Sólo con [pago dividido](/developers/pago-dividido): lo que se llevó cada cuenta. En ese caso `monto_acreditado` es sólo tu parte |
| `donacion` | Sólo en enlaces con [donación](/developers/donaciones): la fundación, el monto y su `estado`. `monto_acreditado` nunca incluye la donación (`monto_bruto` sí) |

## Aviso `link.devuelto` (campo `data`, piloto)

| Campo | Qué es |
|---|---|
| `link_id` | El `id` del cobro que se devolvió |
| `devolucion_id` | Id de la devolución (un cobro puede tener varias devoluciones parciales) |
| `estado` | `completada`: el dinero salió hacia tu cliente |
| `monto` | Lo que se le devolvió a tu cliente en esta devolución |
| `monto_devuelto` | Lo devuelto en total de ese cobro, contando las devoluciones anteriores |
| `moneda` | `VES` |
| `referencia_bancaria` | Referencia del banco de la transferencia a tu cliente. Puede venir `null` |
| `mode` | `live` o `test`: si la devolución fue real o simulada |

## Avisos `transaccion.*` (campo `data`)

| Campo | Qué es |
|---|---|
| `id` | El `id` de la operación |
| `estado` | `LIQUIDADA` o `RECHAZADA` (con una llave de prueba, `ACEPTADA`) |
| `monto`, `moneda`, `concepto` | De la operación |
| `referencia` | Referencia del banco |
| `operacion` | De qué es: `cobro`, `pago`, `reverso`, `devolucion_debito`, `devolucion` o `devolucion_retorno` → [Webhooks](/developers/webhooks-referencia) |

## Respuesta de `GET /estado.json` (sin llave)

| Campo | Qué es |
|---|---|
| `generado_en` | Cuándo se midió (UTC). Se actualiza cada 30 segundos |
| `estado_general` | `operativo`, o `degradado` si alguna pieza del servicio o los cobros no están bien |
| `senales` | Cada pieza del servicio (`api`, `db`, `pago`, `banco`, `liquidacion`) con `nombre`, `nivel` (`ok`, `degradado`, `caido` o `info`) y `detalle` en palabras |
| `bancos` | Estado de los cobros con débito inmediato: `banco` (nombre de la fila), `estado` (`operativo`, `degradado`, `caido` o `sin_datos`) y `actualizado_en` (UTC) |
| `incidentes` | Incidentes de los últimos 7 días, el más reciente primero: `titulo`, `estado` (`en_curso` o `resuelto`), `inicio` (UTC, cuando lo abrimos) y `fin` (UTC, o `null` mientras sigue abierto) |
| `liquidacion_inmediata` | Si la liquidación inmediata está `habilitada`, su `ultimo_ciclo` y su `ultima_acreditacion` (UTC, o `null`) |
