PlugPag para Linux

Nesta documentação você verá os seguintes itens:

Visão geral
Versão
Pareando a sua Moderninha PRO
Mapeando Device Bluetooth
Importando a biblioteca
Efetuando uma Solicitação de Pagamento
Consultando última transação
Iniciando um processo de estorno
Listagem de erros

Visão Geral

Esta integração permite que a sua aplicação Linux se conecte via Bluetooth à Moderninha PRO do PagSeguro, possibilitando ações como Solicitação de Pagamentos, obtenção dos dados de retorno e solicitação de estorno de transações. Se o seu computador não possui a conectividade com bluetooth, você pode utilizar um adaptador bluetooth USB com os seguintes requerimentos mínimos:

INTERFACE: USB 2.0

CONECTIVIDADE: Compatível com a versão Bluetooth: 4.2 + compatibilidade com 2.1 EDR / 3.0 / 4.0 & 4.1

Bluetooth Power Class: Class 2 - 2.5mW (4dBm) 10 meters

Versão

Antes de iniciar, entre no Menu e verifique a versão do firmware conforme as imagens abaixo:

Imagem 1

Caso sua Moderninha PRO não esteja na versão 3.11.x (ou superior), basta iniciar a atualização manual através da opção menu > configurações gerais > atualização.

Dúvidas? Acesse a comunidade de desenvolvedores.

Pareando a sua Moderninha PRO

Antes de mais nada você deve parear a sua Moderninha com o seu dispositivo Linux. Com a sua moderninha pareada, você deverá mapear a moderninha para a porta COM0 como descrito em Mapeando device bluetooth.

  • Para tornar o bluetooth da moderninha visível, basta apertar a tecla '0'.

Ainda não tem a sua Moderninha PRO? Adquira a sua agora em https://loja.pagseguro.uol.com.br/

Mapeando device bluetooth na porta serial

Para utilizar o device bluetooth mapeado no default /dev/rfcomm0 do sistema operacional Linux é necessário rodar os seguintes comandos abaixo (informando o número do MacAddress resultante da pesquisa do comando hcitool):

sudo hcitool scan
sudo rfcomm release all
sudo rfcomm bind /dev/rfcomm0 <numero do MacAddress do device> 1
sudo chmod 777 /dev/rfcomm0
  • É recomendavel mapear a Moderninha PRO para a COM0 como no exemplo

Importando a biblioteca

Todas as chamadas que você verá nos próximos passos são efetuadas utilizando uma biblioteca exclusiva para Linux, que deverá ser importada em seu projeto. Esta biblioteca poderá ser baixada através do link a seguir: Clique aqui para fazer o download!

Com a biblioteca importada, você poderá obter a sua versão através do método GetVersionLib. O método não recebe parâmetros e retorna um const char* - string null terminated com a versão da biblioteca de integração.

Também é importante informar que esta biblioteca não necessita de nenhum tipo de autenticação com login e senha pois a Moderninha PRO já está autenticada e vinculada a uma conta PagSeguro.

Dados

typedef enum {
    PPPAGSEGURO_CREDIT = 1,
    PPPAGSEGURO_DEBIT = 2,
    PPPAGSEGURO_VOUCHER = 3
} enPPPSPaymentMethod;

typedef enum {
    PPPAGSEGURO_A_VISTA = 1,
    PPPAGSEGURO_PARC_VENDEDOR = 2
} enPPPSInstallmentType;

typedef char tyComPort [PPPS_COMPORT_LEN];
typedef char tyAmount [PPPS_TRS_CODE_LEN];
typedef char tyUserReference [PPPS_USER_REFERENCE_LEN];
typedef struct {
    char rawBuffer  [PPPS_RAW_BUFFER_LEN];
    char message  [PPPS_MESSAGE_LEN];
    char transactionCode  [PPPS_TRS_CODE_LEN];
    char date  [PPPS_DATE_LEN];
    char time  [PPPS_TIME_LEN];
    char hostNsu  [PPPS_TRS_HOSTNSU_LEN];
    char cardBrand  [PPPS_CARD_BRAND_LEN];
    char bin  [PPPS_BIN_LEN];
    char holder [PPPS_HOLDER_LEN];
    char userReference [PPPS_USER_REFERENCE_LEN];
    char terminalSerialNumber [PPPS_TERMINAL_SERIAL_NUMBER_LEN];
} stPPPSTransactionResult;

Métodos

Método Retorno Descrição
GetVersionLib const char* Retorna uma string null terminated com a versão da biblioteca de integração.
SetVersionName Int Seta o nome e versão da aplicação que está utilizando a PlugPag. É MANDATÓRIO que esta função seja chamada antes de se realizar qualquer transação.
InitBTConnection Nenhum Configura a porta com que está pareada com a Moderninha. Deve ser passada a porta que foi mapeada seguindo as instruções em Mapeando device bluetooth
SimplePaymentTransaction Int Inicia a transação de venda. Em caso de sucesso, retorna os dados da transação numa estrutura.
CancelTransaction Int Inicia a transação de estorno. Em caso de sucesso, retorna os dados da transação numa estrutura
GetLastApprovedTransactionStatus Int Verifica qual foi a última transação com sucesso feita pelo terminal.

