capacitor-plugin-plugpag

Plugin Capacitor para integração com terminais de pagamento PagBank via PlugPag SDK.

Recursos

• 💳 Múltiplas formas de pagamento — Aceite Crédito (à vista ou parcelado), Débito, Voucher e PIX
• 📊 Consulta de taxas na hora — Valores de parcelas e totais calculados instantaneamente pelo terminal
• 🔄 Estorno integrado — Cancele transações facilmente usando o código ou ID da venda
• 🖨️ Impressão completa — Imprima textos, arquivos e PDFs diretamente na impressora térmica da maquininha
• 📡 Eventos em tempo real — Acompanhe cada passo do pagamento (ex: "insira o cartão", "digite a senha")
• 🔒 Operações seguras — Sistema de fila que evita conflitos e garante que um comando não atropele o outro
• 📘 TypeScript nativo — Estrutura moderna e organizada com enums e interfaces

Instalação

npm install capacitor-plugin-plugpag
npx cap sync

Requisitos

• Capacitor ≥ 7
• Android API ≥ 21
• Terminal PagBank com PlugPag SDK instalado

Uso

Pagamento à vista

import { PlugPag, PaymentType, InstallmentType } from 'capacitor-plugin-plugpag';

try {
  const resultado = await PlugPag.doPayment({
    type: PaymentType.CREDIT,
    amount: 2500, // valor em centavos (R$ 25,00)
    installments: 1,
    userReference: 'PED001', // máx. 10 caracteres alfanuméricos
    printReceipt: true,
  });

  console.log('Aprovado:', resultado.transactionCode);
} catch (error) {
  // Transação negada, cancelada ou erro de comunicação.
  // error.message contém o código e a mensagem retornados pelo terminal.
  console.error('Pagamento recusado:', error.message);
}

Crédito parcelado

import { PlugPag, PaymentType, InstallmentType } from 'capacitor-plugin-plugpag';

// Parcelado sem juros (lojista absorve) — use BUYER_INSTALLMENT para parcelado com juros
const resultado = await PlugPag.doPayment({
  type: PaymentType.CREDIT,
  amount: 15000, // R$ 150,00
  installmentType: InstallmentType.SELLER_INSTALLMENT,
  installments: 3, // 3x de R$ 50,00
  userReference: 'PED002',
  printReceipt: true,
});

Débito e PIX

// Débito — sem parcelamento
await PlugPag.doPayment({
  type: PaymentType.DEBIT,
  amount: 5000,
  userReference: 'PED003',
});

// PIX
await PlugPag.doPayment({
  type: PaymentType.PIX,
  amount: 5000,
  userReference: 'PED004',
});

Acompanhando o progresso em tempo real

Use addListener antes ou durante o pagamento para exibir o status ao operador. O evento PaymentEvent carrega message (texto para exibição) e code (veja PaymentEventCode).

import { PlugPag, PaymentEventCode } from 'capacitor-plugin-plugpag';

const handle = await PlugPag.addListener('paymentProgress', (event) => {
  console.log(event.message); // ex: "Insira o cartão", "Digite a senha", "Processando..."

  if (event.code === PaymentEventCode.CARD_INSERTED) {
    // cartão físico inserido no terminal
  }
  if (event.code === PaymentEventCode.TRANSACTION_APPROVED) {
    // aprovação confirmada antes do doPayment retornar
  }
});

await PlugPag.doPayment({ ... });

handle.remove(); // sempre remova o listener após a operação

Estorno

O estorno só é possível no mesmo dia da transação. Guarde transactionCode e transactionId do resultado do pagamento.

try {
  await PlugPag.voidPayment({
    transactionCode: resultado.transactionCode,
    transactionId: resultado.transactionId,
    printReceipt: true,
  });
  console.log('Estorno concluído');
} catch (error) {
  console.error('Estorno recusado:', error.message);
}

Impressão

// Verificar conexão com o serviço PlugPag antes de imprimir.
// Atenção: este método confirma o IPC com o app PagBank, mas não detecta
// falhas físicas da impressora (papel acabado, etc.).
const { status } = await PlugPag.statusImpressora();

