API Reference

Recarga de Billetera Only Pull

1. Descripción general

Este documento describe el flujo técnico de Recarga de Billetera – IN_ONLY_PULL, mediante el cual Milio permite realizar una recarga de fondos iniciando con un Pull desde el medio de pago del usuario y delegando al sistema integrador la ejecución del Push hacia la tarjeta o cuenta destino.

El flujo contempla mecanismos automáticos de reverso en caso de fallos o falta de confirmación por parte del integrador.

2. Conceptos clave

  • Pull: Débito de fondos ejecutado por Milio desde el medio de pago del usuario.
  • Push: Acreditación de fondos ejecutada por el sistema integrador.
  • Reverse: Operación de reverso ejecutada por Milio cuando el Push no es confirmado.
  • Webhook: Canal de comunicación para notificar eventos y recibir decisiones del integrador.

Estados de transacción

  • FAILED: La transacción falló y no continuó el flujo.
  • APPROVED: La operación fue validada exitosamente.
  • COMPLETED: La operación finalizó (incluye escenarios de reverso).

3. Flujo funcional

  1. El integrador inicializa el SDK de Milio.

  2. El usuario ingresa la información de la recarga en el SDK.

  3. Al seleccionar Recargar, Milio ejecuta el Pull de fondos.

  4. Según el resultado del Pull:

    • Fallo → Se finaliza la transacción y se notifica al integrador.
    • Éxito → Milio notifica al integrador para que ejecute el Push.

  5. El integrador responde indicando el resultado del Push.

  6. Según la respuesta:

    • APPROVED → La recarga se confirma exitosamente.
    • REJECTED o timeout → Milio ejecuta el Reverse automáticamente.

4. Inicialización del SDK

Para habilitar el flujo IN_ONLY_PULL, el SDK debe inicializarse utilizando el Caso 11. Recarga Solo Pull.

Referencia:

⚠️

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

Estructura requerida

 {
    "thirdUUID": "uuid",
    "webhook": "https://...",
    "idExtern": "random-uuid-generated",
    "type": "IN_ONLY_PULL",
    "descriptionPaymentMethod": "Mi cuenta principal"
  }
  • 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).

5. Ejecución del Pull

Al confirmar la recarga, Milio ejecuta el Pull sobre el medio de pago registrado como origen.

5.1 Fallo en el Pull

Si el Pull falla, la transacción se finaliza y Milio notifica al integrador mediante el siguiente webhook:

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

5.2 Pull exitoso

Si el Pull se ejecuta correctamente, Milio notifica al integrador para que proceda con el Push de fondos.

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

6. Respuesta del integrador (resultado del Push)

Luego de ejecutar el Push, el integrador debe responder a Milio indicando el resultado.

Payload de respuesta

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

Valores permitidos para status

  • APPROVED: La recarga se confirma exitosamente.
  • REJECTED: Milio ejecuta el reverso automáticamente.

7. Reverso automático

7.1 Rechazo o timeout del Push

Si el integrador responde REJECTED o no responde dentro del tiempo configurado, Milio ejecuta el Reverse y notifica al integrador:

{
  "webhook_type": "IN_ONLY_PULL",
  "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": "IN_ONLY_PULL"
  },
  "metadata": {
    "useCase": "REVERSED",
    "reverseTransactionIdentifier": 2641611075639,
    "reverseApproveCode": "9365701161462"
  }
}

7.2 Confirmación de recepción del Reverse

Luego del reverso, Milio queda a la espera de la confirmación del integrador:

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

8. Consideraciones finales

  • Milio ejecuta el Pull de manera síncrona al confirmar la recarga.
  • El integrador es responsable de ejecutar y confirmar el Push.
  • Ante fallos o ausencia de respuesta, Milio garantiza la consistencia mediante reversos automáticos.
  • Todos los eventos relevantes son notificados vía webhook.