PlugPag para iOS

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

Visão Geral
Pareando a sua Moderninha PRO
Importando a biblioteca
Efetuando uma Solicitação de Pagamento
Estornando uma Transação
Consultando a última transação
Aplicação Exemplo
Listagem de erros

Visão Geral

Se você tem um aplicativo iOS e quer fazer vendas a partir dele usando a sua Moderninha PRO, o PlugPag é a solução ideal. Com ele você consegue conectar o seu app à Moderninha PRO e realizar cobranças através do PagSeguro.

Versão

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

Imagem 2

Caso sua Moderninha PRO não esteja na versão 3.12.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

O pareamento com a Moderninha PRO deve ser feito em nível de aplicação. Sendo que para fazer o mesmo basta seguir os passos a seguir e a Moderninha PRO estar com o bluetooth visível(apertar a tecla '0' com bluetooth ativado).

Primeiramente deve ser executado o comando GetListModels e SetModel, para que seja identificado, quais modelos de moderninhas visiveis estão próximos do dispositivo iOS e qual será o modelo utilizado.

NSArray *models = [[PlugPag sharedInstance] GetListModels];
NSLog(@"%@", models); //Retornado por exemplo @[@“D200”, @”S920”]

[[PlugPag sharedInstance] SetModel:[models objectAtIndex:2]]; // Selecionado Moderninha PRO (S920)

Após selecionado o modelo de moderninha que será utilizado devem ser executados os comandos GetListPeripheral e SetPeripheralName, para identificar as moderninhas próximas visiveis do modelo escolhido anteriormente e selecionar qual será pareada.

NSArray *devices = [[PlugPag sharedInstance] GetListPeripheral];
NSLog(@"%@", devices); //Retornado por exemplo @[@“PRO-10001384”, @”PRO-10001485”]

if ([devices count] > 0) {
    [[PlugPag sharedInstance] SetPeripheralName:[devices objectAtIndex:1]]; //Selecionado PRO-10001384
}

Fluxo Alternativo:

Caso não seja necessário o pareamento dinâmico onde é identificado os terminais próximos, pode-se utilizar o método SetPeripheralName: withName. Para isso basta informar todos os dados do terminal em qual se deseja conectar. Lembrando que a Moderninha PRO deve estar com bluetooth visível.

[[PlugPag sharedInstance] SetPeripheral:@"S920" withName:@"PRO-10001384"];

Não é necessário qualquer forma de autenticação (login). A identificação de usuário é feita diretamente na Moderninha PRO.

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

Importando a biblioteca

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

  • Primeiramente é necessário inserir os arquivos libBTSerial.a e libPlugPag.a no Build Phases -> Link Binary with Libraries do seu projeto.

  • Em seguida inclua o arquivo PlugPag.h no seu projeto, caso esteja usando Swift não esqueça de criar um arquivo Bridging-Header e importa-lo.

  • Por último no Build Setting do seu projeto altere Enable Bitcode para No.

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* 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 já está autenticada e vinculada a uma conta PagSeguro.

Dados

#import <Foundation/Foundation.h>

#define RET_OK                          0
#define ERR_BASE                        -1000
#define BUFF_SIZE                       ERR_BASE-1
#define NULL_PTR                        ERR_BASE-2
#define POS_NOT_READY                   ERR_BASE-3
#define TRANS_DENIED                    ERR_BASE-4
#define DATA_INV_RESULT_MESSAGE         ERR_BASE-5

#define INV_AMOUNT_PARAM                ERR_BASE-6
#define INV_TOT_AMOUNT_PARAM            ERR_BASE-7
#define INV_USER_REF_PARAM              ERR_BASE-8
#define INV_TRS_RESULT_PARAM            ERR_BASE-9
#define DRIVER_NOT_FOUND                ERR_BASE-10
#define DRIVER_FUNCTION_ERROR           ERR_BASE-11
#define INV_FORMAT_AMOUNT_PARAM         ERR_BASE-12
#define INV_LEN_USER_REF_PARAM          ERR_BASE-13
#define INVALID_BUFFER                  ERR_BASE-14
#define INV_APP_NAME_PARAM              ERR_BASE-15
#define INV_APP_VERSION_PARAM           ERR_BASE-16
#define APP_NAME_VERSION_NOT_SET        ERR_BASE-17
#define TRANS_NODATA                    ERR_BASE-18
#define COMMUNICATION_ERROR             ERR_BASE-19
#define ERROR_DEVICE_NULL               ERR_BASE-1027

#define CREDIT                          1
#define DEBIT                           2

#define A_VISTA                         1
#define PARC_VENDEDOR                   2
@property (nonatomic, assign) unsigned char rawBuffer;
@property (nonatomic, strong) NSString *message; //Cod. ISO-8859-1 (Latin-1)
@property (nonatomic, strong) NSString *transactionCode;
@property (nonatomic, strong) NSString *date;
@property (nonatomic, strong) NSString *time;
@property (nonatomic, strong) NSString *hostNsu;
@property (nonatomic, strong) NSString *cardBrand;
@property (nonatomic, strong) NSString *bin;
@property (nonatomic, strong) NSString *holder;
@property (nonatomic, strong) NSString *userReference;
@property (nonatomic, strong) NSString *terminalSerialNumber;

Métodos

