Open Link Only Pull(CrossBorder)

En esta sección se detallan las diferentes etapas, parámetros de entrada y estructuras de payload para el flujo de Open Link Only Pull (CrossBorder).

Este flujo está diseñado para escenarios donde un usuario local solicita dinero a una persona en el extranjero a través de un enlace de cobro personalizado. Una vez generado, el enlace se comparte con el pagador en el exterior, quien al abrirlo accede a un portal web para ingresar sus datos personales, seleccionar su método de pago y autorizar el envío de fondos.

En esta arquitectura de procesamiento:

Milio ejecuta el cobro o débito de los fondos (Pull) desde la cuenta o tarjeta de origen en moneda extranjera (ej. USD).
El Integrador recibe una notificación vía Webhook tras un Pull exitoso para realizar el abono o depósito final (Push) en la cuenta de destino en moneda local (ej. COP).

Asimismo, esta documentación especifica la gestión de eventos asíncronos, las solicitudes de comisión dinámica (customCommission) y la reversión automática de fondos (REVERSED) en caso de que ocurra un fallo durante la ejecución del Push.

Parámetros del Payload

thirdUUID (string, Requerido): Identificador único del tercero asociado.
thirdBankUUID (string, Requerido): Identificador único de la cuenta o tarjeta destino asociada.
webhook (string, Requerido): URL donde se recibirán las notificaciones de eventos e historial del enlace.
type (string, Requerido): Tipo de operación en el SDK (ej. "OPEN_LINK_ONLY_PULL").
expirationSeconds (number, Opcional): Tiempo de vida del enlace expresado en segundos.
isReusable (boolean, Opcional): Define si el enlace permite múltiples cobros (true) o un único cobro (false).
customCommission (boolean, Opcional): Define si la comisión se calcula de forma dinámica vía webhook (true) o si aplica la tarifa por defecto del sistema (false).
linkId (string, Requerido para actualización): Identificador único del Open Link previamente generado.
amount (number, Opcional/Requerido en actualización): Monto numérico asociado al cobro/pago.
currency (string, Opcional/Requerido en actualización): Código ISO de la moneda de la transacción (ej. "COP").
reference (string, Opcional): Descripción o nota asociada a la solicitud de pago.

Casos de Uso y Ejemplos de Payloads

1. Iniciación de Open Link (Solicitud Base)

Este paso genera la solicitud inicial y crea un enlace de cobro genérico junto con su código QR base.

Petición (POST): /cross-border/v2/link

JSON de ejemplo (Request):

{  
  "thirdUUID": "uuid-tercero",  
  "thirdBankUUID": "uuid-tarjeta",  
  "webhook": "https://mi-webhook-notificacion.com",  
  "type": "OPEN_LINK_ONLY_PULL",  
  "expirationSeconds": 3600,  
  "isReusable": false,
  "customCommission":false
}

JSON de ejemplo (Response):

{  
  "error": 0,  
  "code": "ML000",  
  "category": "GENERAL",  
  "message": "Operación completada con éxito.",  
  "messageEn": "Operation completed successfully.",  
  "data": {  
    "id": "6ed4f1a5-f3e7-4504-b398-59a2d7890a3f",  
    "link": "https://mi-portal-remesas.com/3e09ceb1",  
    "cardNumber": "*********1238",  
    "franchise": "VISA",  
    "alias": "KB1784"  
  }  
}

2. Asignación de Monto y Concepto (Actualización de Enlace)

Se parametriza el valor específico a recibir (amount), la moneda (currency) y una descripción u opcionalmente concepto del pago.

Petición (PUT): /cross-border/v2/link

JSON de ejemplo (Request):

{  
  "linkId": "{{link-id}}",  
  "amount": 500000,  
  "currency": "COP",  
  "reference": "Regalo de cumpleaños 🎁"  
}

JSON de ejemplo (Response):

{  
  "error": 0,  
  "code": "ML000",  
  "category": "GENERAL",  
  "message": "Registro actualizado con éxito.",  
  "messageEn": "Operation completed successfully.",  
  "data": {  
    "link": "https://mi-portal-remesas.com/3e09ceb1",  
    "amount": 500000,  
    "currency": "COP"  
  }  
}