Casos de uso de Dispersiones

Una transferencia saliente es cómo tu negocio envía dinero por Bre-B: nombras a un destinatario por su llave de pago (o un target ya resuelto), Mono enruta los fondos y los webhooks siguen el resultado. El mismo endpoint cubre un pago único a un vendedor, un reembolso verificado o un lote de cientos — lo que cambia es la configuración. Esta página lista los escenarios comunes y los campos a definir para cada uno.

Lee primero Llaves de pago y Targets si estos términos son nuevos. Los montos están en centavos (1 COP = 100 centavos).

Antes de empezar

Necesitarás:

• Una cuenta tenant con fondos (tenant_account_id) desde la cual enviar.
• Un endpoint de webhook para eventos de transferencia y de resolución de target — ve Payloads de webhooks.
• Familiaridad con el ciclo de vida de la transferencia saliente y la referencia de errores.

Cómo una transferencia nombra a su destinatario

Cada transferencia en el arreglo transfers identifica a su destinatario de una de dos formas:

• Por llave — un query que Mono resuelve por ti: { "query": { "value": "3001234567" } }. La transferencia pasa por target_resolved antes de liquidarse.
• Por target — un target_id que ya resolviste (ve UC-OT4 abajo): { "target_id": "bbtgt_..." }. Esto omite el paso de resolución.

Opcionalmente agrega expected_creditor (document_type + document_number) para rechazar la transferencia si el dueño resuelto no coincide.

UC-OT1 — Pago a vendedor (una transferencia)

Paga a un vendedor por su llave. Un lote de un solo ítem sigue siendo un lote.

{
  "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj",
  "description": "Pago a vendedor — pedido ORD-9931",
  "transfers": [
    {
      "query": { "value": "@MNVENDEDOR1" },
      "amount": { "amount": 8000000, "currency": "COP" },
      "external_id": "payout-ORD-9931"
    }
  ]
}

8000000 centavos = $80,000 COP. La transferencia recorre la máquina de estados completa created → processing → target_resolved → ... → successful, emitiendo webhooks en cada paso. Este es el pago que completa un split de marketplace.

UC-OT2 — Reembolso a cliente (verificación de identidad)

Devuelve fondos a una persona específica, rechazando el pago si la llave ahora pertenece a alguien más. Agrega expected_creditor.

{
  "query": { "value": "3001234567" },
  "amount": { "amount": 5000000, "currency": "COP" },
  "expected_creditor": { "document_type": "CC", "document_number": "1023711432" },
  "external_id": "refund-INV-552"
}

Si el dueño resuelto coincide, la transferencia se liquida. Si no, falla con target_creditor_mismatch — ve los errores de validación de destinatario. En sandbox, fuerza el mismatch con la llave sandbox@key_target_creditor_mismatch.err.

UC-OT3 — Split post-venta (lote)

Paga a varios destinatarios desde una venta liquidada, mezclando tipos de llave en un solo lote. Combínalo con el recaudo de split de marketplace: lee las reglas de split del webhook collection.paid, y luego envía.

{
  "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj",
  "description": "Split del pedido ORD-9931",
  "transfers": [
    {
      "query": { "value": "@MNVENDEDOR1" },
      "amount": { "amount": 8000000, "currency": "COP" },
      "external_id": "split-1-vendor"
    },
    {
      "query": { "value": "@MNPLATFORM" },
      "amount": { "amount": 1000000, "currency": "COP" },
      "external_id": "split-2-platform"
    },
    {
      "query": { "value": "shipping@logistics.com" },
      "amount": { "amount": 500000, "currency": "COP" },
      "external_id": "split-3-shipping"
    }
  ]
}

Cada transferencia se sigue de forma independiente por su external_id; que una falle no revierte las demás.

UC-OT4 — Pre-resolución (resolver → confirmar → transferir)

Cuando quieres que el pagador confirme al destinatario antes de mover dinero, resuelve la llave primero, muestra el nombre resuelto, y luego transfiere por target_id.

1. Resolver — llama a Resolver target con la llave.
2. Confirmar — muestra el nombre, banco y cuenta enmascarada devueltos a tu usuario.
3. Transferir — crea la transferencia con el target_id del paso 1 (sin query).

{
  "transfers": [
    {
      "target_id": "bbtgt_5tgliBmzjZ6mpQPRbQjfKj",
      "amount": { "amount": 12000000, "currency": "COP" },
      "external_id": "confirmed-transfer-1"
    }
  ]
}

Como el destinatario ya está resuelto, la transferencia omite target_resolved y pasa directo a la liquidación.

UC-OT5 — Pagos a proveedores en lote (resultados mixtos)

Un lote más grande donde algunas entradas tienen éxito y otras se rechazan. El response de creación devuelve las transferencias aceptadas y una lista rejected_transfers; las fallas de resolución (como una llave incorrecta) llegan después como webhooks outgoing_transfer.failed.

Maneja ambos: reconcilia el rejected_transfers síncrono (p. ej. amount_exceeds_max_limit, duplicados) y suscríbete a los webhooks de falla para los resultados por transferencia. Ve Manejo de transferencias rechazadas.

UC-OT6 — Todos los tipos de llave

Una transferencia puede apuntar a cualquiera de los cinco tipos de llave. Usa el formato correcto de query.value:

Mono resuelve cada una al mismo tipo de target; los datos resueltos que se muestran difieren por tipo.

UC-OT7 — Manejo de errores (sandbox)

Ejercita cada ruta de falla de forma determinista en sandbox antes de salir a producción:

• Errores de resolución — pon query.value en una llave de prueba como sandbox@key_not_found.err, sandbox@key_suspended.err o sandbox@key_target_creditor_mismatch.err.
• Errores de liquidación — codifica el disparador en el description de la transferencia (p. ej. timeout, control de riesgo, cuenta de acreedor no encontrada).
• Rechazos de creación — los requests malformados (sin monto, target desconocido, monto sobre el límite) se rechazan de forma síncrona sin webhooks.

La lista completa de códigos state_reason, sus significados y el manejo recomendado está en la referencia de errores de transferencias salientes. Recorre los disparadores de punta a punta en Sandbox: transferencias salientes.

Próximos pasos

• Casos de uso de Recaudo — el lado de recepción (y el split que alimenta a UC-OT3).
• Flujo de transferencia saliente — la secuencia de punta a punta y la máquina de estados.
• Sandbox: transferencias salientes — simula cualquier receta de arriba.