Reversos (Nequi)

Revierte una transacción Nequi completada (cobro push, cobro QR o dispersión). El reverso se crea como una nueva transacción (subType: NEQUI_REVERSAL) que puedes seguir por webhook o en Transacciones.

Requisitos

La transacción original debe estar en estado COMPLETED — cualquier otro estado responde 409.
Un cobro QR solo es reversable si registra un pago (Nequi debe reportar el celular del pagador); un QR sin pago responde 409.

Reverso de Pay-In

POST /v1/co/payin/{txId}/reversal

Usa el txId devuelto al crear el cobro (push o QR).

Reverso de Pay-Out

POST /v1/co/payout/{externalId}/reversal

Usa el externalId devuelto al crear la dispersión.

Request body

{ "reason": "customerRequest" }

Campo	Tipo	Requerido	Descripción
`reason`	`string`	✅	Motivo: `customerRequest`, `bankError`, `fraud` o `cashierError`

El reverso siempre es por el monto total de la transacción original.

Response `201 Created`

{
  "txId": "7c2e91d4-5b3a-4f8e-9d16-a0b1c2d3e4f5",
  "originalTxId": "3f9f0c2a8b414f0e9a1d2c3b4a5e6f70",
  "status": "PROCESSING",
  "amount": 50000,
  "currency": "COP"
}

Campo	Descripción
`txId`	ID de la nueva transacción de reverso
`originalTxId`	ID de la transacción original reversada
`status`	Estado inicial del reverso (`PROCESSING`)

Errores

Código	Causa
`400`	`reason` faltante o fuera del enum
`403`	Producción no habilitada para tu cuenta
`404`	Transacción original no encontrada
`409`	La transacción original no está `COMPLETED`, o el QR no registra un pago
`422`	Nequi rechazó el reverso