llms.txt

# @lucasmaffei/react-native-plugpag

> React Native (TurboModule, TypeScript) library for PagBank/PagSeguro PlugPag on Android SmartPOS terminals. Card/PIX payments, refund/void, abort, NFC read, and thermal printing (monospaced text with aligned columns, images, QR via ZXing). Android-only; runs ONLY on physical PagBank SmartPOS hardware (not emulators/Expo Go). This file is an LLM-oriented, self-contained reference for implementing with the library.

## Critical facts (read first)

- Platform: **Android only** (PagBank SmartPOS). iOS methods reject with "unsupported platform". No emulator support.
- `amount` is always in **cents** (integer). R$ 12,50 => `1250`.
- Every method is **async** (returns a Promise) except `addPaymentListener`. Wrap calls in try/catch.
- On success, `TransactionResult.result === 0`. Any other value is a failure (`errorCode`/`message` explain).
- Install requires adding PagBank's Maven repo (`https://github.com/pagseguro/PlugPagServiceWrapper/raw/master`) to the app's Android build (bare RN) or via the Expo config plugin `@lucasmaffei/react-native-plugpag`.
- `initializeAndActivatePinpad(code)` must run once before payments. `code` is the PagBank pinpad activation code.
- Multi-print (`PRNTR_NOT_READY`) is retried internally; no need to add delays yourself.

## Imports

```ts
import {
  // payments
  initializeAndActivatePinpad, doPayment, voidPayment, abort, addPaymentListener,
  // nfc + info
  readNFCCard, getTerminalSerialNumber,
  // printing
  printText, printImage, printQRCode, feed, reprintCustomerReceipt,
  // helpers namespace
  layout,
  // enums + types
  PaymentType, InstallmentType,
  type TransactionResult, type PaymentProgressEvent, type PrintAlign,
} from '@lucasmaffei/react-native-plugpag';
```

## Enums

```ts
enum PaymentType { CREDIT = 1, DEBIT = 2, VOUCHER = 3, PIX = 5 }
enum InstallmentType { A_VISTA = 1, PARCELADO_VENDEDOR = 2, PARCELADO_COMPRADOR = 3 }
type PrintAlign = 'left' | 'center' | 'right';
```

## Function signatures

```ts
// Payments
function initializeAndActivatePinpad(activationCode: string): Promise<TransactionResult>;
function doPayment(data: {
  amount: number;               // cents
  type: PaymentType;
  installments?: number;        // default 1
  installmentType?: InstallmentType; // default A_VISTA
  printReceipt: boolean;
  userReference?: string;
}): Promise<TransactionResult>;
function voidPayment(data: {
  transactionCode: string;
  transactionId: string;
  printReceipt: boolean;
}): Promise<TransactionResult>;
function abort(): Promise<boolean>;
function addPaymentListener(cb: (e: PaymentProgressEvent) => void): EmitterSubscription; // e = { code: number; message: string }

// NFC + info
function readNFCCard(): Promise<{ uid: string }>;              // uid: hex string
function getTerminalSerialNumber(): Promise<string>;          // '' if unavailable

// Printing
function printText(text: string, options?: { align?: PrintAlign; bold?: boolean; columns?: number }): Promise<void>;
function printImage(path: string): Promise<void>;             // PNG/JPEG file path
function printQRCode(content: string, options?: { size?: number; align?: PrintAlign }): Promise<void>;
function feed(lines: number): Promise<void>;
function reprintCustomerReceipt(): Promise<void>;

// Layout helpers (pure, width defaults to 32 columns)
layout.center(text: string, width?: number): string;
layout.columns(left: string, right: string, width?: number): string;  // right-justifies `right`
layout.repeat(char: string, width?: number): string;                  // separator line
layout.padLeft(text: string, width: number): string;
layout.padRight(text: string, width: number): string;
layout.receipt(lines: string[]): string;                              // join with '\n'
```

## TransactionResult shape

```ts
type TransactionResult = {
  result: number;               // 0 = success
  errorCode?: string;
  message?: string;
  transactionCode?: string;     // needed for voidPayment
  transactionId?: string;       // needed for voidPayment
  hostNsu?: string;
  date?: string; time?: string;
  cardBrand?: string; bin?: string; holder?: string; holderName?: string;
  userReference?: string;
  terminalSerialNumber?: string;
  amount?: string;
  cardApplication?: string;     // 'CREDITO' | 'DEBITO'
  label?: string;
};
```

## Recipes

### Activate + charge credit + handle result
```ts
await initializeAndActivatePinpad('851192');
const sub = addPaymentListener((e) => console.log(e.code, e.message));
try {
  const r = await doPayment({ amount: 1250, type: PaymentType.CREDIT, printReceipt: true });
  if (r.result === 0) { /* approved: r.transactionId, r.transactionCode */ }
  else { /* failed: r.message */ }
} finally { sub.remove(); }
```

### Refund the last transaction
```ts
await voidPayment({ transactionCode: r.transactionCode!, transactionId: r.transactionId!, printReceipt: true });
```

### Print an aligned receipt + QR
```ts
const text = layout.receipt([
  layout.center('MINHA LOJA'),
  layout.repeat('-'),
  layout.columns('2x Produto', 'R$ 20,00'),
  layout.columns('TOTAL', 'R$ 20,00'),
]);
await printText(text, { columns: 32 });   // 32 cols is the sweet spot for 58mm
await printQRCode('https://pag.ae/x', { size: 240 });
await feed(2);
```

### Read an NFC card
```ts
const { uid } = await readNFCCard();
```

## Gotchas for code generation

- Do NOT call payment/print methods on iOS or emulators; guard with `Platform.OS === 'android'` if the app is cross-platform (methods reject otherwise).
- Prefer `columns: 32` for 58mm printers; larger column counts shrink the font.
- Keep `layout.*` line lengths <= the `columns` value or they will be truncated.
- `installments`/`installmentType` are optional; omit them for a vista.
- Always `remove()` the payment listener subscription to avoid leaks.
- For Expo, this needs a dev build (prebuild); it does NOT work in Expo Go.