Efetuando uma Solicitação de Pagamento

Para efetuar uma chamada para a Moderninha PRO, você deve utilizar o método SimplePaymentTransaction. Veja abaixo alguns exemplos de uma solicitação de venda:

    int ret;
    tyComPort comPort;
    enPPPSPaymentMethod paymentMethod;
    enPPPSInstallmentType installmentType;
    unsigned int installment;
    tyAmount amount;
    tyUserReference userReference;
    tyAppName appName;
    tyAppVersion appVersion;
    stPPPSTransactionResult transactionResult;

    memset ((void*) comPort, 0, sizeof (tyComPort));
    memset ((void*) amount, 0, sizeof (tyAmount));
    memset ((void*) userReference, 0, sizeof (tyUserReference));
    memset ((void*) appName, 0, sizeof (tyAppName));
    memset ((void*) appVersion, 0, sizeof (tyAppVersion));

    // Porta COM11 está com a Moderninha pareada no Bluetooth
    memcpy (comPort, "COM11", 5);

    // Pagamento no débito
    paymentMethod = PPPAGSEGURO_DEBIT;
    // A vista (1 parcela)
    installmentType = PPPAGSEGURO_A_VISTA;
    installment = 1;

    // R$ 30,00 Reais
    memcpy (amount, "3000", 4);

    // Meu código de venda é "0000000001"
    memcpy (userReference, "0000000001", 10);

    InitBTConnection (comPort);

    // Setar o nome e versão da aplicação
    memcpy (appName, "MyApplication", 13);
    memcpy (appVersion, "R001", 4);

    SetVersionName(appName, appVersion);

    ret = SimplePaymentTransaction (
        paymentMethod,
        installmentType,
        installment,
        &amount,
        &userReference,
        &transactionResult
    );
    int ret;
    tyComPort comPort;
    enPPPSPaymentMethod paymentMethod;
    enPPPSInstallmentType installmentType;
    unsigned int installment;
    tyAmount amount;
    tyUserReference userReference;
    tyAppName appName;
    tyAppVersion appVersion;
    stPPPSTransactionResult transactionResult;

    memset ((void*) comPort, 0, sizeof (tyComPort));
    memset ((void*) amount, 0, sizeof (tyAmount));
    memset ((void*) userReference, 0, sizeof (tyUserReference));
    memset ((void*) appName, 0, sizeof (tyAppName));
    memset ((void*) appVersion, 0, sizeof (tyAppVersion));

    // Porta COM11 está com a Moderninha pareada no Bluetooth
    memcpy (comPort, "COM11", 5);

    // Pagamento no crédito
    paymentMethod = PPPAGSEGURO_CREDIT;
    //(7 parcelas)
    installmentType = PPPAGSEGURO_PARC_VENDEDOR;
    installment = 7;

    // R$ 200,00 Reais
    memcpy (amount, "20000", 4);

    // Meu código de venda é "CODIGVENDA"
    memcpy (userReference, "CODIGVENDA", 10);

    InitBTConnection (comPort);

    // Setar o nome e versão da aplicação
    memcpy (appName, "MyApplication", 13);
    memcpy (appVersion, "R001", 4);

    SetVersionName(appName, appVersion);

    ret = SimplePaymentTransaction (
        paymentMethod,
        installmentType,
        installment,
        &amount,
        &userReference,
        &transactionResult
    );

Assim que a chamada é feita, a Moderninha PRO iniciará o processo de venda com os parâmetros encaminhados pela sua aplicação. Você pode configurar a Solicitação de Pagamento a partir dos parâmetros que são passados para o método SimplePaymentTransaction. Veja abaixo a listagem dos parâmetros:

Parâmetro Tipo Descrição
comPort *tyComPort Porta COM mapeada para Bluetooth e já pareada com a Moderninha PRO.
paymentMethod enPPPSPaymentMethod Tipo de transação: credito, debito ou voucher.
installmentType enPPPSInstallmentType Tipo de parcelamento: à vista ou parcelado.
installment unsigned int Número de parcelas. Caso seja pagamento à vista, valor deve ser 1.
amount *tyAmount Valor da transação, com 2 para centavos, sem pontos e virgulas. Ex: "R$ 1.234,56" deve ser passado como "123456".
reference *tyUserReference Código da venda, definido pela sua aplicação.

Os tipos customizados são definidos da seguinte maneira:

Tipo Definição
tyComPort char[8]
enPPPSPaymentMethod enum {PPPAGSEGURO_CREDIT = 1, PPPAGSEGURO_DEBIT = 2, PPPAGSEGURO_VOUCHER = 3}
enPPPSInstallmentType enum {PPPAGSEGURO_A_VISTA = 1, PPPAGSEGURO_PARC_VENDEDOR = 2}
tyAmount char[33]
tyUserReference char[21]

