Ir al contenido

Cobro con QR (Nequi)

POST /v1/co/payin/qr

Genera un código QR para que el usuario pague escaneándolo desde su app Nequi. El estado final se confirma vía webhook.

Request body

{
  "amount": 50000,
  "reference": "orden-8842"
}

Campo	Tipo	Requerido	Descripción
`amount`	`number`	✅	Monto en pesos COP enteros (> 0)
`reference`	`string`	❌	Tu referencia interna (vuelve como `txIdSource` en Transacciones)
`expirationMinutes`	`number`	❌	Vigencia del cobro en minutos: entero de `1` a `60` (default `45`)

Response `201 Created`

{
  "txId": "9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
  "status": "PENDING",
  "qrCode": "<payload del QR>",
  "qrImage": "data:image/png;base64,...",
  "expiresAt": "2026-06-01T10:45:00.000Z",
  "amount": 50000,
  "currency": "COP",
  "estimatedFees": {
    "feeClient": 1500,
    "feeBase": 1261,
    "iva": 239,
    "netAmount": 48500,
    "currency": "COP"
  }
}

Campo	Descripción
`txId`	ID único de la transacción
`qrCode`	Payload del QR (para renderizar con cualquier librería QR)
`qrImage`	Data URI completo del QR, listo para usar tal cual en `<img src="{qrImage}">`. No le antepongas ningún prefijo ni asumas el tipo MIME. Puede no venir: en ese caso renderiza el QR desde `qrCode`
`expiresAt`	Hora en que vence el cobro (según `expirationMinutes`)
`estimatedFees.feeClient`	Fee total que se te cobrará (base + IVA, en pesos COP)
`estimatedFees.netAmount`	Monto neto que recibirás en tu balance

Consultar estado

GET /v1/co/payin/qr/{txId}

Misma semántica que el estado del cobro push: si sigue PENDING, la consulta sincroniza contra Nequi en el momento. Estados posibles: PENDING, COMPLETED, FAILED, EXPIRED.

Un pago por un monto distinto al del cobro no cierra la transacción: queda PENDING con amountMismatch: { expected, paid, underReview } para revisión manual. No acredites el pedido con amountMismatch presente: no hay webhook payin.completed y el balance no se movió. El equipo de Rivopay resuelve el caso; repórtalo con el txId.