Pagos con Terminal (Tap to Phone)

Tap to Phone convierte un teléfono Android en una terminal contactless — sin hardware POS dedicado. Una única app de Android, construida sobre el SDK de Migo, usa el lector NFC del teléfono para aceptar pagos con tarjeta presente y se conecta a la plataforma de pagos de Migo para aceptar también pagos alternativos (sin tarjeta) desde el mismo dispositivo.

info

La app es solo para Android. La lectura de tarjetas corre en el NFC del dispositivo a través del SDK de Migo; los pagos alternativos los maneja la plataforma de Migo.

Cómo funciona el módulo — de un vistazo

1. Crear el lead (prospecto de negocio)     POST /leads   ──►  devuelve un invitationCode
        │
        ▼
2. Registrar al owner con ese código         POST /users   { deviceId, invitationCode, ... }
        │   aprovisiona en una sola llamada:  usuario · business · sucursal · terminal · métodos de pago
        ▼
3. Activar la terminal
        ├─ Tarjeta presente   tras verificación de información + alta con el procesador adquiriente
        └─ Pagos alternativos activación instantánea
        │
        ▼
4. Cobrar y liquidar         vehículo de liquidación: tarjeta · balance · cuenta bancaria   (T+1 o lo acordado)

Agregar más usuarios después (admin / cashier):  POST /users/invitation-code → nuevo código → POST /users

1. Crear el lead

Un lead captura el prospecto de negocio y los métodos de pago que ofrecerá (rieles de tarjeta más rieles alternativos) y el producto SDK a habilitar. Crear el lead devuelve un invitationCode — lo usas directamente para registrar al owner en el paso 2 (no hay un paso de generación de código aparte para el owner).

curl -X POST https://api.ali.app/rest/leads \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Tienda de Ejemplo",
    "commercialName": "Tienda de Ejemplo",
    "firstName": "Example",
    "lastName": "Owner",
    "country": "GT",
    "paymentMethods": [
      { "slug": "akisiQR", "acquirerSlug": "akisi" }
    ],
    "sdk": "MIGO_LINK_USD"
  }'

Respuesta — el lead se devuelve con su invitationCode:

{
  "success": true,
  "data": {
    "_id": "...",
    "invitationCode": "25DC4D1"
  }
}

Consulta Leads para la referencia completa de campos y la respuesta.

2. Registrar al owner

Registra al owner con el invitationCode devuelto por el lead. Esta única llamada aprovisiona el usuario, business, sucursal y terminal, y asigna los métodos de pago declarados en el lead.

curl -X POST https://api.ali.app/rest/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "device-0000",
    "invitationCode": "25DC4D1",
    "username": "owner@example.com",
    "password": "<password>",
    "confirmPassword": "<password>",
    "termsAndConditionsAccepted": true
  }'

Respuesta — el envelope estándar con el usuario creado bajo data:

{ "success": true, "data": { } }

Consulta Gestión del titular para la referencia completa de registro.

3. Agregar usuarios admin o cashier (opcional)

El owner se registra con el código que devuelve el lead. Para agregar usuarios admin o cashier a la misma sucursal, genera un nuevo código de invitación con POST /users/invitation-code y haz que el nuevo usuario se registre con él (paso 2). Estos usuarios son extensiones del owner — no repiten el onboarding del negocio.

curl -X POST https://api.ali.app/rest/users/invitation-code \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: <user-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": 24,
    "role": "cashier"
  }'

Campo	Tipo	Notas
`branchId`	number	La sucursal a la que se limita la invitación
`role`	string	`admin` o `cashier`

Respuesta — el código de invitación generado:

{
  "success": true,
  "data": { "invitationCode": "B1685DA" }
}

El nuevo usuario luego se registra con ese invitationCode exactamente como en el paso 2.

Activación de la terminal

El cobro con tarjeta presente se habilita tras la verificación de información y el alta con el procesador adquiriente. Hasta entonces, la terminal no puede correr transacciones con tarjeta.
Los pagos alternativos se activan de forma instantánea — la terminal puede aceptarlos en cuanto se registra el usuario.

Liquidación

Los pagos capturados por la terminal se liquidan al vehículo de liquidación asociado al negocio. El vehículo puede ser una tarjeta, el balance o una cuenta bancaria. La liquidación ocurre uno o más días después del cobro (T+1+), o según el calendario acordado con tu contacto comercial.

Roles

Rol	Onboarding	Notas
`owner`	Onboarding completo (información personal + del negocio), una sola vez	Siempre requerido — el negocio no puede existir sin un owner
`admin`	Ninguno	Extensión opcional del owner; no se solicita información personal/del negocio
`cashier`	Ninguno	Extensión opcional del owner; no se solicita información personal/del negocio

admin y cashier se agregan emitiendo códigos de invitación adicionales con el role correspondiente — reutilizan el onboarding que el owner ya completó.

Múltiples terminales por sucursal

Una sucursal puede correr más de una terminal. Registra dispositivos adicionales bajo la misma sucursal para agregar terminales.

Páginas de referencia

Visión general — modelo de hardware, procesadores y liquidación
Instalación del SDK — aprovisiona un dispositivo para una sucursal
Flujo de transacción — el flujo de pago con terminal
Cancelar una transacción — actualiza el estado de un pago con terminal

Cómo funciona el módulo — de un vistazo​

1. Crear el lead​

2. Registrar al owner​

3. Agregar usuarios admin o cashier (opcional)​

Activación de la terminal​

Liquidación​

Roles​

Múltiples terminales por sucursal​

Páginas de referencia​