A configuração da Solicitação de Pagamento deve seguir estas regras:

  • Não é possível realizar pagamentos de menos de R$ 1,00;
  • Pagamentos parcelados podem ser divididos em no máximo 12 parcelas;
  • Pagamentos parcelados devem ter valor mínimo de parcela de R$ 5,00.

O último parâmetro do método SimplePaymentTransaction é um ponteiro para uma estrutura que, ao fim da execução do método, estará populada com os dados do retorno da transação efetuada na Moderninha PRO. A estrutura é apresentada no item Dados

Outro ponto importante é o código de referência (ou código de venda) que pode ser encaminhado pela sua aplicação. Este parâmetro pode conter o seu número de ordem ou pedido para que você possa efetuar a conciliação dos seus pagamentos posteriormente.

Consultando a última transação

Sua aplicação pode obter os dados da última transação efetuada com sucesso em sua Moderninha PRO. Para isso você deve utilizar o método GetLastApprovedTransactionStatus(). Veja o exemplo abaixo:

    int ret;
    tyComPort portaCom;

    memset ((void*) portaCom, 0, sizeof (portaCom));

    // Porta COM11 está com a Moderninha Pro pareada no Bluetooth
    memset (portaCom, "COM11", 5);

    ret = GetLastApprovedTransactionStatus (&comPort, &transactionResult);

O último parâmetro do método GetLastApprovedTransactionStatus é um ponteiro para uma estrutura que, ao fim da execução do método, estará populada com os dados do retorno da transação efetuada na Moderninha PRO. A estrutura é apresentada no item Dados.

Estornando uma Transação

Sua aplicação também pode iniciar um processo de estorno de transação. É importante salientar que esta chamada apenas inicia o processo de estorno. Os demais passos são feitos diretamente na moderninha. Veja exemplo a seguir:

    int ret;
    tyComPort portaCom;

    memset ((void*) portaCom, 0, sizeof (portaCom));

    // Porta COM11 está com a Moderninha Pro pareada no Bluetooth
    memset (portaCom, "COM11", 5);

    ret = CancelTransaction (&portaCom, &transactionResult);

O último parâmetro do método CancelTransaction é um ponteiro para uma estrutura que, ao fim da execução do método, estará populada com os dados do retorno da transação efetuada na Moderninha PRO. A estrutura é apresentada no item Dados.

Listagem de erros

Todas a funções da API seguem os mesmos tipos de código retorno, conforme a tabela a seguir:

Valor Descrição Ação
0 Transação autorizada
-1001 Mensagem gerada maior que buffer dimensionado Coletar log (se existir) e enviar para o suporte.
-1002 Parâmetro de aplicação inválido Coletar log (se existir) e enviar para o suporte.
-1003 Terminal não está pronto para transacionar Tente novamente.
-1004 Transação negada pelo Host. Verificar mensagem no terminal.
-1005 Buffer de resposta da transação inválido ao obter as informações de resultado da transação Refaça a transação.
-1006 Parâmetro de valor da transação não pode ser nulo Verificar implementação da chamada da biblioteca.
-1007 Parâmetro de valor total da transação não pode ser nulo Verificar implementação da chamada da biblioteca.
-1008 Parâmetro de código de venda não pode ser nulo Verificar implementação da chamada da biblioteca.
-1009 Parâmetro de resultado da transação não pode ser nulo Verificar implementação da chamada da biblioteca.
-1010 Driver de conexão não encontrado Verificar se todos os arquivos estão no diretório correto.
-1011 Erro ao utilizar driver não encontrado Reinstalar os arquivos do driver de conexão
-1012 Formato do valor da venda invalido Valor deve ser um número inteiro sem virgula
-1013 Comprimento do REF superior a 10 dígitos Truncar REF para no máximo 10 dígitos
-1014 Buffer de recepção corrompido Refaça a transação
-1015 Nome da aplicação maior que 25 caracteres Limitar nome da aplicação a 25 caracteres
-1016 Versão da aplicação maior que 10 caracteres Limitar versão da aplicação em 10 caracteres
-1017 Necessário definir nome da aplicação Definir nome e versão da aplicação com SetVersionName()
-1018 Não existe dados da última transação Refaça a transação
-1019 Erro de comunicação com terminal (resposta inesperada) Realizar consulta de última transação
-2001 Porta COM informada não encontrada Informar uma porta COM válida.
-2002 Não foi possível obter configurações da porta COM informada Informar uma porta COM válida.
-2003 Não foi possível configurar a porta COM informada Informar uma porta COM válida.
-2004 Timeout de comunicação Bluetooth Refaça a transação.
-2005 Não foi possível enviar dados pela porta COM informada Informar uma porta COM válida.

Ainda não tem a sua Moderninha PRO? Adquira a sua agora em https://loja.pagseguro.uol.com.br/