Ir al contenido

Dispersión (Nequi)

POST /v1/co/payout/disburse

Envía dinero a un celular Nequi. Al crear la dispersión se retiene amount + feeCharged de tu balance disponible; al completarse se debita definitivamente, y si falla se libera.

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": "PROCESSING",
  "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 y para reversos
`status`	Estado inicial (`PROCESSING`)
`providerTxId`	ID de la dispersión en Nequi
`feeCharged`	Fee cobrado (en pesos COP)
`totalDebit`	Total retenido 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: PROCESSING, COMPLETED, FAILED. Si falló, failureReason explica el motivo.

Errores

Código	Causa
`400`	`phoneNumber` inválido o `amount` faltante / no entero
`402`	Saldo insuficiente — la respuesta incluye `availableBalance` y `requiredAmount`
`403`	Servicio Nequi no habilitado, o producción no habilitada para tu cuenta
`422`	Monto fuera de los límites de tu cuenta, o Nequi rechazó la operación
`502`	Nequi no disponible — reintenta
`503`	Servicio temporalmente suspendido para tu cuenta

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