API Reference

Transferencia Manual Only Push

1. Descripción general

Este documento describe el flujo técnico de Transferencia Manual – OUT_ONLY_PUSH, en el cual Milio inicia una transferencia de fondos hacia un destino externo, delegando al sistema integrador la validación previa mediante un esquema Pull → Push.

El objetivo del flujo es permitir que el integrador valide y debite los fondos antes de que Milio ejecute el push definitivo.

2. Conceptos clave

  • Pull: Acción realizada por el sistema integrador para debitar o validar los fondos del origen.

  • Push: Transferencia de fondos ejecutada por Milio hacia el destino final.

  • Webhook: Mecanismo de notificación utilizado para intercambiar eventos y decisiones entre Milio y el integrador.

  • Estados de transacción:

    • PENDING: Milio espera respuesta del integrador.
    • FAILED: La transacción fue cancelada o falló.
    • COMPLETED: La transacción finalizó exitosamente.

3. Flujo funcional

  1. El integrador inicializa el SDK de Milio.

  2. El usuario completa la información de la transferencia en el SDK.

  3. Al seleccionar Enviar dinero, Milio:

    • Crea la transacción en estado PENDING.
    • Envía un webhook al integrador solicitando validación (Pull).

  4. El integrador responde el webhook indicando si la transacción es APPROVED o REJECTED.

  5. Según la respuesta:

    • REJECTED o timeout → Milio cancela la transacción.
    • APPROVED → Milio ejecuta el push de fondos.

4. Inicialización del SDK

Para habilitar el flujo OUT_ONLY_PUSH, el SDK debe inicializarse utilizando el 10. Transferencia Solo Push

**.

Referencia:

⚠️

Toda la información enviada al SDK debe estar previamente encriptada.

Estructura requerida

{
  "thirdUUID": "uuid",
  "webhook": "https://...",
  "amount": 10000,
  "idExtern": "random-uuid-generated",
  "type": "OUT_ONLY_PUSH",
  "descriptionPaymentMethod": "Mi cuenta principal"
}

Notas:

  • descriptionPaymentMethod es opcional.
  • Este campo se utiliza únicamente para mostrar una descripción del origen de fondos en el SDK (ej. Mi cuenta principal, Billetera), si este campo no es enviado, al cliente se le mostrará Mi cuenta principal.

Cuando se reciben los parámetros de entrada el SDK abre una ventana interactiva para que el usuario pueda completar la transferencia de dinero. Los detalles del proceso, como el monto y la cuenta receptora, se gestionan automáticamente, proporcionando una experiencia de usuario fluida y segura.


5. Webhook de solicitud de validación (Pull)

Cuando el usuario confirma la transferencia, Milio envía al integrador un webhook con la información de la transacción en estado PENDING.

Payload enviado por Milio

{
  "webhook_type": "OUT_ONLY_PUSH",
  "message": "Operación completada con éxito.",
  "data": {
    "id": "uuid-transfer",
    "idExtern": "idExtern",
    "amount": 100000,
    "currency": "USD",
    "descriptionPaymentMethod": "Mi cuenta principal",
    "destination": {
      "accountNumber": "0009",
      "nameCardHolder": "P***** C*****",
      "cardIssuer": "VISA"
    },
    "date": "2025-10-21T19:14:10.426Z",
    "status": "PENDING",
    "service": "OUT_ONLY_PUSH",
    "actionRequired": "PULL"
  }
}

Mientras la transacción se encuentre en estado PENDING, Milio queda a la espera de la respuesta del integrador.

Si no se recibe respuesta dentro del tiempo configurado para validación, la transacción será cancelada automáticamente.

6. Respuesta del integrador

Luego de ejecutar el Pull, el integrador debe responder a Milio indicando el resultado de la validación.

Payload de respuesta

{
  "webhook_type": "OUT_ONLY_PUSH",
  "message": "Operación completada con éxito.",
  "data": {
    "id": "uuid-transfer",
    "idExtern": "idExtern",
    "status": "APPROVED",
    "service": "OUT_ONLY_PUSH"
  }
}

Valores permitidos para status

  • APPROVED: Milio continúa con la ejecución del push.
  • REJECTED: Milio cancela la transacción.

7. Escenarios posteriores

7.1 Aprobación y ejecución del Push

7.1.1 Fallo en la ejecución del Push (OCT)

Si el retiro de fondos (PULL) fue realizado exitosamente, pero al realizar el envío de los fondos (PUSH) falla, Milio notifica al integrador indicando que debe realizar el reverse correspondiente:

{
  "webhook_type": "OUT_ONLY_PUSH",
  "message": "Operación completada con éxito.",
  "data": {
    "id": "uuid-transfer",
    "idExtern": "idExtern",
    "amount": 100000,
    "currency": "USD",
    "descriptionPaymentMethod": "Mi cuenta principal",
    "destination": {
      "accountNumber": "0009",
      "nameCardHolder": "P***** C*****",
      "cardIssuer": "VISA"
    },
    "date": "2025-10-21T19:14:10.426Z",
    "status": "FAILED",
    "service": "OUT_ONLY_PUSH",
    "actionRequired": "REVERSE",
    "metadata": {
      "errorCode": "1234",
      "errorMessage": "Banco rechazó la transacción"
    }
  }
}

7.1.2 Push exitoso

Si la transferencia se ejecuta correctamente, Milio envía la confirmación final:

{
  "webhook_type": "OUT_ONLY_PUSH",
  "message": "Operación completada con éxito.",
  "data": {
    "id": "TRX_147b2c11-c86a-41c0-a31d-fb6cdf4eb7bc",
    "idExtern": "idExtern",
    "amount": 100000,
    "currency": "USD",
    "descriptionPaymentMethod": "Mi cuenta principal",
    "destination": {
      "accountNumber": "0026",
      "nameCardHolder": "D***** C*****",
      "cardIssuer": "VISA"
    },
    "date": "2025-10-21T19:14:10.426Z",
    "status": "COMPLETED",
    "type": "FT",
    "service": "OUT_ONLY_PUSH"
  },
  "metadata": {
    "useCase": "PUSH",
    "pushTransactionIdentifier": 2641611075639,
    "pushApproveCode": "9365701161462"
  }
}

8. Consideraciones finales

  • El integrador es responsable de ejecutar el Pull y responder oportunamente los webhooks.
  • Milio ejecutará el Push únicamente cuando la transacción haya sido aprobada.
  • En escenarios de fallo, el integrador debe ejecutar los procesos de Reverse según corresponda.