🇧🇷 Português · 🇺🇸 English

Aceite pagamentos por cartão e PIX, faça estorno, leia NFC e imprima recibos e QR Codes direto do React Native nas maquininhas Android da PagBank (Moderninha Smart, GPOS700, GPOS780S e outros SmartPOS).

Recursos

• ⚡ New Architecture (TurboModule), compatível com a bridge antiga
• 🧾 Impressão que alinha de verdade: texto monoespaçado com colunas, imagens e QR Code nativo (ZXing), com retry automático em impressões seguidas
• 💳 Pagamentos crédito, débito, PIX e parcelado, com eventos de progresso tipados
• ↩️ Estorno (void), abort e leitura de NFC
• 🧠 TypeScript-first: tipos, enums e eventos tipados
• 🤖 Nativo em Kotlin, acompanha o wrapper 1.35.x
• 📦 Bare React Native e Expo (config plugin incluído)
• ✅ Validado em hardware real (GPOS780S e Moderninha/Sunmi)

Requisitos

• Um terminal SmartPOS físico da PagBank. O PlugPag conversa com um serviço de pagamento que só existe nesses aparelhos, então não roda em emulador, simulador ou Expo Go.
• Android 7.1+ (SDK 24+).
• O app do serviço PlugPag instalado no terminal (já vem de fábrica nos aparelhos PagBank).
• Um código de ativação da sua conta PagBank (veja Obtendo o código de ativação).

Instalação

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

O PlugPagServiceWrapper nativo fica hospedado no repositório Maven da própria PagBank (não no Maven Central), então seu app precisa declará-lo. Escolha a seção do seu setup.

Bare React Native

1. Adicione o Maven da PagBank no android/build.gradle:

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

   Em templates mais novos os repositórios podem estar em dependencyResolutionManagement { repositories { … } } no android/settings.gradle. Nesse caso, adicione a mesma linha maven { … } lá.

2. O autolinking faz o resto. Rebuilde o app:

   npx react-native run-android

Expo

Esta biblioteca precisa de código nativo, então funciona com development build / prebuild (não no Expo Go).

1. Adicione o config plugin no app.json (ou app.config.js). Ele injeta o Maven da PagBank automaticamente no prebuild:

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

2. Gere um development build:

   npx expo prebuild
   npx expo run:android

Obtendo o código de ativação

O código de ativação do pinpad vem da sua conta PagBank (fica atrelado ao lojista/terminal, ex.: 851192). Você configura uma vez com initializeAndActivatePinpad(codigo) antes de operar pagamentos.

Distribuindo para o terminal (produção)

Em produção, a PagBank distribui seu app para os terminais pelo Portal Developer (você solicita a liberação do seu applicationId para cada modelo de terminal e vincula os terminais ao seu reseller). Em desenvolvimento você pode instalar o build de debug via adb install.

Começando

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

// 1. Ative o pinpad uma vez (ex.: ao abrir o app)
await initializeAndActivatePinpad('851192');

// 2. Acompanhe o progresso da transação (senha, aproxime o cartão, aprovada…)
const sub = addPaymentListener((e) => console.log(e.code, e.message));

// 3. Cobre R$ 12,50 no crédito
const result = await doPayment({
  amount: 1250, // em centavos
  type: PaymentType.CREDIT,
  printReceipt: true,
});

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

sub.remove();

Estorno (void)

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

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

Impressão

O texto é renderizado como um bitmap monoespaçado do tamanho da cabeça de 58 mm (384 dots), então layouts em colunas ficam alinhados. Impressões em sequência já tratam o PRNTR_NOT_READY pra você.

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

const recibo = 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(recibo, { columns: 32 });
await printQRCode('https://pag.ae/seu-link', { size: 240 });

NFC

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

const { uid } = await readNFCCard(); // UID em hex do cartão aproximado

Referência da API

Pagamentos

Função	Descrição
initializeAndActivatePinpad(codigo)	Inicializa/ativa o pinpad. Retorna TransactionResult.
doPayment({ amount, type, installments?, installmentType?, printReceipt, userReference? })	Cobra no cartão. amount em centavos.
voidPayment({ transactionCode, transactionId, printReceipt })	Estorna/cancela uma transação.
abort()	Aborta a operação em andamento.
addPaymentListener(cb)	Assina os eventos de progresso. Retorna um EmitterSubscription.

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

Impressão

Função	Descrição
printText(text, { align?, bold?, columns? })	Texto monoespaçado (colunas alinhadas).
printImage(path)	Imprime um PNG/JPEG de um caminho de arquivo.
printQRCode(content, { size?, align? })	QR Code nativo (ZXing).
feed(lines)	Avança o papel.
reprintCustomerReceipt()	Reimprime a última via do cliente.
layout.*	center, columns, repeat, padLeft, padRight, receipt.

NFC e info

Função	Descrição
readNFCCard()	Lê um cartão NFC aproximado. Retorna { uid }.
getTerminalSerialNumber()	Serial do aparelho (string vazia se indisponível).

Limitações

• Android apenas (é a plataforma dos SmartPOS PagBank); no iOS os métodos rejeitam com um erro de plataforma não suportada, para o app multiplataforma continuar compilando.
• Roda apenas em terminal físico PagBank (não em emulador/Expo Go).

Solução de problemas

• Could not find br.com.uol.pagseguro.plugpagservice.wrapper:wrapper: você não adicionou o Maven da PagBank. Veja Instalação.
• Nada acontece no emulador: é esperado. O PlugPag só funciona em SmartPOS físico.
• Pagamento falha logo após o init: confira o código de ativação e se o terminal está vinculado à sua conta PagBank.
• O segundo recibo/ticket não imprime: já é tratado automaticamente (retry no PRNTR_NOT_READY); se você imprimir por conta própria, deixe um pequeno intervalo entre os jobs.

Compatibilidade

Validada em hardware real: GPOS780S (Android 13, Urovo) e P2 / Moderninha (Sunmi, Android 7.1), na New Architecture.

Contribuindo

Veja o CONTRIBUTING.md. Issues e PRs são bem-vindos.

Aviso legal

Não afiliado nem endossado pela PagBank / PagSeguro / UOL. "PagBank", "PagSeguro" e "PlugPag" são marcas dos seus respectivos donos. O PlugPagServiceWrapper é distribuído pela PagBank e baixado do Maven deles; esta biblioteca apenas o encapsula.

Licença

MIT © Lucas Maffei