if (status === 'IMPRESSORA OK') {
  // Texto simples — use '\n' para quebrar linhas
  // Referência de largura: size=20 → ~28 chars/linha (padrão 58 mm)
  await PlugPag.imprimirTexto({
    mensagem: 'Obrigado pela compra!\n\n\n',
    size: 20,
  });

  // PDF por URL (renderiza cada página como bitmap 384 px)
  await PlugPag.printPdfFromUrl({ url: 'https://exemplo.com/comprovante.pdf' });

  // Reimprimir o último comprovante do cliente
  await PlugPag.reprintCustomerReceipt();
}

Consultar opções de parcelamento

Use calculateInstallments para exibir ao operador as opções reais — com valores por parcela e total — antes de iniciar o pagamento. O método é bloqueante e consulta o serviço PagBank no terminal.

import { PlugPag, InstallmentType } from 'capacitor-plugin-plugpag';

const valorCentavos = Math.round(150.0 * 100); // R$ 150,00 → 15000 centavos

// Parcelado sem juros — lojista absorve as taxas
const { installments: semJuros } = await PlugPag.calculateInstallments({
  value: valorCentavos,
  installmentType: InstallmentType.SELLER_INSTALLMENT,
});

// Parcelado com juros — comprador paga as taxas ao emissor
const { installments: comJuros } = await PlugPag.calculateInstallments({
  value: valorCentavos,
  installmentType: InstallmentType.BUYER_INSTALLMENT,
});

// Cada item de `installments`:
// { installments: 3, installmentValue: 5000, totalValue: 15000 }
//   ↳ todos os valores monetários estão em centavos (divida por 100 para exibir em reais)

for (const op of comJuros) {
  console.log(
    `${op.installments}x de R$ ${(op.installmentValue / 100).toFixed(2)}`,
    `— total R$ ${(op.totalValue / 100).toFixed(2)}`,
  );
}

Cancelar uma operação em andamento

// Chame abort() para interromper um doPayment bloqueante.
// O doPayment lançará exceção com mensagem contendo "RET_ABORT".
await PlugPag.abort();

Verificar estado do terminal

const { value: autenticado } = await PlugPag.isAuthenticated();
const { value: ocupado } = await PlugPag.isServiceBusy();

Ativar o terminal (primeiro uso)

// Necessário apenas na primeira execução ou após reset de fábrica.
await PlugPag.initialize({ activationCode: 'SEU_CODIGO_PAGBANK' });

API

• isAuthenticated()
• isServiceBusy()
• initialize(...)
• doPayment(...)
• abort()
• calculateInstallments(...)
• voidPayment(...)
• imprimirTexto(...)
• statusImpressora()
• printFromFile(...)
• reprintCustomerReceipt()
• printPdfFromUrl(...)
• addListener('paymentProgress', ...)
• addListener('voidProgress', ...)
• removeAllListeners()
• Interfaces
• Enums

Interface principal do plugin PlugPag para Capacitor.

Permite integrar o terminal de pagamento PagBank Smart (e compatíveis) em aplicações Ionic/Capacitor via PlugPag SDK Android.

isAuthenticated()

isAuthenticated() => Promise<{ value: boolean; }>

Verifica se o terminal está autenticado com o serviço PlugPag (IPC ativo).

Returns: Promise<{ value: boolean; }>

isServiceBusy()

isServiceBusy() => Promise<{ value: boolean; }>

Verifica se o serviço PlugPag está ocupado com uma operação em andamento.

Returns: Promise<{ value: boolean; }>

initialize(...)

initialize(options: { activationCode: string; }) => Promise<{ status: string; }>

Inicializa e ativa o terminal com o código de ativação PagBank. Necessário apenas na primeira execução ou após reset de fábrica.

| Param | Type | | ------------- | ---------------------------------------- | | options | { activationCode: string; } |

Returns: Promise<{ status: string; }>

doPayment(...)

doPayment(options: { type: PaymentType; amount: number; installmentType?: InstallmentType; installments?: number; userReference: string; printReceipt?: boolean; }) => Promise<PlugPagTransactionResult>

Inicia uma cobrança no terminal.

O método é bloqueante até o terminal concluir (aprovado, negado ou cancelado). Use addListener('paymentProgress', ...) para acompanhar o progresso em tempo real.

| Param | Type | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | options | { type: PaymentType; amount: number; installmentType?: InstallmentType; installments?: number; userReference: string; printReceipt?: boolean; } |

Returns: Promise<PlugPagTransactionResult>

