Reversos y reaplicaciones

Después de que una transferencia se settlea, la conciliación de cierre del Banco de la República (BanRep) todavía puede ajustarla. Hay dos resultados:

• Reverso — una operación que parecía exitosa en realidad no se completó en el destino (o fue devuelta), por lo que se reversa. Un pago entrante reversado que pertenece a un recaudo se revierte: su intento pasa de successful a reversed, se recalculan el paid_amount y los contadores del recaudo, y el recaudo puede reabrirse.
• Reaplicación — una operación marcada como failed en realidad se settleó tarde, por lo que se reaplica. Un pago entrante reaplicado settlea el intento que se había finalizado como fallido: pasa de failed a successful y se acredita al recaudo.

En producción estos resultados vienen del archivo de conciliación diario. El sandbox te permite replicar cualquiera de los dos resultados sobre una de tus propias transferencias para verificar que tu integración maneja los webhooks resultantes. Estos endpoints solo están disponibles en el entorno sandbox.

Prerrequisitos

Necesitas una transferencia existente y su end_to_end_id:

• Para reversar, la transferencia debe estar en un estado reversable (successful o reapplied). Para un recaudo, primero simula un pago de recaudo exitoso.
• Para reaplicar, la transferencia debe estar en estado failed. Para un recaudo, primero simula un pago con un error para que el intento quede finalizado como fallido.

El end_to_end_id se devuelve en la respuesta de la simulación de intento de recaudo y está presente en todos los payloads de webhook collection.attempt_* e incoming_transfer.*.

Simulando un reverso

Envía un POST para reversar la transferencia que coincide con el end_to_end_id:

curl -X POST \
  https://breb-participant.sandbox.mono.la/api/v1/sandbox/transfers/{end_to_end_id}/reverse \
  -H "Authorization: Bearer <access_token>"

Recibes una respuesta 202 Accepted describiendo el resultado aplicado:

{
  "end_to_end_id": "20260527345544001ENT177994036665555",
  "direction": "incoming",
  "state": "reversed",
  "state_reason": "reversed_by_banrep",
  "result": "applied"
}

Unos segundos después, los webhooks se entregan a tu URL configurada. Para un pago entrante reversado que pertenece a un recaudo recibes:

• collection.attempt_reversed — el intento que estaba successful ahora está reversed.
• collection.updated — se recalcularon el paid_amount, los contadores y el estado del recaudo.

Simulando una reaplicación

Envía un POST para reaplicar la transferencia fallida que coincide con el end_to_end_id:

curl -X POST \
  https://breb-participant.sandbox.mono.la/api/v1/sandbox/transfers/{end_to_end_id}/reapply \
  -H "Authorization: Bearer <access_token>"

Recibes una respuesta 202 Accepted:

{
  "end_to_end_id": "20260527345544001ENT177994036665555",
  "direction": "incoming",
  "state": "reapplied",
  "state_reason": "reapplied_by_banrep",
  "result": "applied"
}

Para un pago entrante reaplicado que pertenece a un recaudo recibes:

• collection.attempt_successful — el intento que estaba failed ahora está successful.
• collection.updated — se recalcularon el paid_amount, los contadores y el estado del recaudo.

Ver la referencia de webhooks de recaudo para los payloads completos.

Campos de la respuesta

Errores

Flujo esperado

1. Crea una transferencia sobre la cual actuar (p. ej. simula un pago de recaudo).
2. Toma su end_to_end_id de la respuesta de simulación o de un webhook.
3. Llama al endpoint sandbox de reverse o reapply con ese end_to_end_id.
4. La API responde con 202 Accepted y el resultado aplicado.
5. Tras un breve delay, los webhooks collection.* se entregan a tu URL configurada.