5. Funções da Biblioteca
Este capítulo define as funções exportadas pela biblioteca do Pay&Go Web, separadas em duas
categorias:
• Funções de controle do fluxo transacional;
• Funções para interação com o PIN-pad.
5.1. Funções de controle do fluxo transacional
Estas funções são utilizadas para iniciar uma operação, alimentar o sistema com os dados
necessários, executar a transação, obter os dados resultantes desejados e enfim confirmar a
transação, conforme fluxo apresentado em “4.1 - Fluxo principal”
PW_iInit
Esta função é utilizada para inicializar a biblioteca, e retorna imediatamente. Deve ser garantido que
uma chamada dela retorne PWRET_OK antes de chamar qualquer outra função.
Int16 PW_iInit
(const char *pszWorkingDir);
➜ Entradas:
pszWorking
Dir Diretório de trabalho (caminho completo, com final nulo) para uso exclusivo do Pay&Go Web.
➜ Saídas:
Nenhuma
➜ Retorno:
PWRET_OK..................................Operação bem sucedida.
PWRET_WRITERR ....................... Falha de gravação no diretório informado.
PWRET_INVCALL......................... Já foi efetuada uma chamada à função PW_iInit após o carregamento da biblioteca.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma
mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG).
➜ Observações:
• Os operadores do Ponto de Captura (que venham a realizar transações através do Pay&Go Web)
devem ter privilégios de leitura e gravação neste diretório.
• O diretório deve ser o mesmo para todos os usuários do sistema, e não deve ser alterado de uma
execução para outra
PW_iNewTransac
Esta função deve ser chamada para iniciar uma nova transação através do Pay&Go Web, e retorna
imediatamente.
Importante: independentemente das funcionalidades suportadas pela Automação e pelo Ponto de
Captura, é requerido que a Automação disponibilize ao operador uma função para realizar uma
transação administrativa (PWOPER_ADMIN), para permitir o acesso às funções de manutenção do
Pay&Go Web. Caso desejado, o acesso a este recurso pode ser restrito a operadores específicos.
Int16 PW_iNewTransac
(Byte bOper);
➜ Entradas:
bOper
Tipo de transação a ser realizada (PWOPER_xxx, conforme tabela abaixo).
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK.................................. Transação inicializada.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
PWRET_NOTINST........................ É necessário efetuar uma transação de Instalação.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG).
Lista de transações suportadas:
Nome | Valor | Descrição |
---|---|---|
PWOPER_NULL | 00h | Testa comunicação com a infraestrutura do Pay&Go Web. |
PWOPER_INSTALL | 01h | Registra o Ponto de Captura perante a infraestrutura do Pay&Go Web, para que seja autorizado a realizar transações. |
PWOPER_PARAMUPD | 02h | Obtém da infraestrutura do Pay&Go Web os parâmetros de operação atualizados do Ponto de Captura. |
PWOPER_REPRINT | 10h | Obtém o último comprovante gerado por uma transação. |
PWOPER_RPTTRUNC | 11h | Obtém um relatório sintético das transações realizadas desde a última obtenção deste relatório. |
PWOPER_RPTDETAIL | 12h | Relatório detalhado das transações realizadas na data informada, ou data atual. |
PWOPER_ADMIN | 20h | Acessa qualquer transação que não seja disponibilizada pelo comando PWOPER_SALE. Um menu é apresentado para o operador selecionar a transação desejada. |
PWOPER_SALE | 21h | (Venda) Realiza o pagamento de mercadorias e/ou serviços vendidos pelo Estabelecimento ao Cliente (tipicamente, com cartão de crédito/débito), transferindo fundos entre as respectivas contas. |
PWOPER_SALEVOID | 22h | (Cancelamento de venda) Cancela uma transação PWOPER_SALE, realizando a transferência de fundos inversa |
PWOPER_PREPAID | 23h | Realiza a aquisição de créditos pré-pagos (por exemplo, recarga de celular). |
PWOPER_CHECKINQ | 24h | Consulta a validade de um cheque papel. |
PWOPER_RETBALINQ | 25h | Consulta o saldo/limite do Estabelecimento (tipicamente, limite de crédito para venda de créditos pré-pagos). |
PWOPER_CRDBALINQ | 26h | Consulta o saldo do cartão do Cliente. |
PWOPER_INITIALIZ | 27h | (Inicialização/abertura) Inicializa a operação junto ao Provedor e/ou obtém/atualiza os parâmetros de operação mantidos por este. |
PWOPER_SETTLEMNT | 28h | (Fechamento/finalização) Finaliza a operação junto ao Provedor. |
PWOPER_PREAUTH | 29h | (Pré-autorização) Reserva o valor correspondente a uma venda no limite do cartão de crédito de um Cliente, porém sem efetivar a transferência de fundos. |
PWOPER_PREAUTVOID | 2Ah | (Cancelamento de pré-autorização) Cancela uma transação PWOPER_PREAUTH, liberando o valor reservado no limite do cartão de crédito. |
PWOPER_CASHWDRWL | 2Bh | (Saque) Registra a retirada de um valor em espécie pelo Cliente no Estabelecimento, para transferência de fundos nas respectivas contas. |
PWOPER_LOCALMAINT | 2Ch | (Baixa técnica) Registra uma intervenção técnica no estabelecimento perante o Provedor. |
PWOPER_FINANCINQ | 2Dh | Consulta as taxas de financiamento referentes a uma possível venda parcelada, sem efetivar a transferência de fundos ou impactar o limite de crédito do Cliente. |
PWOPER_ADDRVERIF | 2Eh | Verifica junto ao Provedor o endereço do Cliente. |
PWOPER_SALEPRE | 2Fh | Efetiva uma pré-autorização (PWOPER_PREAUTH), previamente realizada, realizando a transferência de fundos entre as contas do Estabelecimento e do Cliente. |
PWOPER_LOYCREDIT | 30h | Registra o acúmulo de pontos pelo Cliente, a partir de um programa de fidelidade. |
PWOPER_LOYCREDVOID | 31h | Cancela uma transação PWOPER_LOYCREDIT. |
PWOPER_LOYDEBIT | 32h | Registra o resgate de pontos/prêmio pelo Cliente, a partir de um programa de fidelidade. |
PWOPER_LOYDEBVOID | 33h | Cancela uma transação PWOPER_LOYDEBIT. |
PWOPER_VOID | 39h | Exibe um menu com os cancelamentos disponíveis, caso só exista um tipo, este é selecionado automaticamente. |
PWOPER_VERSION | FCh | (Versão) Permite consultar a versão da biblioteca atualmente em uso. |
PWOPER_CONFIG | FDh | (Configuração) Visualiza e altera os parâmetros de operação locais da biblioteca. |
PWOPER_MAINTENANCE | FEh | (Manutenção) Apaga todas as configurações do Ponto de Captura, devendo ser novamente realizada uma transação de Instalação |
PW_iAddParam
Esta função é utilizada para alimentar a biblioteca com as informações da transação a ser realizada, e
retorna imediatamente. Estas informações podem ser:
• Pré-fixadas na Automação;
• Capturadas do operador pela Automação antes do acionamento do Pay&Go Web;
• Capturadas do operador após solicitação pelo Pay&Go Web (retorno PW_MOREDATA por
PW_iExecTransac).
Int16 PW_iAddParam
(Word wParam, const char *pszValue);
➜ Entradas:
wParam
Identificador do parâmetro (PWINFO_xxx, ver lista completa em “9. Dicionário de dados”).
pszValue
Valor do parâmetro (string ASCII com final nulo).
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK.................................. Parâmetro acrescentado com sucesso.
PWRET_INVPARAM....................O valor do parâmetro é inválido.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
PWRET_TRNNOTINIT..................Não foi executado PW_iNewTransac (ver página 13).
PWRET_NOTINST........................ É necessário efetuar uma transação de Instalação.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma
mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG).
➜ Observações adicionais:
• Os parâmetros abaixo devem obrigatoriamente ser informados pela Automação a cada
transação, qualquer que seja.
Nome | Descrição |
---|---|
PWINFO_AUTNAME | Nome do aplicativo de Automação. |
PWINFO_AUTVER | Versão do aplicativo de Automação. |
PWINFO_AUTDEV | Empresa desenvolvedora da Automação. |
PWINFO_AUTCAP | Capacidades da Automação. |
- Os parâmetros abaixo devem obrigatoriamente ser informados pela Automação para transações
dos seguintes tipos: PWOPER_SALE, PWOPER_SALEVOID, PWOPER_PREAUTH,
PWOPER_CASHWDRWL e PWOPER_SALEPRE.
Nome | Descrição |
---|---|
PWINFO_TOTAMNT | Valor total da transação. |
PWINFO_CURRENCY | Moeda. |
PWINFO_CURREXP | Expoente da moeda. |
- Os parâmetros abaixo devem obrigatoriamente ser informados pela Automação para transações
dos seguintes tipos: PWOPER_SALEVOID, PWOPER_PREAUTVOID e PWOPER_SALEPRE.
Nome | Descrição |
---|---|
PWINFO_TRNORIGDATE | Data da transação original |
PWINFO_TRNORIGNSU | NSU da transação original. |
PWINFO_TRNORIGAMNT | Valor da transação original. |
PWINFO_TRNORIGAUTH | Código de autorização da transação original. |
PWINFO_TRNORIGTIME | Hora da transação original. |
PW_iExecTransac
Esta função tenta realizar uma transação através do Pay&Go Web, utilizando os parâmetros
previamente definidos através de PW_iAddParam. Caso algum dado adicional precise ser informado,
o retorno será PWRET_MOREDATA e o parâmetro pvstParam retornará informações dos dados que
ainda devem ser capturados.
Esta função, por se comunicar com a infraestrutura Pay&Go Web, pode demorar alguns segundos
para retornar.
Int16 PW_iExecTransac
(PW_GetData pvstParam, Int16 piNumParam);
➜ Entradas:
piNumParam
Quantidade máxima de dados que podem ser capturados de uma vez, caso o retorno seja PW_MOREDATA. (Deve refletir o tamanho da área de memória apontada por pvstParam.) Valor sugerido: 9.
➜ Saídas:
pvstParam
Lista e características dos dados que precisam ser informados para executar a transação. Consultar “8.Captura de dados” para a descrição da estrutura e instruções para a captura de dados adicionais.
piNumParam
Quantidade de dados adicionais que precisam ser capturados (quantidade de ocorrências preenchidas em pvstParam).
➜ Retorno:
PWRET_OK.................................. Transação realizada com sucesso. Os resultados da transação devem ser obtidos através da função PW_iGetResult.
PWRET_NOTHING.......................Nada a fazer, fazer as validações locais necessárias e chamar a função
PW_iExecTransac novamente.
PWRET_MOREDATA................... Mais dados são requeridos para executar a transação.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
PWRET_TRNNOTINIT..................Não foi executado PW_iNewTransac.
PWRET_NOTINST........................ É necessário efetuar uma transação de Instalação.
PWRET_NOMANDATORY........... Algum dos parâmetros obrigatórios não foi adicionado.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG).
PW_iGetResult
Esta função pode ser chamada para obter informações que resultaram da transação efetuada,
independentemente de ter sido bem ou mal sucedida, e retorna imediatamente.
Int16 PW_iGetResult
(Int16 iInfo, char *pszData, Uint32 ulDataSize);
➜ Entradas:
iInfo
Código da informação solicitada sendo requisitada (PWINFO_xxx, ver lista completa em “9. Dicionário de dados”, página 70).
ulDataSize
Tamanho (em bytes) da área de memória apontada por pszData. Prever um tamanho maior que o máximo previsto para o dado solicitado.
➜ Saídas:
pszData
Valor da informação solicitada (string ASCII com terminador nulo).
➜ Retorno:
PWRET_OK.................................. Sucesso. pszData contém o valor solicitado.
PWRET_NODATA........................ A informação solicitada não está disponível.
PWRET_BUFOVFLW ...................O valor da informação solicitada não cabe em pszData.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
PWRET_TRNNOTINIT..................Não foi executado PW_iNewTransac.
PWRET_NOTINST........................ É necessário efetuar uma transação de Instalação.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”)
PW_iConfirmation
Esta função informa ao Pay&Go Web o status final da transação em curso (confirmada ou desfeita).
Consultar “7. Confirmação de transação” para informações adicionais.
Int16 PW_iConfirmation
(Uint32 ulResult, const char pszReqNum, const char pszLocRef, const char pszExtRef, const char pszVirtMerch, const char *pszAuthSyst);
➜ Entradas:
ulStatus
Resultado da transação (PWCNF_xxx, ver lista abaixo).
pszReqNum
Referência local da transação, obtida através de PW_iGetResult (PWINFO_REQNUM).
pszLocRef
Referência da transação para a infraestrutura Pay&Go Web, obtida através de PW_iGetResult (PWINFO_AUTLOCREF).
pszExtRef
Referência da transação para o Provedor, obtida através de PW_iGetResult (PWINFO_AUTEXTREF).
pszVirtMerch
Identificador do Estabelecimento, obtido através de PW_iGetResult (PWINFO_VIRTMERCH).
pszAuthSyst
Nome do Provedor, obtido através de PW_iGetResult (PWINFO_AUTHSYST).
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK..................................O status da transação foi atualizado com sucesso.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
PWRET_NOTINST........................ É necessário efetuar uma transação de Instalação.
PWRET_INVALIDTRN .................. A transação informada para confirmação não existe ou já foi confirmada anteriormente.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”)
➜ Observações:
• Caso a chamada a PW_iGetResult para um ou mais do parâmetros acima retorne erro, a
Automação deve informar o(s) parâmetro(s) correspondente(s) como NULL ou string vazia (“”)
Lista de status de confirmação possíveis:
Constante | Valor | Definição |
---|---|---|
PWCNF_CNF_AUTO | 0x00000121 | A transação foi confirmada pelo Ponto de Captura, sem intervenção do usuário. |
PWCNF_CNF_MANU_AUT | 0x00003221 | A transação foi confirmada manualmente na Automação |
PWCNF_REV_MANU_AUT | 0x00003231 | A transação foi desfeita manualmente na Automação. |
PWCNF_REV_PRN_AUT | 0x00013131 | A transação foi desfeita pela Automação, devido a uma falha na impressão do comprovante (não fiscal). A priori, não usar. Falhas na impressão não devem gerar desfazimento, deve ser solicitada a reimpressão da transação. |
PWCNF_REV_DISP_AUT | 0x00023131 | A transação foi desfeita pela Automação, devido a uma falha no mecanismo de liberação da mercadoria |
PWCNF_REV_COMM_AUT | 0x00033131 | A transação foi desfeita pela Automação, devido a uma falha de comunicação/integração com o ponto de captura (Cliente Pay&Go Web). |
PWCNF_REV_ABORT | 0x00043131 | A transação não foi finalizada, foi interrompida durante a captura de dados. |
PWCNF_REV_OTHER_AUT | 0x00073131 | A transação foi desfeita a pedido da Automação, por um outro motivo não previsto |
PWCNF_REV_PWR_AUT | 0x00083131 | A transação foi desfeita automaticamente pela Automação, devido a uma queda de energia (reinício abrupto do sistema). |
PWCNF_REV_FISC_AUT | 0x00093131 | A transação foi desfeita automaticamente pela Automação, devido a uma falha de registro no sistema fiscal (impressora S@T, on-line, etc.). |
PW_iIdleProc
Para o correto funcionamento do sistema, a biblioteca do Pay&Go Web precisa de tempos em
tempos executar tarefas automáticas enquanto não está realizando nenhuma transação a pedido da
Automação.
Após uma chamada de qualquer uma das funções PW_iInit, PW_iExecTransac, PW_iConfirmation ou
PW_iIdleProc, a Automação deve obter, através da função PW_iGetResult, o valor do parâmetro
PWINFO_IDLEPROCTIME, que indica o próximo horário no qual a Automação deve chamar
PW_iIdleProc.
Int16 PW_iIdleProc
(void);
➜ Entradas:
Nenhuma.
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK..................................Operação realizada com êxito.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
PWRET_NOTINST........................ É necessário efetuar uma transação de Instalação.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”).
PW_iGetOperations
Esta função pode ser chamada para obter quais operações o Pay&Go Web disponibiliza no momento,
sejam elas administrativas, de venda ou ambas.
Int16 PW_iGetOperations
(Byte bOperType, PW_Operations vstOperations[], Int16 *piNumOperations);
➜ Entradas:
bOperType
Soma dos tipos de operação a serem incluídos na estrutura de retorno (PWOPTYPE_xxx, conforme tabela abaixo).
piNumOperations
Número máximo de operações que pode ser retornado. (Deve refletir o tamanho da área de memória apontada por pvstOperations).
➜ Saídas:
piNumOperations
Número de operações disponíveis no Pay&Go Web.
vstOperations
Lista das operações disponíveis e suas características, descrição dos membros da
estrutura na tabela abaixo:
Nome | Tipo | Descrição |
---|---|---|
bOperType | Byte | Tipo da operação (PWOPTYPE_XXX). |
szText | char[] | Texto a ser exibido para seleção da operação. Caso a operação seja selecionada, esse valor deve ser adicionado como parâmetro pszValue na função PW_iAddParam, com o parâmetro wParam igual a PWINFO_LOCAINFO1. |
szValue | char[] | Caso a operação seja selecionada, valor a ser adicionado como parâmetro pszValue na função PW_iAddParam, com o parâmetro wParam igual a PWINFO_OPERATION. |
➜ Retorno:
PWRET_OK..................................Operação realizada com êxito.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
PWRET_NOTINST........................ É necessário efetuar uma transação de Instalação.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”)
Tipos de operação:
Nome | Valor | Descrição |
---|---|---|
PWOPTYPE_ADMIN | 1 | Operações administrativas (relatório, reimpressão, etc). |
PWOPTYPE_SALE | 2 | Operações financeiras. |
5.2. Funções para acesso ao PIN-pad
Essas funções são utilizadas para obtenção de dados do PIN-pad, exclusivamente quando solicitado
pelo retorno PWRET_MOREDATA da função PW_iExecTransac.
O uso das funções apresentadas nesta seção deve respeitar o fluxo apresentado em “4.2.2. Interface
com o PIN-pad”.
5.2.1. Funções de controle do fluxo
PW_iPPEventLoop
Esta função deve ser chamada repetidamente até que devolva em código de retorno diferente de
PWRET_NOTHING e PWRET_DISPLAY, e retorna imediatamente.
Int16 PW_iPPEventLoop
(char *pszDisplay, Uint32 ulDisplaySize);
➜ Entradas:
ulDisplaySize
Tamanho (em bytes) da área de memória apontada por pszDisplay. Tamanho mínimo recomendado: 100 bytes.
➜ Saídas:
pszDisplay
Caso o retorno da função seja PWRET_DISPLAY, contém uma mensagem de texto (string ASCII com terminal nulo) a ser apresentada pela Automação na interface com o usuário principal. Para o formato desta mensagem, consultar “4.2.1.Interface com o usuário”.
➜ Retorno:
PWRET_NOTHING.......................Nada a fazer, continuar aguardando o processamento do PIN-pad.
PWRET_DISPLAY......................... Apresentar a mensagem recebida em pszDisplay e continuar aguardando o processamento do PIN-pad.
PWRET_OK.................................. Captura de dados realizada com êxito, prosseguir com a transação.
PWRET_CANCEL.......................... A operação foi cancelada pelo Cliente no PIN-pad (tecla [CANCEL]).
PWRET_TIMEOUT.......................O Cliente não realizou a captura no tempo limite.
PWRET_FALLBACK ......................Ocorreu um erro na leitura do cartão, passar a aceitar a digitação do
número do cartão, caso já não esteja aceitando.
PWRET_PPCOMERR.................... Falha na comunicação com o PIN-pad.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
PWRET_INVCALL.........................Não há captura de dados no PIN-pad em curso.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma
mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG).
PW_iPPAbort
Esta função pode ser utilizada pela Automação para interromper uma captura de dados no PIN-pad
em curso, e retorna imediatamente.
Int16 PW_iPPAbort
(void);
➜ Entradas:
Nenhuma.
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK..................................Operação interrompida com sucesso.
PWRET_PPCOMERR.................... Falha na comunicação com o PIN-pad.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”)
5.2.2. Funções para obtenção de dados
Cada função desta seção inicia um processamento no PIN-pad, e retorna imediatamente.
Para determinar qual função deve ser chamada pela Automação, referir-se à seção “8.Captura de
dados”.
PW_iPPGetCard
Esta função é utilizada para realizar a leitura de um cartão (magnético, com chip com contato, ou
sem contato) no PIN-pad.
Int16 PW_iPPGetCard
(Uint16 uiIndex);
vEntradas:
uiIndex
Índice (iniciado em 0) do dado solicitado na última execução de PW_iExecTransac (índice do dado no vetor pvstParam).
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK.................... Captura iniciada com sucesso, chamar PW_iPPEventLoop para obter o resultado.
PWRET_INVPARAM.......O valor de uiIndex informado não corresponde a uma captura de dados deste tipo.
PWRET_DLLNOTINIT.....Não foi executado PW_iInit.
Outro..................................Outro erro de execução (ver “10. Códigos de retorno”). Uma mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG).
PW_iPPGetPIN
Esta função é utilizada para realizar a captura no PIN-pad da senha (ou outro dado criptografado) do
Cliente.
Int16 PW_iPPGetPIN
(Uint16 uiIndex);
➜ Entradas:
uiIndex
Índice (iniciado em 0) do dado solicitado na última execução de PW_iExecTransac (índice do dado no vetor pvstParam).
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK.................................. Captura iniciada com sucesso, chamar PW_iPPEventLoop para obter o
resultado.
PWRET_INVPARAM....................O valor de uiIndex informado não corresponde a uma captura de dados
deste tipo.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG).
PW_iPPGetData
Esta função é utilizada para fazer a captura no PIN-pad de um dado não sensível do Cliente.
Int16 PW_iPPGetData
(Uint16 uiIndex);
➜ Entradas:
uiIndex
Índice (iniciado em 0) do dado solicitado na última execução de PW_iExecTransac (índice do dado no vetor pvstParam).
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK.................................. Captura iniciada com sucesso, chamar PW_iPPEventLoop para obter o
resultado.
PWRET_INVPARAM....................O valor de uiIndex informado não corresponde a uma captura de dados
deste tipo.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG).
PW_iPPGoOnChip
Esta função é utilizada para realizar o processamento off-line (antes da comunicação com o Provedor) de um cartão com chip no PIN-pad.
Int16 PW_iPPGoOnChip
(Uint16 uiIndex);
➜ Entradas:
uiIndex
Índice (iniciado em 0) do dado solicitado na última execução de PW_iExecTransac
(índice do dado no vetor pvstParam).
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK.................................. Captura iniciada com sucesso, chamar PW_iPPEventLoop para obter o
resultado.
PWRET_INVPARAM....................O valor de uiIndex informado não corresponde a uma captura de dados
deste tipo.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma
mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG)
PW_iPPFinishChip
Esta função é utilizada para finalizar o processamento on-line (após comunicação com o Provedor) de
um cartão com chip no PIN-pad.
Int16 PW_iPPFinishChip
(Uint16 uiIndex);
➜ Entradas:
uiIndex
Índice (iniciado em 0) do dado solicitado na última execução de PW_iExecTransac (índice do dado no vetor pvstParam).
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK.................................. Captura iniciada com sucesso, chamar PW_iPPEventLoop para obter o
resultado.
PWRET_INVPARAM....................O valor de uiIndex informado não corresponde a uma captura de dados
deste tipo.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG).
PW_iPPConfirmData
Esta função é utilizada para obter do Cliente a confirmação de uma informação no PIN-pad.
Int16 PW_iPPConfirmData
(Uint16 uiIndex);
➜ Entradas:
uiIndex
Índice (iniciado em 0) do dado solicitado na última execução de PW_iExecTransac (índice do dado no vetor pvstParam).
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK.................................. Captura iniciada com sucesso, chamar PW_iPPEventLoop para obter o
resultado.
PWRET_INVPARAM....................O valor de uiIndex informado não corresponde a uma captura de dados
deste tipo.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG).
PW_iPPGenericCMD
Esta função é utilizada para realizar um comando genérico no PIN-pad.
Int16 PW_iPPGenericCMD
(Uint16 uiIndex);
➜ Entradas:
uiIndex
Índice (iniciado em 0) do dado solicitado na última execução de PW_iExecTransac (índice do dado no vetor pvstParam).
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK.................................. Captura iniciada com sucesso, chamar PW_iPPEventLoop para obter o
resultado.
PWRET_INVPARAM....................O valor de uiIndex informado não corresponde a uma captura de dados
deste tipo.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma
mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG).
PW_iPPDataConfirmation
Esta função é utilizada para realizar a confirmação positiva de um dado, ou um bloco de dados, no
PIN-pad.
Int16 PW_iPPDataConfirmation
(Uint16 uiIndex);
➜ Entradas:
uiIndex
Índice (iniciado em 0) do dado solicitado na última execução de PW_iExecTransac (índice do dado no vetor pvstParam).
➜ Saídas:
Nenhuma.
➜ Retorno:
PWRET_OK.................................. Captura iniciada com sucesso, chamar PW_iPPEventLoop para obter o
resultado.
PWRET_INVPARAM....................O valor de uiIndex informado não corresponde a uma captura de dados
deste tipo.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma
mensagem de erro pode ser obtida através da função PW_iGetResult
(PWINFO_RESULTMSG)
5.2.3. Outras funções
As funções descritas nesta seção permitem interagir com o PIN-pad fora do fluxo de uma transação.
Cada função desta seção inicia um processamento no PIN-pad, e retorna assim que possível.
PW_iPPDisplay
Esta função é utilizada para apresentar uma mensagem no PIN-pad.
Int16 PW_iPPDisplay
(const char *pszMsg)
Entradas:
pszMsg
Mensagem a ser apresentada no PIN-pad. O caractere ‘\r’ (0Dh) indica uma quebra de linha.
Saídas:
Nenhuma.
Retorno:
PWRET_OK.................................. Função iniciada com sucesso, chamar PW_iPPEventLoop para obter o
resultado.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”)
PW_iPPGetUserData
Esta função é utilizada para obter um dado digitado pelo portador do cartão no PIN-pad.
Int16 PW_iPPGetUserData
(Uint16 uiMessageId, Byte bMinLen, Byte bMaxLen, Int16
iToutSec, char *pszData);
Entradas:
uiMessageId
Identificador da mensagem a ser exibida como prompt para a captura, seguindo a
tabela abaixo:
Identificador | Mensagem apresentada |
---|---|
1 | DIGITE O DDD |
2 | REDIGITE O DDD |
3 | DIGITE O TELEFONE |
4 | REDIGITE O TELEFONE |
5 | DIGITE DDD+TELEFONE |
6 | REDIGITE DDD+TELEFONE |
7 | DIGITE O CPF |
8 | REDIGITE O CPF |
9 | DIGITE O RG |
10 | REDIGITE O RG |
11 | DIGITE OS 4 ULTIMOS DIGITOS |
12 | 12 DIGITE CODIGO DE SEGURANCA |
bMinLen
Tamanho mínimo do dado a ser digitado.
bMaxLen
Tamanho máximo do dado a ser digitado.
iToutSec
Tempo limite para a digitação do dado em segundos.
Saídas:
pszData
Dado digitado pelo portador do cartão no PIN-pad.
Retorno:
PWRET_OK.................................. Função iniciada com sucesso, chamar PW_iPPEventLoop para obter o
resultado.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
PWRET_NOTINST........................ É necessário efetuar uma transação de Instalação.
PWRET_CANCEL.......................... A operação foi cancelada pelo Cliente no PIN-pad (tecla [CANCEL]).
PWRET_TIMEOUT.......................O Cliente não realizou a captura no tempo limite.
PWRET_PPCOMERR.................... Falha na comunicação com o PIN-pad.
PWRET_INVCALL.........................Não é possível capturar dados em um PIN-pad não ABECS.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”).
PW_iPPWaitEvent
Esta função é utilizada para aguardar a ocorrência de um evento no PIN-pad.
Int16 PW_iPPWaitEvent
(Uint32 *pulEvent);
Entradas:
pulEvent
Soma dos valores referentes aos eventos a serem monitorados no PIN-pad:
Entradas: pulEvent Soma dos valores referentes aos eventos a serem monitorados no PIN-pad: | Valor | Evento |
---|---|---|
PWPPEVTIN_KEYS | 1 | Acionamento de teclas |
PWPPEVTIN_MAG | 2 | Passagem de cartão magnético |
PWPPEVTIN_ICC | 4 | Inserção de cartão com chip |
PWPPEVTIN_CTLS | 8 | Aproximação de um cartão sem contato. |
Saídas:
pulEvent
Evento ocorrido, conforme tabela abaixo.
Atenção: este dado somente é preenchido após retorno PWRET_OK de PW_iPPEventLoop.
Retorno:
PWRET_OK.................................. Captura iniciada com sucesso, chamar PW_iPPEventLoop para obter o
resultado.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”).
Constante | Valor | Definição |
---|---|---|
PWPPEVT_MAGSTRIPE | 01h | Foi passado um cartão magnético. |
PWPPEVT_ICC | 02h | Foi detectada a presença de um cartão com chip. |
PWPPEVT_CTLS | 03h | Foi detectada a presença de um cartão sem contato. |
PWPPEVT_KEYCONF | 11h | Foi pressionada a tecla [OK]. |
PWPPEVT_KEYBACKSP | 12h | Foi pressionada a tecla [CORRIGE]. |
PWPPEVT_KEYCANC | 13h | Foi pressionada a tecla [CANCELA]. |
PWPPEVT_KEYF1 | 21h | Foi pressionada a tecla [F1]. |
PWPPEVT_KEYF2 | 22h | Foi pressionada a tecla [F2]. |
PWPPEVT_KEYF3 | 23h | Foi pressionada a tecla [F3]. |
PWPPEVT_KEYF4 | 24h | Foi pressionada a tecla [F4]. |
PW_iPPRemoveCard
Esta função é utilizada para aguardar a remoção de um cartão com chip.
Int16 PW_iPPRemoveCard
(void);
Entradas:
Nenhuma.
Saídas:
Nenhuma.
Retorno:
PWRET_OK.................................. Captura iniciada com sucesso, chamar PW_iPPEventLoop para obter o
resultado.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”).
5.3. Outras funções
Estas funções permitem executar algumas funções fora do fluxo de uma transação. Geralmente,
funções de cunho administrativo.
PW_iTransactionInquiry
Esta função é utilizada para realizar uma consulta de transações efetuadas por um ponto de captura
junto ao Pay&Go Web.
Int16 PW_iTransactionInquiry
(const char pszXmlRequest, char pszXmlResponse, Uint32 ulXmlResponseLen);
Entradas:
ulXmlResponseLen
Tamanho da string pszXmlResponse.
pszXmlRequest
Arquivo de entrada no formato XML, contendo as informações necessárias para fazer
a consulta pretendida, seguindo o padrão abaixo:
Elemento | Elemento “pai” | Descrição |
---|---|---|
RequestTransactionHistory | - | Elemento raiz do arquivo XML. |
authentication | RequestTransactionHistory | Elemento que agrupa os dados necessários para autenticação no sistema. |
login | authentication | Usuário utilizado para autenticação. |
password | authentication | Senha utilizada para autenticação. |
QueryFilter | RequestTransactionHistory | Elemento que agrupa os filtros utilizados na consulta de transações |
TransactionAuthorizer | QueryFilter | Autorizador para o qual se deseja fazer a consulta. |
TransactionStartDate | QueryFilter | Data de início da consulta no formato “DD/MM/AAAA HH:MM:SS”. |
TransactionEndDate | QueryFilter | Data de fim da consulta no formato “DD/MM/AAAA HH:MM:SS”. |
ArrayOfTransactionType | QueryFilter | Elemento que agrupa os tipos de transação que se deseja consultar. |
TransactionType | ArrayOfTransactionType | Tipo de transação para o qual se deseja fazer a consulta (bOper utilizado na função PW_iNewTransac). |
ArrayOfTransactionStatus | QueryFilter | Elemento que agrupa os status das transações que se deseja consultar. |
TransactionStatus | ArrayOfTransactionStatus | Status de transação para o qual se deseja fazer a consulta (289 para transações aprovadas). |
Error | RequestTransactionHistory | - |
Number | Error | - |
Description | Error | - |
Saídas:
pszXmlResponse
Arquivo de saída no formato XML, contendo o resultado da consulta efetuada, o arquivo de saída tem todos os elementos do arquivo de entrada, com os dados abaixo adicionados:
Elemento | Elemento “pai” | Descrição |
---|---|---|
Transactions | RequestTransactionHistory | Elemento que agrupa as transações resultado da consulta. |
Transaction | Transactions | Elemento que agrupa as informações de uma transação. |
- | Transaction | O detalhamento de todas as informações retornadas de cada transação pode ser obtido no item Detalhamento Transactions |
Retorno:
PWRET_OK.................................. A consulta foi efetuada com sucesso.
PWRET_DLLNOTINIT...................Não foi executado PW_iInit.
Outro...........................................Outro erro de execução (ver “10. Códigos de retorno”). Uma mensagem de erro pode ser obtida através da função PW_iGetResult (PWINFO_RESULTMSG).
Exemplos:
pszXmlRequest
Arquivo XML de solicitação para as transações de venda (tipo de transação 33) aprovadas e confirmadas (status 289), efetuadas com o autorizador ELAVON, do dia 15/09/2016 até o dia 16/09/2016:
<RequestTransactionHistory xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" version="1.0.0.0">
<authentication>
<login>user</login>
<password>123456</password>
</authentication>
<QueryFilter>
<TransactionAuthorizer>ELAVON</TransactionAuthorizer>
<TransactionStartDate>15/09/2016 00:00:00</TransactionStartDate>
<TransactionEndDate>16/09/2016 23:59:59</TransactionEndDate>
<ArrayOfTransactionType>
<TransactionType>33</TransactionType>
</ArrayOfTransactionType>
<ArrayOfTransactionStatus>
<TransactionStatus>289</TransactionStatus>
</ArrayOfTransactionStatus>
</QueryFilter>
<Error>
<Number />
<Description />
</Error>
</RequestTransactionHistory>
pszXmlResponse
Arquivo XML de resposta com as transações efetuadas no período informado (2 transações foram retornadas):
<RequestTransactionHistory version="1.0.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<authentication>
<login>user</login>
<password>123456</password>
</authentication>
<QueryFilter>
<TransactionAuthorizer>ELAVON</TransactionAuthorizer>
<TransactionStartDate>15/09/2016 00:00:00</TransactionStartDate>
<TransactionEndDate>16/09/2016 23:59:59</TransactionEndDate>
<ArrayOfTransactionType>
<TransactionType>33</TransactionType>
</ArrayOfTransactionType>
<ArrayOfTransactionStatus>
<TransactionStatus>289</TransactionStatus>
</ArrayOfTransactionStatus>
</QueryFilter>
<Transactions>
<Transaction>
<UniqueId>329904</UniqueId>
<AuthorizerExternalReference>00000072328</AuthorizerExternalReference>
<InternalLocalReference>12</InternalLocalReference>
<Status>289</Status>
<POSTimestamp>15/09/2016 15:18:23</POSTimestamp>
<Type>33</Type>
<Amount>10000</Amount>
<Discount />
<CashBack />
<AuthorizerName>ELAVON</AuthorizerName>
<AuthorizerCode>ELAVON</AuthorizerCode>
<AuthorizationCode>024662</AuthorizationCode>
<ProductName>MASTERCARD</ProductName>
<ResultMessage>TRANSACAO AUTORIZADA </ResultMessage>
<ServerTimestamp>15/09/2016 15:18:23</ServerTimestamp>
<AffiliationNumber>001941400000000004226</AffiliationNumber>
<AuthorizationTimestamp />
<CurrencyExponent>2</CurrencyExponent>
<CurrencyCode>986</CurrencyCode>
<TransactionDetails>
<RequestPurpose>1</RequestPurpose>
<POSData>
<Identifier>50328</Identifier>
<Description>Terminal de testes</Description>
</POSData>
<PinPadData>
<SerialNumber>1931410242000008 </SerialNumber>
<Version>001.29 110310 </Version>
<Model>PPC910;3MB </Model>
<FirmwareVersion>0080_0072_0083_0106 </FirmwareVersion>
<SpecificationVersion>1.07</SpecificationVersion>
</PinPadData>
<CardData>
<CardBrand />
<Type>1</Type>
<CardName>Crédito</CardName>
</CardData>
<POSCompanyData>
<TaxId>03.361.770/0001-58</TaxId>
</POSCompanyData>
<FinancingData>
<Type>4</Type>
<DueDate />
<InstallmentsNumber>2</InstallmentsNumber>
</FinancingData>
<TopUpData />
<BankingAgentData />
</TransactionDetails>
</Transaction>
<Transaction>
<UniqueId>329909</UniqueId>
<AuthorizerExternalReference>00000072341</AuthorizerExternalReference>
<InternalLocalReference>21</InternalLocalReference>
<Status>289</Status>
<POSTimestamp>16/09/2016 10:28:28</POSTimestamp>
<Type>33</Type>
<Amount>3000</Amount>
<Discount />
<CashBack />
<AuthorizerName>ELAVON</AuthorizerName>
<AuthorizerCode>ELAVON</AuthorizerCode>
<AuthorizationCode>024664</AuthorizationCode>
<ProductName>VISA ELECTRON</ProductName>
<ResultMessage>TRANSACAO AUTORIZADA </ResultMessage>
<ServerTimestamp>16/05/2016 10:28:28</ServerTimestamp>
<AffiliationNumber>001941400000000004226</AffiliationNumber>
<AuthorizationTimestamp />
<CurrencyExponent>2</CurrencyExponent>
<CurrencyCode>986</CurrencyCode>
<TransactionDetails>
<RequestPurpose>1</RequestPurpose>
<POSData>
<Identifier>50328</Identifier>
<Description>Terminal de testes</Description>
</POSData>
<PinPadData>
<SerialNumber>1931410242000008 </SerialNumber>
<Version>001.29 110310 </Version>
<Model>PPC910;3MB </Model>
<FirmwareVersion>0080_0072_0083_0106 </FirmwareVersion>
<SpecificationVersion>1.07</SpecificationVersion>
</PinPadData>
<CardData>
<CardBrand />
<Type>2</Type>
<CardName>Débito</CardName>
</CardData>
<POSCompanyData>
<TaxId>03.361.770/0001-58</TaxId>
</POSCompanyData>
<FinancingData>
<Type>1</Type>
<DueDate />
<InstallmentsNumber>1</InstallmentsNumber>
</FinancingData>
<TopUpData />
<BankingAgentData />
</TransactionDetails>
</Transactions>
<Error>
<Number />
<Description />
</Error>
</RequestTransactionHistory>
5.4.Detalhamento Transactions
<?xml version="1.0" encoding="iso-8859-1"?>
<request version="1.0.0.0" id="">
<authentication>
<login></login>
<password></password>
</authentication>
<Transactions>
<QueryFilter>
<AuthorizerStatus/>
<MerchantLegalName/>
<MerchantTradeName/>
<MerchantTaxId/>
<POSIdentifier/>
<POSType/>
<POSPinPadSerialNumber/>
<POSApplication/>
<POSApplicationVersion/>
<ReqNum/>
<UniqueId/>
<TransactionType/>
<TransactionAuthorizer/>
<TransactionProductName/>
<TransactionStatus/>
<TransactionStartDate/>
<TransactionEndDate/>
<AuthorizerStatus/>
<LastUniqueIdSearched/>
<ArrayOfUniqueId>
<UniqueId/>
<UniqueId/>
</ArrayOfUniqueId>
<ArrayOfTransactionType>
<TransactionType/>
<TransactionType/>
</ArrayOfTransactionType>
<ArrayOfTransactionStatus>
<TransactionStatus/>
<TransactionStatus/>
</ArrayOfTransactionStatus>
</QueryFilter>
<Transaction>
<UniqueId/>
<ReqNum/>
<OriginalTransactionReqNum/>
<AuthorizerExternalReference/>
<InternalLocalReference/>
<Status/>
<POSTimestamp/>
<Type/>
<Amount/>
<Discount/>
<CashBack/>
<AuthorizerName/>
<AuthorizerCode/>
<AuthorizerStatus/>
<AuthorizationCode/>
<AuthorizationType/>
<ProductCode/>
<ProductName/>
<ResultCode/>
<ResultMessage/>
<ServerTimestamp/>
<AffiliationNumber/>
<ProcessingCode/>
<ResponseCode/>
<ResponseMessage/>
<FullReceiptCopy/>
<AuthorizationTimestamp/>
<CurrencyExponent/>
<CurrencyCode/>
<CurrencySymbol/>
<TaxIdentifier/>
<CardHolderVerificationFlags/>
<CardSecCodeEntryMode/>
<AdditionalDataArray>
<AdditionalData/>
<AdditionalData/>
<AdditionalDataArray>
<TransactionDetails>
<SpecificationVersion/>
<RequestMode/>
<RequestPurpose/>
<OperatingSystem/>
<ComputerName/>
<ComputerUserName/>
<Login/>
<POSData>
<ExternalId></ExternalId>
<Identifier></Identifier>
<Description></Description>
<Status></Status>
<POSType></POSType>
<CardEntryModes>
<CardEntryMode></CardEntryMode>
</CardEntryModes>
<CardEntryModes>
<CardEntryMode></CardEntryMode>
</CardEntryModes>
<CommGroup></CommGroup>
<CardTypes>
<CardType></CardType>
</CardTypes>
<CardTypes>
<CardType></CardType>
</CardTypes>
<InstallmentPlans>
<InstallmentPlan></InstallmentPlan>
</InstallmentPlans>
<InstallmentPlans>
<InstallmentPlan></InstallmentPlan>
</InstallmentPlans>
<Unattended></Unattended>
<FiscalPrinter></FiscalPrinter>
<Printer></Printer>
<Automation></Automation>
<PINPad></PINPad>
<PINPadIdleMsgLine1></PINPadIdleMsgLine1>
<PINPadIdleMsgLine2></PINPadIdleMsgLine2>
<ConnectedAffiliations>
<Authorizer></Authorizer>
<Number></Number>
</ConnectedAffiliations>
<ConnectedAffiliations>
<Authorizer></Authorizer>
<Number></Number>
</ConnectedAffiliations>
</POSData>
<PinPadData>
<SerialNumber/>
<Version/>
<Model/>
<FirmwareVersion/>
<SpecificationVersion/>
</PinPadData>
<CardData>
<CardBrand/>
<CardBIN/>
<EntryMode/>
<Type/>
<MaskedCardNumber/>
<CardName/>
<CardHolderName/>
<ExpirationDate/>
</CardData>
<POSCompanyData>
<LegalName></LegalName>
<TradeName></TradeName>
<Notes></Notes>
<Individual></Individual>
<PerformsTransactions></PerformsTransactions>
<DisplayName></DisplayName>
<TaxId></TaxId>
<City></City>
<State></State>
<Country></Country>
<PostalCode></PostalCode>
<MerchantGroup>
<Name></Name>
<Option>
<Name></Name>
</Option>
<Option>
<Name></Name>
</Option>
</MerchantGroup>
</POSCompanyData>
<AffiliationCompanyData>
<LegalName></LegalName>
<TradeName></TradeName>
<Notes></Notes>
<Individual></Individual>
<PerformsTransactions></PerformsTransactions>
<DisplayName></DisplayName>
<TaxId></TaxId>
<City></City>
<State></State>
<Country></Country>
<PostalCode></PostalCode>
<MerchantGroup>
<Name></Name>
<Option>
<Option>
<Name></Name>
</Option>
<Option>
<Name></Name>
</Option>
</Option>
</MerchantGroup>
</AffiliationCompanyData>
<FinancingData>
<Type/>
<DueDate/>
<InstallmentsNumber/>
</FinancingData>
<RetailAutomationDetails>
<Capabilities/>
<Company/>
<Name/>
<Version/>
</RetailAutomationDetails>
<TopUpData>
<AreaCode/>
<MaskedPhoneNumber/>
</TopUpData>
<BankingAgentData>
<BarCode/>
<DueDate/>
<EntryMode/>
<Discount/>
<Reduction/>
<Fee/>
<Amount/>
<TotalAmount/>
</BankingAgentData>
</TransactionDetails>
</Transaction>
</Transactions>
<Error>
<Number/>
<Description/>
</Error>
</request>
5.4.1.Considerações Iniciais
Dado Obrigatório (Mandatório) | M |
Dado Opcional | O |
Dado Ecoado | E |
String | S |
Interio (Int) | I |
Booleano | B |
Devolvido na resposta | R |
Ausente/Não necessário | X |
Condicional | C |
5.4.2.Tipos de Dados
QueryFilter Node
Campo | Tipo | GET | Tam. | Descrição |
---|---|---|---|---|
AuthorizerStatus | S | O | 1..2 | Status da Transação perante ao Autorizador. Veja Valores de Domínio. |
MerchantLegalName | S | O | 1..200 | Razão Social da empresa ou Nome do cadastrado no caso de ser pessoa física. |
MerchantTradeName | S | O | 1..100 | Nome Fantasia da Empresa. |
MerchantTaxID | S | O | 1..18 | Enviar o CPF caso se trate de pessoa física, enviar CNPJ caso seja empresa. |
POSIdentifier | S | O | 1..15 | Identificador do ponto de captura. |
POSType | S | O | 1..50 | Descrição do ponto de captura. Veja Valores de Domínio. |
POSApplication | S | O | 1..20 | Código da aplicação. OBS: Na resposta retorna a descrição. Veja Valores de Domínio. |
POSApplicationVersion | S | O | 1..20 | Descrição da versão. |
ReqNum | S | O | 1..20 | Número da Transação gerado pelo Ponto de Captura. |
ArrayOfUniqueId | S | O | 1..20 | Lista de identificadores únicos da transação no sistema Pay&Go Web. Este número é a chave primária do registro do banco de dados que deverá ser enviado na busca. |
InternalLocalReference | S | O | 1..20 | Número único da transação no sistema Pay&Go Web por afiliação. |
ArrayOfTransactionType | S | O | 1..100 | Lista de identificadores de Tipo da Transação. Veja Valores de Domínio. |
TransactionAuthorizer | S | O | 1..50 | Sistema Autorizador Veja Valores de Domínio. |
TransactionProductName | S | O | 1..50 | Nome do Produto |
ArrayOfTransactionStatus | S | O | 1..10 | Lista de identificadores da Situação da Transação no Pay&Go Web. Veja Valores de Domínio |
TransactionStartDate | S | O | 1..14 | Data e Hora inicial para filtro das transações. |
TransactionEndDate | S | O | 1..14 | Data e Hora inicial para filtro das transações. |
AuthorizerStatus | S | O | 1..50 | Situação da transação com o Autorizador. Veja Valores de Domínio |
LastUniqueIdSearched | S | O | 1..20 | Para busca parciais informar qual o último DatabaseId retornado na última consulta. |
Transaction Node
Campo | tIPO | GET | Tam. | Descrição |
---|---|---|---|---|
UniqueId | S | M | 1..20 | Número único da transação no sistema Pay&Go Web. Este número é a chave primária do registro do banco de dados |
ReqNum | S | M | 1..20 | Número da Transação gerado pelo Ponto de Captura. |
InternalLocalReference | M | 1..20 | Número único da transação no sistema Pay&Go Web por afiliação. | |
OriginalTransactionReqNum | S | O | 1..20 | No caso da transação se tratar de uma confirmação, este campo trará o número da transação original que foi confirmada ou cancelada. |
AuthorizerExternalReference | S | M | 1..20 | Número da transação para rede autorizadora. |
Status | S | M | 1..20 | Situação da Transação no Pay&Go Web. Veja Valores de Domínio. |
POSTimestamp | S | M | 14 | Data e Hora da Transação. (Formato) |
Type | S | M | 1..50 | Tipo da Transação Veja Valores de Domínio. |
Amount | S | M | 1..50 | Valor da Transação. |
Discount | S | O | 1..50 | Valor do Desconto. |
Cashback | S | O | 1..50 | Valor do Saque. |
AuthorizerName | S | M | 1..50 | Nome Autorizador. |
AuthorizerCode | S | M | 1..10 | Código do Autorizador. |
AuthorizerStatus | S | M | 1..20 | Situação da Transação perante ao Autorizador. |
AuthorizationCode | S | O | 1..6 | Código de Autorização. |
AuthorizationType | S | O | 1..20 | Modalidade de Autorização Veja Valores de Domínio |
ProductCode | S | O | 1..20 | Código do Produto. |
ProductName | S | O | 1..50 | Nome do Produto. |
ResultCode | S | M | 1..4 | Resultado da Transação |
ResultMessage | S | M | 1..80 | Mensagem informativa do resultado da Transação. |
ServerTimestamp | S | M | 1..14 | Horário do Servidor da Transação. |
AffiliationNumber | S | M | 1..50 | Código de Afiliação que foi usado na transação |
ProcessingCode | S | M | 1..10 | Código de Processamento. |
ResponseCode | S | M | 1..10 | Código de Resposta do Autorizador |
ResponseMessage | S | M | 1..300 | Mensagem de Resposta do Autorizador |
FullReceiptCopy | S | O | 1.10000 | Comprovante. Via completa. |
AuthorizationTimestamp | S | O | 1..14 | Data e Hora da autorização da transação. |
CurrencyExponent | S | M | 1..20 | Expoente da Moeda. Segundo Norma ISO4217. |
CurrencyCode | S | O | 1..3 | Código da Moeda. Segundo Norma ISO4217. |
CurrencySymbol | S | O | 1..3 | Símbolo da Moeda. Segundo Norma ISO4217. |
TaxIdentifier | S | O | 1..12 | Identificador do documento fiscal |
CardHolderVerificationFlags | S | M | 1..2 | Método de Verificação do Portador do Cartão. Veja Valores de Domínio |
CardSecCodeEntryMode | S | O | 1..2 | Modo Entrada do Código de Segurança do Cartão. Veja Valores de Domínio |
AdditionalDataArray | S | O | 1..n | Dados Adicionais enviados pelo ponto de captura. Cada dado adicional tem um limite de 100 caracteres. |
TransactionDetailsNode
Campo | Tipo | GET | Tam | Descrição |
---|---|---|---|---|
SpecificationVersion | S | M | 1..20 | Versão da especificação do módulo do sistema de autorização. |
RequestMode | S | M | 1..20 | Indica o modo da solicitação Veja Valores de Domínio. |
RequestPurpose | S | M | 1..30 | Indica o motivo do modo da solicitação |
OperatingSystem | S | O | 1..128 | Versão do sistema operacional do ponto de captura |
ComputerName | S | O | 1..128 | Nome do computador do ponto de captura. |
ComputerUserName | S | O | 1..128 | Nome do usuário do computador do ponto de captura. |
Login | S | M | 1..80 | Indica o usuário que interagiu na transação, se for o caso. |
POSData Node
Mesma estrutura que consta do cadastro de Ponto de Captura.
Campo | Tipo | GET | Tam. | Descrição |
---|---|---|---|---|
PinPadData Node | ||||
SerialNumber | S | O | 1..20 | Número de Série do PinPad do Ponto de Captura. |
ModelVersion | S | O | 1..19 | Versão do Modelo do PinPad |
Model | S | 1..19 | Modelo do PinPad | |
FirmwareVersion | S | O | 1..20 | Versão do Firmware do PinPad. |
*SpecificationVersion | S | O | 1..4 | Versão da Especificação do PinPad. |
CardData Node | ||||
CardBrand | S | O | 1..1 | Bandeira do Cartão. |
CardBIN | S | O | 1..6 | BIN do Cartão. |
EntryMode | S | O | 1..20 | Modo de entrada do cartão permitido no PtoCapturaFisico. Valores Domínio Veja Valores de Domínio |
Type | O | 1..20 | Tipo do cartão permitido no PtoCapturaFisico. Veja Valores de Domínio. | |
MaskedCardNumber | S | O | 1..20 | Número do Cartão Mascarado. |
CardName | S | O | 1..99 | Nome do Cartão |
CardHolderName | S | O | 1..99 | Nome do portador do Cartão. |
ExpirationDate | S | O | 1..4 | Data Vencimento do Cartão. Formato YYMM. |
POSCompanyData (M)
Mesma estrutura que consta do cadastro de Agrupamentos e Opções
AffiliationCompanyData (O)
Mesma estrutura que consta do cadastro de Entidade. Esta entidade é atrelada a afiliação que foi efetuado o pagamento, neste caso, utilizando multiestabelecimento.
Campo | Tipo | GET | Tam. | Descrição |
---|---|---|---|---|
FinancingData Node | ||||
Type | S | O | 1..25 | Tipo do financiamento. Veja valores de domínio. |
DueDate | S | O | 1..14 | Data do pré-datado. |
InstallmentsNumber | S | O | 1..2 | Número de Parcelas. |
RetailAutomationDetails Node | ||||
Capabilities | S | O | 1..4 | Capacidades da automação comercial. |
Company | S | O | 1..50 | Empresa desenvolvedora do aplicativo de automação comercial. |
Name | S | O | 1..128 | Nome do aplicativo de automação comercial. |
Version | S | O | 1..128 | Versão do aplicativo de automação comercial. |
Transaction Specifics Details Nodes
TopUpData Node
Campo | Tipo | GET | Tam. | Descrição |
---|---|---|---|---|
AreaCode | S | O | 1...3 | DDD do Telefone em que foi efetuada a recarga. |
MaskedPhoneNumber | S | O | 1...9 | Número do telefone, sem o DDD (8 ou 9 dígitos). |
BankingAgentData Node | ||||
BarCode | S | O | Código de Barras do Pagamento de Contas. | |
DueDate | S | O | 1..14 | Data de vencimento da conta. |
EntryMode | S | O | 1..2 | Modo de Entrada do Código de Barras. Veja Valores de Domínio. |
Discount | S | O | 1..15 | Desconto efetuado para o pagamento. |
Reduction | S | O | 1..15 | Abatimento do valor para o pagamento |
Amount | S | O | 1..15 | Valor para o pagamento. |
Fee | S | O | 1..15 | Multa aplicada ao pagamento. |
TotalAmount | S | O | 1..15 | Valor Total do pagamento somado de multa, juros e subtraído do abatimento e desconto. |
5.4.3.Serviços de Pesquisa
Serviço | API | Envio | Retorno |
---|---|---|---|
Transaction Date Range | GetTransactions | Ver tabela de dados para envio | Dados completos do filtro realizado. |
Transaction Date Range (Summary) | GetTransactionsSummary | Ver tabela de dados para envio | Dados resumidos do filtro realizado. |
Transaction Status | GetTransactionsStatus | Array of UniqueId | Status de cada UniqueId enviado. |
Transaction Array of Ids (Summary) | GetTransactionsSummary | Array of UniqueId | Dados resumidos de cada UniqueId enviado. |
5.4.4. Tabela de Valores de Códigos e Descrições para Domínio
5.4.4.1.Ponto de Captura
Nome do Campo | Código | Descrição |
---|---|---|
Status | 01 | Não Liberado para Instalação “SetupNotAllowed” |
02 | Liberado para Instalação “ReadyForSetup” | |
03 | Instalado (valor informativo) “SetupOk” | |
04 | Inativo “Disabled” | |
05 | Transacionando (valor informativo) “Transacting” | |
CardEntryMode | 01 | Digitado - “Manual” |
02 | Tarja Magnética - “Magstripe” | |
03 | Chip Com Contato - “ContactChip” | |
04 | Chip Sem Contato - “ContactlessChip” | |
05 | Fallback - “MagStripeFallback” | |
06 | FallBack Digitado - “ManualFallback” | |
*CardType | 01 | Crédito – “Credit” |
02 | Débito – “Debit” | |
04 | Voucher – “Voucher” | |
08 | Outros – “Other” | |
*FinancingType | 01 | À Vista - “1Installment” |
02 | Parcelado Emissor - “IssuerPlan” | |
03 | Parcelado Estabelecimento - “MerchantPlan” | |
04 | Pré Datado - “Postponed” |
5.4.4.2.Dados Comuns
Nome do Campo | Código | Descrição |
---|---|---|
*Status | 01 | Habilitado ou Ativo – “Enabled” |
02 | Desabilitado ou Inativo – “Disabled” | |
*AuthorizerStatus | 01 | Pendente de Confirmação |
02 | Confirmação em Curso | |
03 | Confirmação OK | |
04 | Pendente de Desfazimento | |
05 | Desfazimento em Curso | |
06 | Desfazimento OK | |
07 | Transação em Curso | |
08 | Transação OK | |
09 | Advice Pendente | |
10 | Advice em Curso | |
11 | Advice OK | |
12 | Não Enviar Advice | |
POSType | 1 | Pay&Go |
2 | LibC | |
3 | POS Muxx | |
*POSApplication | 1 | Pay&Go |
2 | Site | |
3 | Agendador | |
4 | WinDLL32 | |
5 | iWL25x | |
TT22 | iCT22x | |
TT9E | EFT930 S-GME | |
TT32 | Windows 32bits | |
6 | LibVerti | |
7 | POS Windows | |
8 | Android | |
Authorizer | 01 | ELAVON |
02 | CONDUCTOR | |
03 | BIN | |
04 | RV | |
05 | FIRSTDATA CORBAN | |
06 | FILLIP | |
07 | LIBERCARD | |
08 | CIELO | |
09 | REDE | |
10 | CREDSYSTEM | |
11 | INFOCARDS | |
12 | NDDCARGO | |
13 | GLOBAL | |
14 | VERO | |
*AuthorizationType | 01 | Online |
02 | Offline | |
CardHolderVerificationFlags | 01 | Assinatura do portador requerida. |
02 | Senha do portador verificada off-line. | |
04 | Senha offline do portador foi bloqueada na última apresentação inválida. | |
08 | Senha do portador capturada para verificação online. | |
CardSecCodeEntryMode | 00 | Não Solicitado |
01 | Capturado | |
02 | Ilegível | |
03 | Não Possui | |
*RequestMode | 01 | Solicitação Automática |
02 | Solicitação Manual | |
*CardEntryMode | 01 | Digitado |
02 | Tarja magnética | |
04 | Chip com contato | |
08 | Chip sem contato | |
16 | Fallback de chip para tarja | |
32 | Chip sem contato simulando tarja | |
64 | Chip sem contato EMV | |
128 | Transação necessita de fallback | |
256 | Fallback de tarja para digitado | |
CardType | 01 | Crédito |
02 | Débito | |
04 | Voucher | |
08 | Outros | |
FinancingType | 01 | À Vista |
02 | Parcelado pelo Emissor | |
04 | Parcelado pelo Estabelecimento | |
08 | Pré-Datado | |
BarCodeEntryMode | 01 | Lido |
02 | Digitado |
Transaction Status
TransactionType
5.5. Agrupamentos e Opções
<?xml version="1.0" encoding="ISO-8859-1"?>
<RequestTransactionMerchantGroupRegistration version="">
<authentication>
<login></login>
<password></password>
<externalLoginName></externalLoginName>
</authentication>
<MerchantGroups>
<MerchantGroup>
<Identifier xmlns="http://tempuri.org/"></Identifier>
<Name xmlns="http://tempuri.org/"></Name>
<Options xmlns="http://tempuri.org/">
<Option>
<Identifier></Identifier>
<Name></Name>
<Restrictive>true</Restrictive>
</Option>
<Option>
<Identifier></Identifier>
<Name></Name>
<Restrictive>true</Restrictive>
</Option>
</Options>
</MerchantGroup>
</MerchantGroups>
<Error>
<Number></Number>
<Description></Description>
</Error>
</RequestTransactionMerchantGroupRegistration>
5.5.1. Tipos de Dados
Campo | Tipo | PUT | POST | GET | DELETE | Tam. | Descrição |
---|---|---|---|---|---|---|---|
MerchantGroup/Name | S | M | M | X | X | 1..50 | Nome do Agrupamento |
Name Identifier | N | M | R | M | M | 1..4 | Identificador Agrupamento. Será devolvido na resposta da inclusão do registro. |
Option/Name | S | M/C | M/C | X | X | 1..50 | Nome da Opção |
Option/Restrictive | B | M/C | M/C | X | X | Caso a opção do agrupamento seja restritiva, ou seja, restrinja a visualização dos dados por outros grupos, enviar [TRUE] | |
Option Identifier | N | M/C | R/C | X | M/C | 1..4 | Identificador Opção. Será devolvido na resposta da inclusão do registro. |
5.6. Entidade
<?xml version="1.0" encoding="ISO-8859-1"?>
<RequestTransactionCompanyRegistration version="1.0.0.0" id="">
<authentication>
<login></login>
<password></password>
<externalLoginName></externalLoginName>
</authentication>
<Company>
<LegalName></LegalName>
<TradeName></TradeName>
<Notes></Notes>
<Individual></Individual>
<PerformsTransactions></PerformsTransactions>
<DisplayName></DisplayName>
<TaxId></TaxId>
<City></City>
<State></State>
<Country></Country>
<PostalCode></PostalCode>
<MerchantGroup>
<Name></Name>
<Option>
<Option>
<Name></Name>
</Option>
<Option>
<Name></Name>
</Option>
</Option>
</MerchantGroup>
</Company>
<Error>
<Number></Number>
<Description></Description>
</Error>
</request>
5.6.1.Tipos de Dados
Updated over 3 years ago