Método Retorno Descrição
GetVersionLib const char* Retorna uma const char com a versão da biblioteca de integração.
SetVersionName: withVersion 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 Int Inicializa a comunicação blutooth utilizando o dispositivo padrão do aparelho iOS.
SimplePaymentTransaction: withInstallmentType: endInstallments: endAmount 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.
SetModel nenhum Seta o modelo do terminal PagSeguro que a PlugPag vai parear e conectar via bluetooth
SetPeripheralName nenhum Seta o ID do terminal PagSeguro que a PlugPag vai parear e conectar via Bluetooth (O ID pode ser encontrado ao pressionar a tecla '0' no terminal).
SetPeripheral:withName nenhum Seta o modelo do terminal e o ID do terminal PagSeguro que a PlugPag vai parear e conectar via Bluetooth.
GetListModels NSArray (NSArray de Strings) Retorna uma lista de modelos de terminais PagSeguro disponível para pareamento via Bluetooth.
GetListPeripheral NSArray (NSArray de Strings) Retorna uma lista de terminais PagSeguro disponíveis para pareamento via Bluetooth de acordo com o modelo selecionado. Limitação: Deve ser Chamado apóster informado o modelo desejado através do método SetModel

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:

[[PlugPag sharedInstance] SetVersionName:@"MyApp" withVersion:@"R001"];
int ret = [[PlugPag sharedInstance] InitBTConnection];

    if (ret == RET_OK) {

        // Transação de 12,34
        NSString * value = @"1234";

        // Venda, Crédito, A Vista, R$ 12,34
        ret = [[PlugPag sharedInstance] SimplePaymentTransaction:CREDIT withInstallmentType:A_VISTA andInstallments:1 andAmount:value andUserReference:@"CODIGVENDA"];

        if (ret == RET_OK) {
            _txtResultado.text = @"Transação realizada com sucesso";
        }else{
            _txtResultado.text = [NSString stringWithFormat:@"Erro: %d", ret];
        }
    }else{
        _txtResultado.text = [NSString stringWithFormat:@"Erro: %d", ret];
    }
[[PlugPag sharedInstance] SetVersionName:@"MyApp" withVersion:@"R001"];
int ret = [[PlugPag sharedInstance] InitBTConnection];

    if (ret == RET_OK) {

        // Transação de 1208,34
        NSString * value = @"128034";

        // A vista, 7 parcelas
        int numeroParcelas = 7;

        // Venda, Crédito, Parcelado Vendedor, 7 parcelas, R$ 1.208,34
        ret = [[PlugPag sharedInstance] SimplePaymentTransaction:CREDIT withInstallmentType:PARC_VENDEDOR andInstallments:numeroParcelas andAmount:value andUserReference:@"CODIGVENDA"];

        if (ret == RET_OK) {
            _txtResultado.text = @"Transação realizada com sucesso";
        }else{
            _txtResultado.text = [NSString stringWithFormat:@"Erro: %d", ret];
        }
    }else{
        _txtResultado.text = [NSString stringWithFormat:@"Erro: %d", ret];
    }

Estornando uma Transação

Para iniciar uma transação de estorno na Moderninha PRO, acompanhe o exemplo a seguir:

int ret = [[PlugPag sharedInstance] InitBTConnection];

    if (ret == RET_OK) {

        // Estorno
        ret = [[PlugPag sharedInstance] CancelTransaction];

        if (ret == RET_OK) {
            _txtResultado.text = @"Estorno realizado com sucesso";
        }else{
            _txtResultado.text = [NSString stringWithFormat:@"Erro: %d", ret];
        }

    }else{
        _txtResultado.text = [NSString stringWithFormat:@"Erro: %d", ret];
    }

Consultando a última transação aprovada

Para consultar a última transação aprovada na Moderninha PRO, acompanhe o exemplo a seguir:

int ret = [[PlugPag sharedInstance] InitBTConnection];

    if (ret == RET_OK) {

        // Consulta a última transação
        ret = [[PlugPag sharedInstance] GetLastApprovedTransactionStatus];

        if (ret == RET_OK) {

            NSString *txDate = [PlugPag sharedInstance].date;
            NSString *txTime = [PlugPag sharedInstance].time;
            NSString *txHost = [PlugPag sharedInstance].hostNsu;
            NSString *txCardBrand = [PlugPag sharedInstance].cardBrand;

        }else{
            _txtResultado.text = [NSString stringWithFormat:@"Erro: %d", ret];
        }

    }else{
        _txtResultado.text = [NSString stringWithFormat:@"Erro: %d", ret];
    }
  • Caso exista uma transação em andamento no momento da consulta, a função GetLastApprovedTransactionStatus() aguarda a finalização da transação e retorna os dados desta se aprovada (nessessário biblioteca 1.3.0+ e moderninha 3.12+).

Aplicação Exemplo

A aplicação de exemplo está disponível no GitHub. Basta acessar o link de acordo com a linguagem desejada:

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
-1020 Transação Bluetooth não permitida quando o terminal está em modo compartilhado Desativar modo compartilhado
-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.
-2022 Adaptador Null Verificar implementação
-2023 erro em DeviceToUse Coletar log (se existir) e enviar para o suporte.
-2024 erro no serviço RfcommSocket Coletar log (se existir) e enviar para o suporte.
-2026 Close exception Coletar log (se existir) e enviar para o suporte.
-2027 Não foi possível estabelecer conexão Bluetooth Tente novamente.
-2028 Não foi possível abrir socket ou stream Tente novamente.
-2029 Socket null Coletar log (se existir) e enviar para o suporte.
-2030 Exception no buffer de saída Coletar log (se existir) e enviar para o suporte.
-2031 Exception no buffer de entrada Coletar log (se existir) e enviar para o suporte.
-2032 Exception ao fechar socket Coletar log (se existir) e enviar para o suporte.
-2033 Read timeout Tente novamente
-2036 Exception ao enviar buffer Coletar log (se existir) e enviar para o suporte.
-2037 Exception ao limpar buffer de envio Coletar log (se existir) e enviar para o suporte.
-2038 Exception buffer de envio nulo Coletar log (se existir) e enviar para o suporte.
-3000 Erro na camada de integração com a biblioteca Coletar log (se existir) e enviar para o suporte.

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