Ir al contenido

Dispersión (Nequi)

POST /v1/co/payout/disburse

Envía dinero a un celular Nequi. La operación es síncrona: si Nequi responde OK, el dinero ya salió y la transacción queda cerrada en la misma respuesta, con amount + feeCharged debitado de tu balance disponible.

Request body

{
  "phoneNumber": "3009876543",
  "amount": 30000,
  "reference": "retiro-551",
  "description": "Pago a proveedor"
}

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

Response `201 Created`

{
  "externalId": "b4f6d2f0-6a1e-4c9b-9d3a-2f8e7c6b5a41",
  "status": "COMPLETED",
  "providerTxId": "NEQUI-DISB-4421",
  "amount": 30000,
  "feeCharged": 800,
  "totalDebit": 30800,
  "currency": "COP"
}

Campo	Descripción
`externalId`	ID generado por Rivopay — guárdalo para consultar el estado
`status`	`COMPLETED` — la dispersión ya se ejecutó
`providerTxId`	ID de la dispersión en Nequi
`feeCharged`	Fee cobrado (en pesos COP)
`totalDebit`	Total debitado de tu balance (`amount + feeCharged`)

Consultar estado

GET /v1/co/payout/{externalId}

{
  "externalId": "b4f6d2f0-6a1e-4c9b-9d3a-2f8e7c6b5a41",
  "status": "COMPLETED",
  "amount": 30000,
  "currency": "COP",
  "feeCharged": 800,
  "failureReason": null,
  "createdAt": "2026-06-01T10:00:00.000Z",
  "updatedAt": "2026-06-01T10:02:00.000Z"
}

Estados posibles: COMPLETED, PROCESSING (dispersión enviada, pendiente de confirmación) y FAILED — en cuyo caso se libera el hold y failureReason explica el motivo. Este endpoint solo devuelve dispersiones Nequi; los pagos Bre-B se consultan en /v1/co/breb/payout/{externalId}.

Lo normal es que la creación ya devuelva COMPLETED y no necesites consultar. Usa este GET para conciliación, o cuando se cortó la conexión antes de recibir la respuesta.

Errores

Código	Causa
`400`	`phoneNumber` inválido, `amount` faltante / no entero, o falta `X-Idempotency-Key` (`IDEMPOTENCY_KEY_REQUIRED`)
`402`	Saldo insuficiente — la respuesta incluye `availableBalance` y `requiredAmount`
`403`	Servicio Nequi no habilitado, o producción no habilitada para tu cuenta
`409`	Onboarding incompleto — contacta con soporte
`422`	Monto fuera de los límites de tu cuenta, o Nequi rechazó la operación (llega `code` + mensaje mapeado, ej. celular sin cuenta Nequi)
`502`	Nequi no disponible — reintenta
`503`	Servicio temporalmente suspendido para tu cuenta

{
  "error": "Insufficient balance",
  "availableBalance": 15000,
  "requiredAmount": 30800,
  "currency": "COP"
}