> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Medianet

> Cobra una tarjeta en un pinpad Medianet desde el kiosco Android con @fire-spark/payments-medianet-pinpad-rn.

Medianet es el pinpad de los kioscos de Fire spark en Ecuador. Un pago del dashboard es un botón del checkout. El pinpad está en la LAN del local. El cliente lo usa y el kiosco espera la respuesta.

| | |
| - | - |
| Países | Ecuador |
| Monedas | USD |
| Estado | Disponible |
| Paquete | `@fire-spark/payments-medianet-pinpad-rn` |

Solo kiosco Android. POS, web e iOS no usan este paquete.

Los paquetes son públicos en el SDK `0.12.5`. Entran a npm en el próximo release. Un canal de este repositorio los depende con `workspace:*`.

Sigue las secciones de abajo para integrarlo a mano. Para dárselo a un agente, copia el prompt de [Prompt para un agente](#prompt-para-un-agente).

## Requisitos

* Un kiosco Android con development build. Expo Go no carga el módulo nativo.
* Un pinpad Medianet en la LAN del local.
* `CajaPinPadLibrary_V3.jar` (WPOSS), fuera de git. Medianet licencia el JAR.

> [!WARNING]
>
> No subas el JAR ni una IP, un MID, un TID o un cajero de producción. El template del kiosco es público.

## Activarlo

1. En el dashboard, abre el comercio, entra a **Payments** y crea un pago con el proveedor **Medianet** y el método **PIN pad**. El nombre del pago es el texto del botón del checkout. Ver [Botón del checkout](#botón-del-checkout).
2. En **Connection Settings**, completa:

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| Merchant ID (MID) | `merchant_id` | No | Obligatorio. Lo comparten los pinpads, salvo que una tienda o un dispositivo lo pise |

3. En **Store settings**, completa cada tienda que necesite otro MID. Vacío significa el MID del pago. La API le entrega al kiosco solo la fila de su tienda.

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| Merchant ID (MID) | `merchant_id` | No | Opcional. Pisa el MID del pago para esta tienda |

4. En cada kiosco, abre el dispositivo y la pestaña **Payments**. Los valores viven en `settings_overrides.payment_settings`, con el id del pago como clave. Ver [Configurar un dispositivo](https://firespark.cloud/docs/es/guides/payments/configure-a-device.md).

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| IP del pinpad | `terminal_ip` | No | Obligatoria. Dirección en la LAN |
| Puerto TCP | `terminal_port` | No | Obligatorio |
| Id de terminal (TID) | `terminal_id` | No | Obligatorio. 8 caracteres |
| Id de cajero (CID) | `cashier_id` | No | Obligatorio. El secuencial del lote usa sus últimos 2 caracteres |
| Merchant ID (MID) | `merchant_id` | No | Opcional. Pisa el del pago y el de la tienda |
| Timeout del pinpad (segundos) | `timeout_s` | No | Opcional. Timeout del socket. Por defecto 90. Nunca menos de 60 |
| Máscara de red | `network_mask` | No | Opcional. Solo para la configuración del pinpad |
| Gateway | `gateway` | No | Opcional. Solo para la configuración del pinpad |

El MID se resuelve así: dispositivo, luego tienda, luego pago.

> [!NOTE]
>
> Un pago al que le falta `terminal_ip`, `terminal_port`, `terminal_id`, `cashier_id` o un MID no llega al kiosco, así que su botón no aparece en el checkout. En el listado de dispositivos, la columna **Payments** muestra lo que sigue vacío. Un dispositivo también puede ocultar un pago con `disabled_payment_ids`.

## Botón del checkout

Cada pago Medianet es un botón. El template del kiosco ya pinta una tarjeta por pago a partir de `services.payments.list` (`CheckoutPaymentMethodCard`). No agregas un componente de botón ni una ilustración.

* El texto es `payment.name`. Si el pago no tiene nombre, la tarjeta usa el nombre del método.
* La imagen es la ilustración de tarjeta. `paymentInstructionKind` devuelve `"card"` para todo pago `PIN_PAD`, y el texto debajo es `checkout.method.cardHint` ("Débito o crédito en el datáfono"). Medianet no tiene `modalities`, así que la tarjeta nunca se trata como Pix y el cliente no elige débito o crédito en el kiosco. Eso lo hace el pinpad.
* Débito y crédito son el mismo botón. Un segundo pago Medianet es una segunda tarjeta, con su nombre y sus datos de dispositivo.

## Usarlo en el SDK

Agrega los dos paquetes a la app del kiosco. No forman parte del template público. Fíjalos a la misma versión que `@fire-spark/payments`.

```bash theme={null}
pnpm add @fire-spark/payments-medianet-pinpad-rn@0.12.5 @fire-spark/payments-medianet-client@0.12.5
```

`@fire-spark/payments-medianet-client` es el módulo Android y el config plugin de Expo. `@fire-spark/payments-medianet-pinpad-rn` es el adaptador. Cobra con el adaptador. No abras un socket ni armes tramas.

En `app.config.ts`:

```typescript theme={null}
export default {
  plugins: [
    [
      "@fire-spark/payments-medianet-client",
      { binariesDir: process.env.MEDIANET_BINARIES_DIR }
    ]
  ]
};
```

`binariesDir` es absoluta o relativa a la raíz de la app. Apúntala a una carpeta fuera de git:

```text theme={null}
binaries/
  CajaPinPadLibrary_V3.jar
```

Después genera el proyecto Android y corre un development build:

```bash theme={null}
MEDIANET_BINARIES_DIR=/ruta/al/jar npx expo prebuild --platform android --clean
npx expo run:android --device
```

El plugin copia el JAR a `android/app/libs/`, lo agrega al `build.gradle` de la app y pide el permiso de internet. El prebuild se detiene con `[medianet] missing ...` si falta el JAR. `medianet.available`, de `@fire-spark/payments-medianet-client`, es `true` cuando el plugin está en el build.

Regístralo una vez por pedido, con el almacenamiento del dispositivo. Pasa `storage` siempre: ahí queda el lote del día (`medianet:control:v1`) y la cola de reversos. Sin él, el pinpad puede volver a pedir la apertura del lote y se pierde un reverso pendiente. El adaptador ya usa el cliente compartido. No crees otro.

```typescript theme={null}
import AsyncStorage from "@react-native-async-storage/async-storage";
import { medianetPinPadPayments } from "@fire-spark/payments-medianet-pinpad-rn";

const deviceStorage = {
  get: (key: string) => AsyncStorage.getItem(key),
  set: (key: string, value: string) => AsyncStorage.setItem(key, value),
  remove: (key: string) => AsyncStorage.removeItem(key)
};

order.setPaymentAdapters([
  medianetPinPadPayments({ storage: deviceStorage })
]);

order.setPaymentOptions({
  isProduction: merchant.env_is_prod,
  collectAt: "KIOSK",
  deviceSettings: kioskConfig.overrides.payment_settings,
  deviceId: kioskConfig.device.id
});
```

`kioskConfig` es lo que devuelve `getKioskConfig`. Los valores del dispositivo llegan en `overrides.payment_settings`. Las fechas de la trama usan `America/Guayaquil`, salvo que pases `timeZone`.

`order.getMissingPaymentFields(payment)` lista los campos del dispositivo que siguen vacíos. La API ya oculta un pago incompleto. Usa el helper en la pantalla de administración del kiosco cuando quieras mostrar lo que falta.

## Aviso de espera

El adaptador no dibuja nada. Manda una sola línea, en español, mientras el pinpad trabaja:

```typescript theme={null}
{ text: "Siga las instrucciones en el pinpad", kind: "waiting" }
```

El UI de pagos por defecto ignora `message`. No hay `select`, `input`, `confirm` ni QR. Implementa `message` solo cuando esa línea deba verse en el kiosco:

```typescript theme={null}
order.setPaymentUI({
  message: ({ text }) => setTerminalMessage(text)
});
```

## Cobrar

Cobra el pago que eligió el cliente:

```typescript theme={null}
await order.setTenders([
  {
    method: "PIN_PAD",
    provider: "medianet",
    payment_id: payment.id,
    collect_at: "DEVICE",
    allocation: null
  }
]);

const result = await order.payIntent({
  onProgress: progress => render(progress)
});
```

`payIntent({ payment })` igual coloca un tender. Para partir Medianet con otro método, llama a `setTenders` con una asignación y después a `payIntent()`. Ver [Usar pagos en el SDK](https://firespark.cloud/docs/es/guides/payments/use-payments-in-the-sdk.md).

El primer cobro del día manda la trama de apertura del lote (`PC`) una sola vez. Si esa trama falla, no hay cobro. Una venta se aprueba solo cuando el pinpad y el autorizador responden `00`. El monto va en centavos; el adaptador lo arma.

El plazo del cobro es de 300 segundos. Cubre el `PC` del día, la venta y un reverso. Deja `runtime.timeout_ms` sin definir para conservar ese plazo. Un valor en el pago lo reemplaza, así que pon `300000` o más. Para subir el valor por defecto del adaptador, pasa `timeoutMs`:

```typescript theme={null}
medianetPinPadPayments({ storage: deviceStorage, timeoutMs: 300_000 });
```

Para el texto usa `formatPaymentError` de `@fire-spark/payments`. No reintentes un resultado `AMBIGUOUS`.

## Qué ve el cliente

El botón de tarjeta y después el pinpad. El kiosco no dibuja una pantalla de pinpad ni muestra un QR. Con `PAID`, sigue el pedido. El código de autorización, la marca, los últimos 4, el secuencial (`reference`), el lote, el id de terminal y el id de comercio están en `result.metadata.payment`. El kiosco no los guarda por su cuenta.

| Resultado | Qué hace el kiosco |
| - | - |
| `PAID` | Sigue con el pedido |
| `FAILED` con `CARD_DECLINED` | Ofrece reintentar u otro método |
| `FAILED` con `TERMINAL_UNAVAILABLE`, `TIMEOUT` o `NETWORK_ERROR` | El pinpad no tomó el cobro. Reintenta solo si `error.retryable` es true |
| `AMBIGUOUS` (`metadata.needs_review`) | No reintentes. La tarjeta puede haberse leído. El adaptador manda un reverso cuando el resultado quedó desconocido y hay número de autorización. Manda al cliente al mostrador |

## Inicio del turno y configuración del pinpad

Llama a esto desde la pantalla de administración, nunca durante un cobro. El adaptador las corre de a una.

Al abrir el turno, abre el lote del día. Manda `PC` aunque el día ya esté abierto. `start` también manda `PC` una vez por día si el turno no lo hizo:

```typescript theme={null}
await order.runPaymentTerminal(payment, "open_batch");
```

Responde `Medianet batch <batch> open`.

Escribe la red del pinpad (IP, máscara, gateway, puerto) solo cuando se guardan esos valores. Manda `CP` y después `PC`, y exige `network_mask` y `gateway`:

```typescript theme={null}
await order.runPaymentTerminal(payment, "init");
```

Responde `Medianet pinpad configured`. Si faltan la máscara o el gateway, lanza `Medianet is missing network_mask, gateway`. El cobro no necesita esos dos campos.

Prueba de enlace, salud del módulo nativo y reversos pendientes:

```typescript theme={null}
await order.runPaymentTerminal(payment, "test");
await order.runPaymentTerminal(payment, "status");
await order.runPaymentTerminal(payment, "retry_pending_reversals");
```

`test` responde `Medianet link OK (hash valid)` o `Medianet link OK (hash invalid)`. `retry_pending_reversals` responde `Reverses and voids completed: N, pending: M`.

No hay cierre de lote del pinpad. El cierre del día queda en el sistema de la tienda. No hay consulta de la última transacción. No armes las tramas.

## Webhooks

Ninguno.

## Anulaciones

`order.cancel()` anula un pedido que no se entregó. `order.refund()` reembolsa uno que sí. Una venta aprobada se anula en el pinpad (`03`). Un resultado desconocido se reversa (`04`). Una anulación es `REFUNDED` solo cuando el pinpad y el autorizador responden `00`.

| Resultado | Qué hace el kiosco |
| - | - |
| `REFUNDED` o `CANCELLED` | La anulación terminó |
| `PAID` con `needs_review` y un error reintentable | La anulación quedó en cola. Dile al cliente que vaya al mostrador. Desde la pantalla de administración del kiosco, corre `order.runPaymentTerminal(payment, "retry_pending_reversals")` |
| `PAID` con `MANUAL_REVERSAL_REQUIRED` | A la anulación le falta el secuencial o la autorización. Resuélvela fuera del kiosco |
| `FAILED` con `REVERSAL_NOT_ALLOWED` | El cobro ya está pagado, así que un cancel no puede reversarlo. Anúlalo con `order.refund()` |

## Errores comunes

| Código Spark | Código del proveedor | Qué hacer |
| - | - | - |
| `INVALID_REQUEST` | `01` | El pinpad rechazó la trama. Revísalo con Medianet |
| `TERMINAL_UNAVAILABLE` | `02`, `ER` | El pinpad no respondió, o falló el `PC` del día. Revisa la IP, el puerto y que el pinpad esté en la LAN. Ver [Activarlo](#activarlo) |
| `PROVIDER_UNAVAILABLE` | `20`, `91` | Error de proceso del pinpad (`20`), o el emisor no está disponible (`91`, reintentable) |
| `TIMEOUT` | `TO` | Se acabó el timeout del socket, o el plazo de 300 segundos. Deja `runtime.timeout_ms` sin definir, o ponlo en `300000` o más |
| `CARD_DECLINED` | `12`, `57` y cualquier otro código del autorizador | El autorizador rechazó. Ofrece reintentar u otro método |
| `INSUFFICIENT_FUNDS` | `51` | Ofrece otro método |
| `FRAUD_SUSPECTED` | `59` | No reintentes |
| `TERMINAL_NOT_CONFIGURED` | — | Faltan datos de la tienda o del dispositivo. Revisa [Activarlo](#activarlo) |
| `NETWORK_ERROR` | — | La trama no salió del kiosco. Reintenta si `error.retryable` es true |
| `AMBIGUOUS` | — | El resultado quedó desconocido. No reintentes el cobro. Ver [Errores de pago](https://firespark.cloud/docs/es/guides/payments/errors.md) |

## Compatibilidad

| `@fire-spark/payments-medianet-pinpad-rn` | Proveedor | `@fire-spark/payments` |
| - | - | - |
| 0.12.5 | Medianet, Android | Misma versión que `@fire-spark/payments-medianet-client` |

## Prompt para un agente

Pega esto en el agente que edita la app del kiosco. Cubre solo Medianet. Las secciones de arriba son el mismo trabajo, escrito para una persona.

```text title="Prompt de integración" theme={null}
Integra solo el pinpad Medianet en esta app de kiosco Android de Fire spark. No agregues ningún otro proveedor de pagos. No agregues este paquete a POS, web ni iOS.

Medianet cobra una tarjeta en un pinpad de la LAN del local, en Ecuador (USD). Un pago del dashboard es un botón del checkout. El template del kiosco ya pinta una tarjeta por pago a partir de services.payments.list (CheckoutPaymentMethodCard). No crees un componente de botón nuevo ni agregues una ilustración.

El texto es payment.name, o el nombre del método si el pago no tiene nombre. paymentInstructionKind devuelve "card" para PIN_PAD, y el texto de ayuda es checkout.method.cardHint ("Débito o crédito en el datáfono"). Medianet no tiene modalidades. No lo trates como Pix y no agregues un selector de débito o crédito. El pinpad elige. Un segundo pago Medianet es una segunda tarjeta.

Paquetes, fijados a la misma versión que @fire-spark/payments. Son públicos en el SDK 0.12.5 y entran a npm en el próximo release. Dentro de este repositorio, dependelos con workspace:*:
- @fire-spark/payments-medianet-pinpad-rn@0.12.5 (adaptador)
- @fire-spark/payments-medianet-client@0.12.5 (módulo Android y config plugin de Expo)

Cobra solo con medianetPinPadPayments. No llames al cliente nativo, no abras un socket y no armes tramas LT, CP, PC ni PP. No agregues una consulta de la última transacción. No cierres el lote del pinpad. No existe terminal.closeBatch. El cierre del día queda en el sistema de la tienda.

Setup nativo:
- Expo Go no carga el módulo. Usa un development build.
- En app.config.ts agrega el plugin ["@fire-spark/payments-medianet-client", { binariesDir: process.env.MEDIANET_BINARIES_DIR }].
- El JAR se queda fuera de git (licencia de Medianet). La carpeta tiene CajaPinPadLibrary_V3.jar. No commitees el JAR ni una IP, un MID, un TID o un cajero de producción.
- Genera Android con MEDIANET_BINARIES_DIR definido: npx expo prebuild --platform android --clean, y después npx expo run:android --device.
- El plugin copia el JAR a android/app/libs/, lo agrega al build.gradle de la app y pide el permiso de internet. El prebuild se detiene con "[medianet] missing ..." si falta el JAR.
- medianet.available, de @fire-spark/payments-medianet-client, es true cuando el plugin está en el build.

Regístralo una vez por pedido. Pasa siempre el almacenamiento del dispositivo (AsyncStorage). Ahí queda el lote del día (medianet:control:v1) y la cola de reversos. Sin él, el pinpad puede volver a pedir la apertura del lote después de un reinicio, y se pierde un reverso pendiente. No crees otro cliente de Medianet. El adaptador ya usa el compartido.

import AsyncStorage from "@react-native-async-storage/async-storage";
import { medianetPinPadPayments } from "@fire-spark/payments-medianet-pinpad-rn";

const deviceStorage = {
  get: (key: string) => AsyncStorage.getItem(key),
  set: (key: string, value: string) => AsyncStorage.setItem(key, value),
  remove: (key: string) => AsyncStorage.removeItem(key)
};

order.setPaymentAdapters([
  medianetPinPadPayments({ storage: deviceStorage })
]);

order.setPaymentOptions({
  isProduction: merchant.env_is_prod,
  collectAt: "KIOSK",
  deviceSettings: kioskConfig.overrides.payment_settings,
  deviceId: kioskConfig.device.id
});

kioskConfig es lo que devuelve getKioskConfig. Los valores del dispositivo llegan en overrides.payment_settings. Las fechas de la trama usan America/Guayaquil, salvo que pases timeZone.

El adaptador no dibuja nada. Manda un solo ui.message: { text: "Siga las instrucciones en el pinpad", kind: "waiting" }. El UI de pagos por defecto ignora message. No implementes select, input, confirm ni un QR. Implementa message solo cuando esa línea deba verse en el kiosco.

Cobra el pago que eligió el cliente:

await order.setTenders([{
  method: "PIN_PAD",
  provider: "medianet",
  payment_id: payment.id,
  collect_at: "DEVICE",
  allocation: null
}]);
const result = await order.payIntent({ onProgress: progress => render(progress) });

El primer cobro del día manda la trama de apertura del lote (PC) una sola vez. Si esa trama falla, no hay cobro. Una venta se aprueba solo cuando el pinpad y el autorizador responden 00. El adaptador arma el monto en centavos.

El plazo del cobro es de 300 segundos (PC del día, venta y un reverso). Deja runtime.timeout_ms sin definir. Si lo defines, usa 300000 o más. Sube el valor por defecto del adaptador con medianetPinPadPayments({ storage: deviceStorage, timeoutMs: 300_000 }).

Muestra los errores con formatPaymentError de @fire-spark/payments.

Resultados:
- PAID: sigue con el pedido. El código de autorización, la marca, los últimos 4, el secuencial (reference), el lote, el id de terminal y el id de comercio están en result.metadata.payment. No los guardes por tu cuenta. No hay un comprobante del cliente para imprimir.
- FAILED CARD_DECLINED: ofrece reintentar u otro método.
- FAILED TERMINAL_UNAVAILABLE, TIMEOUT o NETWORK_ERROR: reintenta solo si error.retryable es true.
- AMBIGUOUS (metadata.needs_review): no reintentes. La tarjeta puede haberse leído. El adaptador manda un reverso cuando el resultado quedó desconocido y hay número de autorización. Manda al cliente al mostrador.

Inicio del turno y administración, nunca durante un cobro. El adaptador las corre de a una:
- order.runPaymentTerminal(payment, "open_batch") al abrir el turno. Manda PC aunque el día ya esté abierto. Responde "Medianet batch <batch> open". start también manda PC una vez por día si el turno no lo hizo.
- order.runPaymentTerminal(payment, "init") solo cuando se guarda la red del pinpad. Exige network_mask y gateway. Responde "Medianet pinpad configured". Lanza "Medianet is missing network_mask, gateway" si falta alguno. El cobro no necesita esos dos campos.
- order.runPaymentTerminal(payment, "test") responde "Medianet link OK (hash valid)" o "Medianet link OK (hash invalid)".
- order.runPaymentTerminal(payment, "status") devuelve la salud del módulo nativo.
- order.runPaymentTerminal(payment, "retry_pending_reversals") responde "Reverses and voids completed: N, pending: M".

Anulaciones: order.cancel() si el pedido no se entregó, order.refund() si se entregó. Una venta aprobada se anula en el pinpad (03). Un resultado desconocido se reversa (04). REFUNDED solo cuando el pinpad y el autorizador responden 00.
- REFUNDED o CANCELLED: la anulación terminó.
- PAID con needs_review y un error reintentable: la anulación quedó en cola. Desde la pantalla de administración del kiosco corre order.runPaymentTerminal(payment, "retry_pending_reversals").
- PAID con MANUAL_REVERSAL_REQUIRED: falta el secuencial o la autorización. Una persona lo resuelve fuera del kiosco.
- FAILED con REVERSAL_NOT_ALLOWED: el cobro ya está pagado, así que un cancel no puede reversarlo. Anúlalo con order.refund().

Errores a manejar: INVALID_REQUEST (01), TERMINAL_UNAVAILABLE (02, ER; también un PC del día que falló), PROVIDER_UNAVAILABLE (20, o 91 cuando el emisor no está disponible y es reintentable), TIMEOUT (TO; socket o el plazo de 300 segundos), CARD_DECLINED (12, 57 y cualquier otro código del autorizador), INSUFFICIENT_FUNDS (51), FRAUD_SUSPECTED (59; no reintentes), TERMINAL_NOT_CONFIGURED (faltan datos), NETWORK_ERROR (la trama no salió del kiosco), AMBIGUOUS (no reintentes el cobro).

Los valores del dashboard los llena una persona; no los inventes. Proveedor Medianet, método PIN pad. Config del pago: merchant_id (MID obligatorio). Por tienda, merchant_id opcional. Por kiosco, settings_overrides.payment_settings[paymentId]: terminal_ip, terminal_port, terminal_id (8 caracteres) y cashier_id son obligatorios. merchant_id opcional pisa el del pago y el de la tienda. timeout_s opcional, por defecto 90 y nunca menos de 60. network_mask y gateway solo son obligatorios para init. La precedencia del MID es dispositivo, luego tienda, luego pago. El secuencial del lote usa los últimos 2 caracteres de cashier_id. Un pago al que le faltan los datos obligatorios del dispositivo o un MID no aparece en el checkout. disabled_payment_ids del dispositivo también lo oculta. order.getMissingPaymentFields(payment) lista lo que sigue vacío.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.