API Reference

Open Link (Cross Border) Only Pull

1. Descripción general

Este documento describe el flujo técnico de Open link Crossborder – OPEN_LINK_ONLY_PULL, mediante el cual Milio permite realizar una Recarga de fondos a través de una solicitud de dinero internacional iniciando con las construcción de un enlace que el usuario proporciona a la persona que va a enviar el dinero (el cual se encuentra en otro país), luego de ingresar toda la información y proceder con el envío, Milio inicia con un Pull desde el medio de pago del usuario y delegando al sistema integrador la ejecución del Push hacia el 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.
  • CrossBorder: Indica transacción internacional.

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, se genera el link y lo proporciona a la persona que enviará el dinero (otro país).

  3. El usuario que enviará el dinero, ingresa la información en el SDK (mediante un Link Web).

  4. Al seleccionar Continuar, Milio ejecuta el Pull de fondos.

  5. 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.

  6. El integrador responde indicando el resultado del Push.

  7. 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 OPEN_LINK_ONLY_PULL, el SDK debe inicializarse utilizando el 12. Open Link Crossborder 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": "OPEN_LINK_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 ingresar toda la información y dar click en Continuar, 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": "OPEN_LINK_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": "OPEN_LINK_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": "OPEN_LINK_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": "OPEN_LINK_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": "OPEN_LINK_ONLY_PULL",
  "message": "Operación completada con éxito.",
  "data": {
    "id": "uuid-transfer",
    "idExtern": "idExtern",
    "status": "APPROVED",
    "service": "OPEN_LINK_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": "OPEN_LINK_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": "OPEN_LINK_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": "OPEN_LINK_ONLY_PULL",
  "message": "Operación completada con éxito.",
  "data": {
    "id": "uuid-transfer",
    "idExtern": "idExtern",
    "status": "RECEIVED",
    "service": "OPEN_LINK_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.