Skip to content

README.en.md

Latest commit

 

History

History
224 lines (160 loc) · 7.92 KB

README.en.md

File metadata and controls

224 lines (160 loc) · 7.92 KB
Raw

react-native-plugpag

🇧🇷 Português · 🇺🇸 English

npm license platform TypeScript

Accept card and PIX payments, refund, read NFC and print receipts and QR codes directly from React Native on PagBank Android POS devices (Moderninha Smart, GPOS700, GPOS780S, and other SmartPOS terminals).

Features

  • ⚡ New Architecture (TurboModule), with old-bridge backward compatibility
  • 🧾 Printing that stays aligned: monospaced text with columns, images, and native QR Code (ZXing), with automatic retry on back-to-back prints
  • 💳 Payments credit, debit, PIX and installments, with typed progress events
  • ↩️ Refund (void), abort and NFC read
  • 🧠 TypeScript-first: types, enums and typed events
  • 🤖 Native in Kotlin, tracks wrapper 1.35.x
  • 📦 Bare React Native and Expo (config plugin included)
  • ✅ Validated on real hardware (GPOS780S and Moderninha/Sunmi)

Requirements

  • A physical PagBank SmartPOS terminal. PlugPag talks to a payment service that only exists on these devices, so it does not run on emulators, simulators, or Expo Go.
  • Android 7.1+ (SDK 24+).
  • The PlugPag service app installed on the terminal (pre-installed on PagBank devices).
  • An activation code for your PagBank account (see Getting your activation code).

Installation

npm install @lucasmaffei/react-native-plugpag
# or
yarn add @lucasmaffei/react-native-plugpag

The native PlugPagServiceWrapper is hosted on PagBank's own Maven repository (not Maven Central), so your app has to declare it.

Bare React Native

  1. Add PagBank's Maven repo to android/build.gradle:

    allprojects {
    repositories {
        // ...
        maven { url 'https://github.com/pagseguro/PlugPagServiceWrapper/raw/master' }
    }
}

    On newer templates repositories may live under dependencyResolutionManagement { repositories { … } } in android/settings.gradle. Add the same maven { … } line there instead.

  2. Autolinking wires up the rest. Rebuild the app:

    npx react-native run-android

Expo

This library needs native code, so it works with development builds / prebuild (not Expo Go).

  1. Add the config plugin to app.json (or app.config.js). It injects the PagBank Maven repo automatically on prebuild:

    {
  "expo": {
    "plugins": ["@lucasmaffei/react-native-plugpag"]
  }
}

  2. Create a development build:

    npx expo prebuild
npx expo run:android

Getting your activation code

The pinpad activation code comes from your PagBank account (tied to the merchant/terminal, e.g. 851192). Configure it once via initializeAndActivatePinpad(code) before taking payments.

Distributing to the terminal (production)

For production, PagBank distributes your app to the terminals through the Developer Portal (you request your applicationId to be enabled for each terminal model and bind terminals to your reseller). During development you can sideload the debug build via adb install.

Quick start

import {
  initializeAndActivatePinpad,
  doPayment,
  addPaymentListener,
  PaymentType,
} from '@lucasmaffei/react-native-plugpag';

// 1. Activate the pinpad once (e.g. on app start)
await initializeAndActivatePinpad('851192');

// 2. Follow the transaction progress (enter password, tap card, approved…)
const sub = addPaymentListener((e) => console.log(e.code, e.message));

// 3. Charge R$ 12,50 on credit
const result = await doPayment({
  amount: 1250, // cents
  type: PaymentType.CREDIT,
  printReceipt: true,
});

if (result.result === 0) {
  console.log('Approved:', result.transactionId);
}

sub.remove();

Refund (void)

import { voidPayment } from '@lucasmaffei/react-native-plugpag';

await voidPayment({
  transactionCode: result.transactionCode!,
  transactionId: result.transactionId!,
  printReceipt: true,
});

Printing

Text is rendered as a monospaced bitmap sized to the 58 mm (384-dot) print head, so column layouts stay aligned. Sequential prints handle PRNTR_NOT_READY for you.

import { printText, printQRCode, layout } from '@lucasmaffei/react-native-plugpag';

const receipt = layout.receipt([
  layout.center('BAR DO EXEMPLO'),
  layout.repeat('-'),
  layout.columns('2x Cerveja', 'R$ 24,00'),
  layout.columns('1x Agua', 'R$ 5,00'),
  layout.repeat('-'),
  layout.columns('TOTAL', 'R$ 29,00'),
]);

await printText(receipt, { columns: 32 });
await printQRCode('https://pag.ae/your-link', { size: 240 });

NFC

import { readNFCCard } from '@lucasmaffei/react-native-plugpag';

const { uid } = await readNFCCard(); // hex UID of the tapped card

API reference

Payments

Function Description
initializeAndActivatePinpad(code) Initializes/activates the pinpad. Returns TransactionResult.
doPayment({ amount, type, installments?, installmentType?, printReceipt, userReference? }) Charges the card. amount in cents.
voidPayment({ transactionCode, transactionId, printReceipt }) Refunds/voids a transaction.
abort() Aborts the in-progress operation.
addPaymentListener(cb) Subscribes to progress events. Returns an EmitterSubscription.

Enums: PaymentType (CREDIT, DEBIT, VOUCHER, PIX), InstallmentType.

Printing

Function Description
printText(text, { align?, bold?, columns? }) Monospaced text (aligned columns).
printImage(path) Prints a PNG/JPEG from a file path.
printQRCode(content, { size?, align? }) Native QR Code (ZXing).
feed(lines) Advances the paper.
reprintCustomerReceipt() Reprints the last customer receipt.
layout.* center, columns, repeat, padLeft, padRight, receipt.

NFC & info

Function Description
readNFCCard() Reads a tapped NFC card. Returns { uid }.
getTerminalSerialNumber() Device serial (empty string if unavailable).

Limitations

  • Android only (the platform of PagBank SmartPOS devices); on iOS the methods reject with an "unsupported platform" error so cross-platform apps still compile.
  • Runs only on physical PagBank terminals (not emulators/Expo Go).

Troubleshooting

  • Could not find br.com.uol.pagseguro.plugpagservice.wrapper:wrapper: you did not add PagBank's Maven repo. See Installation.
  • Nothing happens on emulator: expected. PlugPag only works on real SmartPOS hardware.
  • Payment fails right after init: check the activation code and that the terminal is bound to your PagBank account.
  • Second receipt/ticket does not print: handled automatically (retry on PRNTR_NOT_READY); if you print your own way, leave a short delay between jobs.

Compatibility

Validated on real hardware: GPOS780S (Android 13, Urovo) and P2 / Moderninha (Sunmi, Android 7.1), on the New Architecture.

Contributing

See CONTRIBUTING.md. Issues and PRs welcome.

Disclaimer

Not affiliated with or endorsed by PagBank / PagSeguro / UOL. "PagBank", "PagSeguro" and "PlugPag" are trademarks of their respective owners. The PlugPagServiceWrapper is distributed by PagBank and pulled from their Maven repository; this library only wraps it.

License

MIT © Lucas Maffei