Guía de integración - Recibir en Punto físico

Este flujo está diseñado para los casos en los que el sender (remitente del dinero) accede directamente a la plataforma para iniciar un envío internacional y transferir fondos a un receiver (beneficiario), quien recibirá el dinero de manera presencial en un punto físico autorizado.

1. Autenticación

Actualmente, se incluye un único endpoint que permite autenticar a un usuario o compañía mediante credenciales válidas. Al hacerlo, se generará un JWT (JSON Web Token), que deberá ser utilizado en las siguientes peticiones como medio de autenticación.

✅

Importante: El JWT debe ser incluido en el encabezado Authorization con el formato Bearer <token>.

Esto garantiza que las solicitudes futuras estén

Más información: Login- autenticación

2. Gestión de llaves criptográficas (obligatorio)

Después de completar la autenticación, es obligatorio realizar la generación y carga de llaves criptográficas para habilitar la comunicación segura con la plataforma de Milio.

Este paso se realiza una sola vez por empresa y es requisito previo para ejecutar cualquier flujo transaccional.

🚧

Importante: Sin la configuración de llaves, no será posible enviar información encriptada ni procesar transacciones.

Más información: Gestión de llaves para encriptación de datos

3. Registro del Remitente (si no existe)

Antes de realizar cualquier envío, tanto el remitente como el beneficiario deben estar previamente registrados en el sistema.

Durante este proceso:

• Se genera un identificador único (UUID) que debe ser almacenado por el integrador.

🚧

Este paso aplica tanto para el remitente como para el beneficiario.

Más información: documentación de registro de terceros

4. Registro de Tarjeta y tokenización (si no posee una)

Una vez registrado el tercero (remitente), podrá asociar un método de pago utilizando el SDK seguro de Milio, encargado de capturar y tokenizar los datos de la tarjeta conforme a los estándares de seguridad PCI-DSS.

La integración varía según la plataforma:

A. SDK Web (Escritorio y Navegadores Móviles)

Para integrar el widget web, se debe seguir el siguiente flujo secuencial de 3 pasos:

1. Generar Llave de Sesión (Key) Primero, el cliente del integrador debe solicitar una llave temporal para autorizar la carga del SDK.
   • Endpoint: POST /sdk-widget/create-enrollment
   • Caso de uso: CARD_REGISTRATION
   • Documentación: Generar key token
     Respuesta exitosa (HTTP 200): El servicio retornará un objeto JSON. Es vital capturar el valor de data.key, ya que es el token necesario para iniciar el SDK en el frontend.
2. Cargar la Librería del SDK Con el key obtenido, proceda a importar la librería JS de Milio en su frontend.
   • Guía: Cargar SDK
3. Inicializar (Levantar) el SDK Finalmente, utilice la función de inicialización inyectando el key del paso 1. Esto renderizará el formulario seguro para que el usuario ingrese su tarjeta.
   • Guía: Levantar SDK con la Key

B. SDK Móvil:

Para integraciones nativas, consulte la documentación específica de los componentes móviles.

• Link: Guía Tokenización de tarjeta (Móvil)

En este paso se genera un token temporal y se crea un identificador único del método de pago (senderBankUUID) que podrá reutilizarse posteriormente.

Nota: Al completar la tokenización, recibirá el estado del proceso en la URL del webhook configurado.

5. Registro del Beneficiario (si no existe)

Al igual que el remitente, quien recibirá el dinero debe estar registrado previamente en la plataforma como un Tercero.

El Alias es el Documento Para este flujo específico, al crear al tercero beneficiario, el valor asignado al campo alias DEBE corresponder estrictamente al Número de Documento de Identidad (Cédula) de la persona que retirará el dinero.

Más información: Documentación crear tercero

6. Cotización de Divisas (FX Quote)

Antes de realizar el envío, el usuario puede consultar el tipo de cambio para conocer:

• El valor exacto que recibirá el beneficiario en la moneda destino.
• La relación entre la moneda de origen y la moneda de destino.
• La tasa de conversión aplicada al momento de la transacción.

Endpoint:

POST /cross-border/fx-quote-v1

Este paso es clave para brindar transparencia y claridad al usuario antes de confirmar la operación.

Mas información: Documentación de divisas

Gestión de Comisiones

Para garantizar la rentabilidad del servicio, es necesario configurar previamente las reglas de cobro y consultarlas antes de cada transacción.

A. Creación o Actualización de Comisión (Setup)

Este paso permite definir las reglas de negocio respecto al cobro de comisiones. Las comisiones se pueden definir con flexibilidad por cliente/usuario y actualizarse dinámicamente.

Endpoint: POST /company-commission Documentación Crear/Actualizar Comisión

B. Consulta de Comisión (Transaccional)

Una vez configurada la comisión, y antes de confirmar el envío, el usuario debe consultar el valor exacto que se le aplicará.

Esto permite:

• Detallar el monto de la comisión al usuario final.
• Evitar sorpresas al momento de la confirmación del pago.

Endpoint: GET /company-commission Documentación Listar Comisiones

Más información general: Modelos de cobro y parametrización

7. Creación y ejecución de la transacción

En este paso se valida toda la información recopilada previamente y se ejecuta la transacción de envío de dinero.

Aquí es donde el sistema:

• Verifica que el sender exista y tenga una tarjeta tokenizada activa.
• Valida que el recipientDocument corresponda a un beneficiario registrado.
• Ejecuta el débito al remitente y deja la transacción lista para retiro en punto físico.

Endpoint:

POST /sdk-widget/create-transaction

Caso de uso: PULL_PHYSICAL_POINT

Ejemplo de payload:

JSON

{
  "recipientDocument": "123456789", 
  "senderUUID": "uuid-del-sender",
  "senderBankUUID": "uuid-del-sender-bank",
  "webhook": "url-del-webhook",
  "reference": "reference",
  "idExtern": "id-externo",
  "type": "PULL_PHYSICAL_POINT",
  "exchange": {
    "sourceCurrencyCode": "USD",
    "destinationCurrencyCode": "COP",
    "sourceAmount": 100
  }
}

Donde:

• recipientDocument: Debe ser el número de documento del beneficiario.
• senderUUID: Identificador único del remitente.
• senderBankUUID: Identificador del método de pago tokenizado del sender.
• webhook: URL donde se notificará el resultado final de la operación.
• type: Debe tener el valor PULL_PHYSICAL_POINT, lo que indica que el beneficiario recibirá el dinero en un punto físico.
• idExtern Identificar externo para la transacción
• exchange: Información del pago.

🚧

Importante: El sender debe haber sido creado previamente y debe contar con una tarjeta tokenizada válida.