> ## 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

> Charge a card on a Medianet pinpad from the Android kiosk with @fire-spark/payments-medianet-pinpad-rn.

Medianet runs the pinpad on Fire spark kiosks in Ecuador. One dashboard payment is one checkout button. The pinpad sits on the store LAN. The customer uses the pinpad; the kiosk waits for the answer.

| | |
| - | - |
| Countries | Ecuador |
| Currencies | USD |
| Status | Available |
| Package | `@fire-spark/payments-medianet-pinpad-rn` |

Android kiosk only. POS, web, and iOS do not use this package.

The packages are public in the SDK at `0.12.5`. They join npm on the next SDK release. A channel in this repository depends on them with `workspace:*`.

Follow the sections below to wire it by hand. To hand the same work to an agent, copy the prompt in [AI agent prompt](#ai-agent-prompt).

## Requirements

* An Android kiosk and a development build. Expo Go does not load the native module.
* A Medianet pinpad on the store LAN.
* `CajaPinPadLibrary_V3.jar` (WPOSS), kept outside git. Medianet licenses the JAR.

> [!WARNING]
>
> Do not commit the JAR or a production IP, MID, TID, or cashier id. The kiosk template is public.

## Activate it

1. In the dashboard, open the merchant, go to **Payments**, and create a payment with the provider **Medianet** and the method **PIN pad**. The payment name is the label on the checkout button. See [Checkout button](#checkout-button).
2. In **Connection Settings**, fill in:

| Field | Key | Secret | Notes |
| - | - | - | - |
| Merchant ID (MID) | `merchant_id` | No | Required. Shared by every store pinpad unless a store or a device overrides it |

3. In **Store settings**, fill in each store that needs a different MID. Leave it empty to keep the payment MID. The API sends the kiosk only its own store row.

| Field | Key | Secret | Notes |
| - | - | - | - |
| Merchant ID (MID) | `merchant_id` | No | Optional. Overrides the payment MID for this store |

4. On each kiosk, open the device and the **Payments** tab. Values live in `settings_overrides.payment_settings`, keyed by payment id. See [Configure a device](https://firespark.cloud/docs/guides/payments/configure-a-device.md).

| Field | Key | Secret | Notes |
| - | - | - | - |
| Pinpad IP address | `terminal_ip` | No | Required. LAN address of the pinpad |
| Pinpad TCP port | `terminal_port` | No | Required |
| Medianet terminal id (TID) | `terminal_id` | No | Required. 8 characters |
| Medianet cashier id (CID) | `cashier_id` | No | Required. The batch sequential uses its last 2 characters |
| Merchant ID (MID) | `merchant_id` | No | Optional. Overrides the payment and the store |
| Pinpad timeout (seconds) | `timeout_s` | No | Optional. Socket timeout. Default 90. Never under 60 |
| Pinpad network mask | `network_mask` | No | Optional. Required only for terminal init |
| Pinpad gateway | `gateway` | No | Optional. Required only for terminal init |

The MID resolves as device, then store, then payment.

> [!NOTE]
>
> A payment that is missing `terminal_ip`, `terminal_port`, `terminal_id`, `cashier_id`, or a MID never reaches the kiosk, so its button stays off the checkout. On the device list, the **Payments** column shows what is still empty. A device can also hide a payment with `disabled_payment_ids`.

## Checkout button

Each Medianet payment is one button. The kiosk template already renders one card per payment from `services.payments.list` (`CheckoutPaymentMethodCard`). You do not add a button component and you do not add an illustration.

* The label is `payment.name`. When the payment has no name, the card uses the method name.
* The picture is the card illustration. `paymentInstructionKind` returns `"card"` for every `PIN_PAD` payment, and the hint under the label is `checkout.method.cardHint` ("Debit or credit on the pin pad"). Medianet has no `modalities`, so the card is never treated as Pix and the customer does not pick debit or credit on the kiosk. The pinpad does that.
* Debit and credit are the same button. A second Medianet payment is a second card, with its own name and its own device fields.

## Use it in the SDK

Add both packages to the kiosk app. They are not part of the public template. Pin them to the same version as `@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` is the Android module and the Expo config plugin. `@fire-spark/payments-medianet-pinpad-rn` is the adapter. Charge through the adapter. Do not open a socket or build frames yourself.

In `app.config.ts`:

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

`binariesDir` is absolute, or relative to the app root. Point it at a folder outside git:

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

Then generate the Android project and run a development build:

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

The plugin copies the JAR into `android/app/libs/`, adds it to the app `build.gradle`, and adds the internet permission. Prebuild stops with `[medianet] missing ...` when the JAR is absent. `medianet.available` from `@fire-spark/payments-medianet-client` is `true` when the plugin is in the build.

Register the adapter once per order, with device storage. Pass `storage` every time: it keeps the day's batch (`medianet:control:v1`) and the reverse queue across restarts. Without it, the pinpad can ask to open the batch again, and a pending reverse is lost. The adapter already uses the shared client. Do not create another one.

```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` is what `getKioskConfig` returns. Device values arrive on `overrides.payment_settings`. Frame dates use `America/Guayaquil` unless you pass `timeZone`.

`order.getMissingPaymentFields(payment)` lists device fields that are still empty. The API already hides an incomplete payment. Use the helper on the kiosk admin screen when you want to show what is missing.

## Waiting message

The adapter draws nothing. It sends one line, in Spanish, while the pinpad works:

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

The default payment UI ignores `message`. There is no `select`, `input`, `confirm`, or QR. Implement `message` only when that line should appear on the kiosk:

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

## Charge

Charge the payment the customer picked:

```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 })` still places one tender. To split Medianet with another method, call `setTenders` with an allocation and then `payIntent()`. See [Use payments in the SDK](https://firespark.cloud/docs/guides/payments/use-payments-in-the-sdk.md).

The first charge of the day sends the batch-open frame (`PC`) once. If that frame fails, there is no charge. A sale is approved only when the pinpad and the authorizer both answer `00`. The amount is sent in cents; the adapter builds it.

The charge window is 300 seconds. It covers the daily `PC`, the sale, and a reverse. Leave `runtime.timeout_ms` unset to keep that window. A value on the payment replaces it, so set `300000` or higher. To raise the adapter default, pass `timeoutMs`:

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

Use `formatPaymentError` from `@fire-spark/payments` for the message. Do not retry an `AMBIGUOUS` result.

## What the customer sees

The card button, then the pinpad. The kiosk does not draw a pinpad screen and does not show a QR. On `PAID`, continue the order. Authorization code, brand, last 4, sequential (`reference`), batch, terminal id, and merchant id are on `result.metadata.payment`. The kiosk does not store them itself.

| Result | What the kiosk does |
| - | - |
| `PAID` | Continue the order |
| `FAILED` with `CARD_DECLINED` | Offer a retry or another method |
| `FAILED` with `TERMINAL_UNAVAILABLE`, `TIMEOUT`, or `NETWORK_ERROR` | The pinpad did not take the charge. Retry only when `error.retryable` is true |
| `AMBIGUOUS` (`metadata.needs_review`) | Do not retry. The card may already have been read. The adapter sends a reverse when the result is unknown and an authorization number is present. Send the customer to the counter |

## Shift start and pinpad setup

Call these from the admin screen, never during a charge. The adapter runs them one at a time.

Open the day's batch when the shift starts. This sends `PC` even when the day is already open. `start` also sends `PC` once per day when the shift did not:

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

It answers `Medianet batch <batch> open`.

Write the pinpad network (IP, mask, gateway, port) only when those values are saved. This sends `CP`, then `PC`, and needs `network_mask` and `gateway`:

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

It answers `Medianet pinpad configured`. When the mask or the gateway is empty, it throws `Medianet is missing network_mask, gateway`. A charge does not need those two fields.

Link test, native-module health, and pending reverses:

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

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

There is no pinpad batch close. End of day stays with the store system. There is no last-transaction query. Do not build the frames yourself.

## Webhooks

None.

## Voids

`order.cancel()` voids an order that was not fulfilled. `order.refund()` refunds one that was. An approved sale is voided on the pinpad (`03`). An unknown result is reversed (`04`). A void is `REFUNDED` only when the pinpad and the authorizer both answer `00`.

| Result | What the kiosk does |
| - | - |
| `REFUNDED` or `CANCELLED` | The void finished |
| `PAID` with `needs_review` and a retryable error | The void is queued. Tell the customer to go to the counter. From the kiosk admin screen, run `order.runPaymentTerminal(payment, "retry_pending_reversals")` |
| `PAID` with `MANUAL_REVERSAL_REQUIRED` | The void is missing the sequential or the authorization. Handle it outside the kiosk |
| `FAILED` with `REVERSAL_NOT_ALLOWED` | The charge is already paid, so a cancel cannot reverse it. Void it with `order.refund()` |

## Common errors

| Spark code | Provider code | What to do |
| - | - | - |
| `INVALID_REQUEST` | `01` | The pinpad rejected the frame. Check the pinpad with Medianet |
| `TERMINAL_UNAVAILABLE` | `02`, `ER` | The pinpad did not answer, or the daily `PC` failed. Check the IP, the port, and that the pinpad is on the LAN. See [Activate it](#activate-it) |
| `PROVIDER_UNAVAILABLE` | `20`, `91` | Pinpad process error (`20`), or the issuer is unavailable (`91`, retryable) |
| `TIMEOUT` | `TO` | The socket timed out, or the 300 second window ended. Leave `runtime.timeout_ms` unset, or set it to `300000` or higher |
| `CARD_DECLINED` | `12`, `57`, and any other authorizer code | The authorizer declined. Offer a retry or another method |
| `INSUFFICIENT_FUNDS` | `51` | Offer another method |
| `FRAUD_SUSPECTED` | `59` | Do not retry |
| `TERMINAL_NOT_CONFIGURED` | — | Store or device fields are missing. Check [Activate it](#activate-it) |
| `NETWORK_ERROR` | — | The frame never left the kiosk. Retry when `error.retryable` is true |
| `AMBIGUOUS` | — | The result is unknown. Do not retry the charge. See [Payment errors](https://firespark.cloud/docs/guides/payments/errors.md) |

## Compatibility

| `@fire-spark/payments-medianet-pinpad-rn` | Provider | `@fire-spark/payments` |
| - | - | - |
| 0.12.5 | Medianet, Android | Same version as `@fire-spark/payments-medianet-client` |

## AI agent prompt

Paste this into the agent that edits the kiosk app. It covers only Medianet. The sections above are the same work, written for a person.

```text title="Integration prompt" theme={null}
Integrate only the Medianet pinpad into this Fire spark Android kiosk app. Do not add any other payment provider. Do not add this package to POS, web, or iOS.

Medianet charges a card on a pinpad on the store LAN in Ecuador (USD). One dashboard payment is one checkout button. The kiosk template already renders one card per payment from services.payments.list (CheckoutPaymentMethodCard). Do not create a new button component and do not add an illustration.

The label is payment.name, or the method name when the payment has none. paymentInstructionKind returns "card" for PIN_PAD, and the hint is checkout.method.cardHint ("Debit or credit on the pin pad"). Medianet has no modalities. Do not treat it as Pix, and do not add a debit or credit picker. The pinpad chooses. A second Medianet payment is a second card.

Packages, pinned to the same version as @fire-spark/payments. They are public in the SDK at 0.12.5 and join npm on the next SDK release. Inside this repository, depend on them with workspace:*:
- @fire-spark/payments-medianet-pinpad-rn@0.12.5 (adapter)
- @fire-spark/payments-medianet-client@0.12.5 (Android module and Expo config plugin)

Charge only through medianetPinPadPayments. Do not call the native client, open a socket, or build LT, CP, PC, or PP frames yourself. Do not add a last-transaction query. Do not close the pinpad batch. There is no terminal.closeBatch. End of day stays with the store system.

Native setup:
- Expo Go cannot load the module. Use a development build.
- In app.config.ts add the plugin ["@fire-spark/payments-medianet-client", { binariesDir: process.env.MEDIANET_BINARIES_DIR }].
- The JAR stays outside git (Medianet license). The folder holds CajaPinPadLibrary_V3.jar. Do not commit the JAR or a production IP, MID, TID, or cashier id.
- Generate Android with MEDIANET_BINARIES_DIR set: npx expo prebuild --platform android --clean, then npx expo run:android --device.
- The plugin copies the JAR into android/app/libs/, adds it to the app build.gradle, and adds the internet permission. Prebuild stops with "[medianet] missing ..." when the JAR is absent.
- medianet.available from @fire-spark/payments-medianet-client is true when the plugin is in the build.

Register once per order. Always pass device storage (AsyncStorage). It keeps the day's batch (medianet:control:v1) and the reverse queue. Without it, the pinpad can ask to open the batch again after a restart, and a pending reverse is lost. Do not create another Medianet client. The adapter already uses the shared one.

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 is what getKioskConfig returns. Device values arrive on overrides.payment_settings. Frame dates use America/Guayaquil unless you pass timeZone.

The adapter draws nothing. It sends one ui.message: { text: "Siga las instrucciones en el pinpad", kind: "waiting" }. The default payment UI ignores message. Do not implement select, input, confirm, or a QR. Implement message only when that line should appear on the kiosk.

Charge the payment the customer picked:

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) });

The first charge of the day sends the batch-open frame (PC) once. If that frame fails, there is no charge. A sale is approved only when the pinpad and the authorizer both answer 00. The adapter builds the amount in cents.

The charge window is 300 seconds (daily PC, sale, and a reverse). Leave runtime.timeout_ms unset. If it is set, use 300000 or higher. Raise the adapter default with medianetPinPadPayments({ storage: deviceStorage, timeoutMs: 300_000 }).

Show errors with formatPaymentError from @fire-spark/payments.

Results:
- PAID: continue the order. Authorization code, brand, last 4, sequential (reference), batch, terminal id, and merchant id are on result.metadata.payment. Do not store them yourself. There is no customer receipt to print.
- FAILED CARD_DECLINED: offer a retry or another method.
- FAILED TERMINAL_UNAVAILABLE, TIMEOUT, or NETWORK_ERROR: retry only when error.retryable is true.
- AMBIGUOUS (metadata.needs_review): do not retry. The card may already have been read. The adapter sends a reverse when the result is unknown and an authorization number is present. Send the customer to the counter.

Shift start and admin, never during a charge. The adapter runs these one at a time:
- order.runPaymentTerminal(payment, "open_batch") at shift start. Sends PC even when the day is already open. Answers "Medianet batch <batch> open". start also sends PC once per day when the shift did not.
- order.runPaymentTerminal(payment, "init") only when the pinpad network is saved. Needs network_mask and gateway. Answers "Medianet pinpad configured". Throws "Medianet is missing network_mask, gateway" when either is empty. A charge does not need those two fields.
- order.runPaymentTerminal(payment, "test") answers "Medianet link OK (hash valid)" or "Medianet link OK (hash invalid)".
- order.runPaymentTerminal(payment, "status") returns native-module health.
- order.runPaymentTerminal(payment, "retry_pending_reversals") answers "Reverses and voids completed: N, pending: M".

Voids: order.cancel() for an order that was not fulfilled, order.refund() for one that was. An approved sale is voided on the pinpad (03). An unknown result is reversed (04). REFUNDED only when the pinpad and the authorizer both answer 00.
- REFUNDED or CANCELLED: the void finished.
- PAID with needs_review and a retryable error: the void is queued. From the kiosk admin screen run order.runPaymentTerminal(payment, "retry_pending_reversals").
- PAID with MANUAL_REVERSAL_REQUIRED: sequential or authorization is missing. A person handles it outside the kiosk.
- FAILED with REVERSAL_NOT_ALLOWED: the charge is already paid, so a cancel cannot reverse it. Void it with order.refund().

Errors to handle: INVALID_REQUEST (01), TERMINAL_UNAVAILABLE (02, ER; also a failed daily PC), PROVIDER_UNAVAILABLE (20, or 91 when the issuer is unavailable and retryable), TIMEOUT (TO; socket or the 300 second window), CARD_DECLINED (12, 57, and any other authorizer code), INSUFFICIENT_FUNDS (51), FRAUD_SUSPECTED (59; do not retry), TERMINAL_NOT_CONFIGURED (missing fields), NETWORK_ERROR (frame never left the kiosk), AMBIGUOUS (do not retry the charge).

Dashboard values are filled by a person, not invented by you. Provider Medianet, method PIN pad. Payment config: merchant_id (required MID). Per store, optional merchant_id. Per kiosk, settings_overrides.payment_settings[paymentId]: terminal_ip, terminal_port, terminal_id (8 characters), and cashier_id are required. Optional merchant_id overrides the payment and the store. Optional timeout_s defaults to 90 and is never under 60. network_mask and gateway are required only for init. MID precedence is device, then store, then payment. The batch sequential uses the last 2 characters of cashier_id. A payment missing the required device fields or a MID is hidden from checkout. disabled_payment_ids on the device also hides it. order.getMissingPaymentFields(payment) lists what is still empty.
```


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