# 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 QuickPay. **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 [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 |
| `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 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 |

## 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 |

## 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) |