Cobro Push (Nequi)

POST /v1/co/payin/push

Inicia un cobro enviando una notificación push al celular del usuario para que apruebe en su app Nequi. No requiere registrar al pagador previamente. El estado final se confirma vía webhook.

Request body

{
  "phoneNumber": "3001234567",
  "amount": 50000,
  "reference": "orden-8842",
  "description": "Compra tienda XYZ"
}

Campo	Tipo	Requerido	Descripción
`phoneNumber`	`string`	✅	Celular Nequi del pagador (10 dígitos)
`amount`	`number`	✅	Monto en pesos COP enteros (> 0)
`reference`	`string`	❌	Tu referencia interna (vuelve como `txIdSource` en Transacciones)
`description`	`string`	❌	Texto mostrado al usuario en su app

Response `201 Created`

{
  "txId": "3f9f0c2a8b414f0e9a1d2c3b4a5e6f70",
  "status": "PENDING",
  "providerTxId": "NEQUI-998877",
  "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 — guárdalo para consultas y webhooks
`status`	Estado inicial (`PENDING`)
`providerTxId`	ID de la transacción en Nequi
`estimatedFees.feeClient`	Fee total que se te cobrará (base + IVA, en pesos COP)
`estimatedFees.feeBase`	Componente base del fee
`estimatedFees.iva`	IVA del fee
`estimatedFees.netAmount`	Monto neto que recibirás en tu balance (`amount - feeClient`)

Consultar estado

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

Si la transacción sigue PENDING, esta consulta sincroniza contra Nequi en el momento: si el usuario ya aprobó, verás COMPLETED (y se dispara el webhook); si el cobro venció, verás EXPIRED.

{
  "txId": "3f9f0c2a8b414f0e9a1d2c3b4a5e6f70",
  "status": "COMPLETED",
  "amount": 50000,
  "currency": "COP",
  "description": "Compra tienda XYZ",
  "feeClient": 1500,
  "netAmount": 48500,
  "createdAt": "2026-06-01T10:00:00.000Z",
  "updatedAt": "2026-06-01T10:05:00.000Z"
}

Estados posibles: PENDING, COMPLETED, FAILED, CANCELLED, EXPIRED.

Cancelar cobro

POST /v1/co/payin/push/{txId}/cancel

Cancela un cobro push que aún está PENDING. Si la transacción ya está en otro estado, responde 409.

{ "txId": "3f9f0c2a8b414f0e9a1d2c3b4a5e6f70", "status": "CANCELLED" }

Errores

Código	Causa
`400`	`phoneNumber` inválido (no son 10 dígitos) o `amount` faltante / no entero
`403`	Servicio Nequi no habilitado, o producción no habilitada para tu cuenta
`409`	Cancelación sobre una transacción que ya no está `PENDING`
`422`	Monto fuera de los límites de tu cuenta, o Nequi rechazó la operación (incluye `code` con el motivo)
`502`	Nequi no disponible — reintenta
`503`	Servicio temporalmente suspendido para tu cuenta