abort()

abort() => Promise<{ result: ErrorCode; }>

Aborta a operação em andamento (pagamento ou estorno). Retorna imediatamente — o doPayment ou voidPayment falhará com código OPERATION_ABORTED (-1).

Returns: Promise<{ result: ErrorCode; }>

calculateInstallments(...)

calculateInstallments(options: { value: number; installmentType: InstallmentType; }) => Promise<{ installments: PlugPagInstallment[]; }>

Consulta as opções de parcelamento para um valor e modalidade.

Operação bloqueante — o SDK consulta o serviço PagBank e retorna os valores reais calculados com base no plano de recebimento do lojista vinculado ao terminal.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------------ | | options | { value: number; installmentType: InstallmentType; } |

Returns: Promise<{ installments: PlugPagInstallment[]; }>

voidPayment(...)

voidPayment(options: { transactionCode: string; transactionId: string; printReceipt?: boolean; }) => Promise<PlugPagTransactionResult>

Estorna (cancela) uma transação previamente aprovada.

Só é possível no mesmo dia da transação original. Use addListener('voidProgress', ...) para acompanhar o progresso.

| Param | Type | | ------------- | ---------------------------------------------------------------------------------------- | | options | { transactionCode: string; transactionId: string; printReceipt?: boolean; } |

Returns: Promise<PlugPagTransactionResult>

imprimirTexto(...)

imprimirTexto(options: { mensagem: string; size?: number; }) => Promise<void>

Imprime texto diretamente na impressora térmica do terminal (58 mm / 384 px).

O texto é renderizado em um bitmap monoespaçado e enviado via PlugPag SDK. Use quebras de linha (\n) para múltiplas linhas.

Referência de largura por tamanho de fonte: | size | chars/linha aprox. | |--------|--------------------| | 18 | ~34 | | 20 | ~30 (recomendado) | | 26 | ~23 |

| Param | Type | | ------------- | ------------------------------------------------- | | options | { mensagem: string; size?: number; } |

statusImpressora()

statusImpressora() => Promise<{ status: string; }>

Verifica se o serviço PlugPag está autenticado e acessível.

Atenção: este método usa isAuthenticated() como proxy — confirma que o IPC com o app PagBank está ativo, mas não detecta falhas físicas da impressora (papel acabado, cabeçote com defeito, etc.). Erros físicos são reportados apenas como resultado de uma tentativa de impressão.

Returns: Promise<{ status: string; }>

printFromFile(...)

printFromFile(options: { filePath: string; }) => Promise<void>

Imprime a partir de um arquivo de imagem já salvo no dispositivo.

| Param | Type | | ------------- | ---------------------------------- | | options | { filePath: string; } |

reprintCustomerReceipt()

reprintCustomerReceipt() => Promise<void>

Reimprimir o último comprovante do cliente diretamente pelo terminal.

printPdfFromUrl(...)

printPdfFromUrl(options: { url: string; }) => Promise<void>

Baixa um PDF da URL informada, renderiza cada página como bitmap (384 px de largura) e imprime via PlugPag SDK página a página.

Em dispositivos Android mais antigos, um TrustManager permissivo é aplicado apenas para esta conexão HTTPS — valide o certificado do servidor antes de usar em produção.

| Param | Type | | ------------- | ----------------------------- | | options | { url: string; } |

addListener('paymentProgress', ...)

addListener(eventName: 'paymentProgress', listenerFunc: (info: PaymentEvent) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Escuta eventos de progresso durante {@link doPayment}.

| Param | Type | | ------------------ | ------------------------------------------------------------------------ | | eventName | 'paymentProgress' | | listenerFunc | (info: PaymentEvent) => void |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

addListener('voidProgress', ...)

addListener(eventName: 'voidProgress', listenerFunc: (info: PaymentEvent) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Escuta eventos de progresso durante {@link voidPayment}.

| Param | Type | | ------------------ | ------------------------------------------------------------------------ | | eventName | 'voidProgress' | | listenerFunc | (info: PaymentEvent) => void |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

removeAllListeners()

removeAllListeners() => Promise<void>

Remove todos os listeners registrados neste plugin. Chame no ngOnDestroy ou equivalente para evitar memory leaks.

Interfaces

PlugPagTransactionResult

Resultado completo de uma transação (pagamento ou estorno). Todos os campos opcionais podem ser undefined dependendo da bandeira e do tipo de transação.

| Prop | Type | Description | | -------------------------- | ------------------- | -------------------------------------------------------------------------------------------- | | transactionCode | string | Código interno da transação — necessário para estorno via {@link PlugPagPlugin.voidPayment}. | | transactionId | string | ID externo da transação — necessário para estorno via {@link PlugPagPlugin.voidPayment}. | | message | string | Mensagem de resposta do host autorizador. | | errorCode | string | Código de erro do SDK (presente apenas em casos de falha tratada). | | hostNsu | string | NSU do host autorizador. | | date | string | Data da transação no formato retornado pelo terminal (DDMMAA). | | time | string | Hora da transação no formato retornado pelo terminal (HHmmss). | | cardBrand | string | Bandeira do cartão (ex: "VISA", "MASTERCARD"). | | bin | string | Seis primeiros dígitos do cartão (BIN). | | holder | string | Nome do portador do cartão conforme gravado na trilha. | | userReference | string | Referência enviada no momento do pagamento via userReference. | | terminalSerialNumber | string | Número de série do terminal PagBank. | | amount | string | Valor cobrado em centavos como string (ex: "15000" para R$ 150,00). | | availableBalance | string | Saldo disponível (para vouchers/pré-pagos). | | cardApplication | string | Aplicação EMV selecionada pelo cartão. | | label | string | Label da aplicação EMV. | | holderName | string | Nome do portador (campo curto). | | extendedHolderName | string | Nome do portador (campo estendido, quando disponível). | | installments | string | Número de parcelas confirmadas pelo terminal como string (ex: "3"). |

PlugPagInstallment

Uma opção de parcelamento retornada por {@link PlugPagPlugin.calculateInstallments}. Os valores monetários estão em centavos (divida por 100 para exibir em reais).

| Prop | Type | Description | | ---------------------- | ------------------- | ---------------------------------------------------------- | | installments | number | Número de parcelas (ex: 3 para 3x). | | installmentValue | number | Valor de cada parcela em centavos (ex: 5670 = R$ 56,70). | | totalValue | number | Valor total com juros em centavos. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

PaymentEvent

Evento de progresso emitido pelo terminal durante um pagamento ou estorno. Recebido via listener paymentProgress ou voidProgress.

| Prop | Type | Description | | ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | code | PaymentEventCode | Código numérico do evento (veja {@link PaymentEventCode}). | | message | string | Mensagem legível para exibição ao operador. |

Enums

PaymentType

| Members | Value | | ------------- | -------------- | | CREDIT | 1 | | DEBIT | 2 | | VOUCHER | 3 | | PIX | 5 |

InstallmentType

| Members | Value | | ------------------------ | -------------- | | NO_INSTALLMENT | 1 | | SELLER_INSTALLMENT | 2 | | BUYER_INSTALLMENT | 3 |

ErrorCode

| Members | Value | | --------------------------- | --------------- | | OK | 0 | | OPERATION_ABORTED | -1 | | AUTHENTICATION_FAILED | -2 | | COMMUNICATION_ERROR | -3 | | NO_PRINTER_DEVICE | -4 | | NO_TRANSACTION_DATA | -5 |

PaymentEventCode

| Members | Value | | ---------------------------- | ----------------- | | CARD_INSERTED | 1001 | | CARD_REMOVED | 1002 | | CARD_TAPPED | 1003 | | WAITING_CARD | 1004 | | DIGIT_PASSWORD | 1010 | | NO_PASSWORD | 1011 | | LAST_PASSWORD_TRY | 1012 | | PROCESSING_TRANSACTION | 1020 | | CONNECTING_TO_NETWORK | 1021 | | SENDING_DATA | 1022 | | WAITING_HOST_RESPONSE | 1023 | | REMOVE_CARD | 1030 | | TRANSACTION_APPROVED | 1031 | | TRANSACTION_DENIED | 1032 | | COMMUNICATION_ERROR | 1040 | | INVALID_CARD | 1041 | | CARD_BLOCKED | 1042 | | INSUFFICIENT_FUNDS | 1043 | | TRANSACTION_CANCELLED | 1050 | | SIGNATURE_REQUIRED | 1051 | | PRINTING_RECEIPT | 1052 |

Licença

MIT © Igor Gomes