Manual de Integração Retorno dos dados do cliente

Transcrição

1 Manual de Integração Retorno dos dados do cliente Integração EvoluCard Versão 1.3 Janeiro de 2012

2 Histórico de versões Data Versão Responsável 28/10/ Criação do documento. Erivelton Oliveira 19/12/ Correção de parâmetros do método getcards. Erivelton Oliveira 26/01/ Adicionado parâmetro consumerfare no Erivelton Oliveira método getcards. Adicionado seção Considerações no método updatetransacion. 15/02/ Adição de erro EV032 na seção Codificação de Erros. Erivelton Oliveira EvoluCard Manual de Integração Versão 1.1 Dezembro

3 Índice 1. Introdução O que é a EvoluCard? Informações importantes Fases e fluxo de dados Detalhamento das etapas Obtenção dos cartões disponíveis do cliente (Etapa 1) Retorno da EvoluCard à solicitação na Etapa 1 (Etapa 2) Envio das condições da transação à EvoluCard (Etapa 3) Retorno da EvoluCard à solicitação na Etapa 3 (Etapa 4) Reenvio do TOKEN para o cliente (Etapa EXTRA) Envio do TOKEN de duas variáveis, informado pelo cliente (Etapa 5) Retorno da EvoluCard à solicitação na Etapa 5 (Etapa 6) Reenvio do token fornecido pelo cliente (Etapa EXTRA 2) Atualização do status da transação (Etapa 7) Retorno da EvoluCard à solicitação na Etapa 7 (Etapa 8) Codificação de Erros Erros gerados no método getcards Erros gerados no método newtransaction Erros gerados no método resendtoken Erros gerados no método confirmtokentransaction Erros gerados no método updatetransaction Operações de Teste Envio do TOKEN Campo resend Informações dos cartões de crédito Processo de Homologação Suporte Técnico ANEXO I Diagrama da integração EvoluCard Manual de Integração Versão 1.1 Dezembro

4 1. Introdução Para realizar a transmissão dos dados das transações, a EvoluCard utiliza o modelo de integração web service e HTTPS/POST que segue o fluxo de dados especificado no Anexo I Diagrama da integração. Através da integração web service e HTTPS/POST, as principais vantagens obtidas são: facilidade na integração, independência de plataforma, redução de custos para transporte de dados e adoção ao formato universal. O objetivo desse documento é orientar os estabelecimentos quanto aos módulos necessários e disponíveis para a transmissão de uma transação, através das soluções de integração EvoluCard. Para iniciar o processo de integração, o desenvolvedor do estabelecimento deverá informar à EvoluCard o(s) endereço(s) de IP da aplicação que se comunicará com o servidor da EvoluCard. Além disso, o estabelecimento deve preencher o Formulário de Adesão a EvoluCard que estará junto deste manual e enviá-lo para suporteweb@evolucard.com.br. 2. O que é a EvoluCard? A EvoluCard viabiliza ao estabelecimento e ao cliente meios de pagamentos mais seguros através dos cartões de crédito, voltados principalmente para a realização de compras pela internet ou por telefone, utilizando o celular do cliente e o TOKEN com duas variáveis para validar a compra. 3. Informações importantes Para integração, em linhas gerais, exige-se que o servidor utilizado pelo estabelecimento seja capaz de interpretar os dados em formato JSON, padrão este enviado pelo servidor da EvoluCard. Além disso, deve ser capaz de realizar uma chamada para o web service da EvoluCard, ou então, enviar uma requisição HTTPS/POST, dependendo do padrão escolhido para realizar a integração. Toda a comunicação realizada pela integração poderá utilizar o protocolo HTTPS/POST ou web service para comunicação com a EvoluCard, sendo a resposta da EvoluCard sempre no padrão JSON. Como nesse modelo de integração o estabelecimento fica responsável por enviar a transação para o adquirente/gateway de pagamentos, é necessário enviar para EvoluCard o resultado dessa transação, para atualização do nosso sistema. Isso será explicado mais a frente nesse manual. Para utilizar essa forma de integração é necessário que o(s) IP(s) de onde as transações partirão seja(m) fixo(s). Os parâmetros de cada etapa da integração encontram-se detalhados no item 6 deste manual. EvoluCard Manual de Integração Versão 1.1 Dezembro

5 4. Fases e fluxo de dados O processo de uma transação é composto por quatro fases, que compreende duas etapas, cada uma delas. Sendo uma o envio de dados pelo estabelecimento e a outra o retorno da EvoluCard. Em todas as etapas que a EvoluCard responder ao estabelecimento, essa resposta virá no formato JSON, serializado a partir da mesma classe. Assim, sempre serão enviados os mesmos parâmetros em todas as etapas. A diferença estará no conjunto de parâmetros que poderão ser não-nulos em cada método. Esses parâmetros possivelmente não-nulos serão os descritos em cada especificação. I) Obtenção dos cartões disponíveis do cliente Método getcards Nessa fase inicial, o estabelecimento solicita à EvoluCard os cartões cadastrados para o celular informado (Etapas 1 e 2). A resposta traz a lista dos possíveis cartões do cliente para realizar a transação. II) Envio das condições da transação à EvoluCard Método newtransaction O cartão do cliente e a condição de pagamento selecionada para transação são direcionadas à EvoluCard (Etapas 3 e 4). A EvoluCard cria a transação, envia o TOKEN ao cliente e responde ao estabelecimento o número de transação EvoluCard que identificará a transação dentre outros dados. III) IV) Envio do TOKEN de duas variáveis Método confirmtokentransaction O estabelecimento envia à EvoluCard o TOKEN fornecido pelo cliente, que será validado pela EvoluCard (Etapas 5 e 6). A EvoluCard responderá os dados do cliente para o estabelecimento enviar a transação para o adquirente/gateway de pagamentos. Atualização do status da transação Método updatetransaction Após o estabelecimento enviar a transação para o adquirente/gateway de pagamentos, o estabelecimento informa a EvoluCard se a transação foi ou não aprovada. 5. Detalhamento das etapas Os campos para qualquer etapa são enviados sempre como String, e a listagem de todos os códigos de erro encontra-se na seção 6 deste manual. Independente da forma de integração escolhida (web service ou HTTPS/POST), os parâmetros enviados devem ser os mesmos, diferindo apenas na forma de envio. Além disso, em cada método estará especificado a url de cada forma de integração. Os estabelecimentos que forem utilizar a integração por web service podem encontrar a WSDL no seguinte endereço: EvoluCard Manual de Integração Versão 1.1 Dezembro

6 Abaixo, segue a legenda para as tabelas de parâmetros utilizadas nos métodos: J JSON Parâmetro está no formato JSON N Numérico Apenas números AN Alfanumérico Números e caracteres M Monetário Padrão para valores, segue o padrão americano. Ex: T Texto Campo livre O Obrigatório Campo deve ser enviado obrigatoriamente OP Opcional Campo é opcional C Condicional Campo é obrigatório dependendo de uma condição 5.1. Obtenção dos cartões disponíveis do cliente (Etapa 1) A Etapa 1 corresponde à requisição para obter os cartões cadastrados do cliente com a EvoluCard, que podem ser utilizados no estabelecimento. Escopo Protocolo/Método Endereço Formato da resposta HTTPS/POST JSON Protocolo/Método Endereço Formato da resposta Webservice/SOAP JSON Parâmetros Na tabela a seguir estão os parâmetros que o estabelecimento deverá enviar à EvoluCard na etapa 1. Parâmetro Formato Obrigatoriedade Tamanho Exemplo merchantcode Código do estabelecimento com a EvoluCard AN O est mobilecc DDI do celular do cliente N O 2 55 mobileac DDD do celular do cliente N O 2 11 mobilenb Número do celular do cliente N O EvoluCard Manual de Integração Versão 1.1 Dezembro

7 Considerações O número do celular do cliente não deve ser armazenado pelo estabelecimento, deve este apenas trafegar no momento da transação, e após finalizada a transação, os dados devem ser descartados Retorno da EvoluCard à solicitação na Etapa 1 (Etapa 2) Nessa etapa, a EvoluCard responde a solicitação do estabelecimento, disponibilizando a lista de cartões cadastrados do cliente mencionado, para posterior seleção de um deles. Parâmetros O modelo do JSON, em caso de sucesso e de erro, está descrito abaixo e a descrição de cada parâmetro na tabela em seguida. Lembramos que estão descritos apenas os valores não-nulos em cada caso. JSON em caso de sucesso: { "code": EV000, "consumername":"josé da Silva", "consumermobileoperator":"vivo", "cardlist":[ { "binnumber":"333333", "description":"cartão Exemplo 1", "id":"nti3mq*3", paymentbrand : VISA, consumerfare : 0.00 }, { "binnumber":"111222", "description":"cartão Exemplo 2", "id":"nti3na*3", paymentbrand : MASTERCARD, consumerfare : 0.00 } ] } JSON em caso de erro: { code : EV004" } EvoluCard Manual de Integração Versão 1.1 Dezembro

8 Parâmetro Formato Tamanho Exemplo code Código de sucesso ou erro. EV000 em caso de sucesso. Para os demais erros, ver seção 6 AN 1..5 EV004 consumername Nome do cliente T n/a José da Silva consumermobile Operator Operadora de celular do cliente T n/a VIVO cardlist Lista dos cartões válidos do cliente. Possui 5 campos: id, description, binnumber, paymentbrand e consumerfare descritos a seguir J n/a Ver o exemplo acima. binnumber Campo de cardlist. Bin number do cartão do cliente, ou seja, os 6 primeiros dígitos do cartão N description id paymentbrand consumerfare Campo de cardlist. do cartão do cliente Campo de cardlist. Id do cartão do cliente Campo de cardlist. Bandeira do cartão do cliente Este campo deve ser ignorado pelo estabelecimento. T n/a Cartão Principal T n/a NTI3MQ*3 AN n/a VISA M n/a 0.00 Considerações Os cartões disponíveis na cardlist não são editáveis, apenas passíveis de seleção pelo estabelecimento. A EvoluCard retorna atualmente as seguintes bandeiras como parâmetro: VISA, MASTERCARD, ELO, AMERICAN EXPRESS, DINERS E HIPERCARD. EvoluCard Manual de Integração Versão 1.1 Dezembro

9 5.3. Envio das condições da transação à EvoluCard (Etapa 3) O estabelecimento enviará o cartão a ser utilizado pelo cliente, e os dados da transação, incluindo a condição de pagamento. Escopo Protocolo/Método Endereço Formato da resposta HTTPS/POST JSON Protocolo/Método Endereço Formato da resposta Webservice/SOAP JSON Parâmetros Na tabela a seguir estão os parâmetros que o estabelecimento enviará à EvoluCard informando os dados da transação. Parâmetro Formato Obrigatoriedade Tamanho Exemplo merchantcode Código do estabelecimento com a EvoluCard AN O est docnumber Número do documento que o estabelecimento utiliza para N O identificar a transação cardid Id do cartão do cliente escolhido para a transação T O n/a NTI3MQ*3 value Valor da transação M O n/a numberpayment Número de parcelas da transação N O Retorno da EvoluCard à solicitação na Etapa 3 (Etapa 4) O retorno da EvoluCard descreve nessa etapa, se o envio TOKEN foi por SMS ou Ligação. Se enviado por SMS, possibilitará ao estabelecimento mais uma única solicitação do reenvio do SMS e uma por ligação. Se por ligação, não haverá mais reenvio. EvoluCard Manual de Integração Versão 1.1 Dezembro

10 Parâmetros A seguir temos os JSON de retorno em caso de sucesso e de erro. Na sequência temos a tabela com a explicação dos parâmetros. JSON em caso de sucesso: { "code": EV000, "docnumber":"4300", "transactionnumberevc":" ", "additionalinfo":"0", "resend":"1" } JSON em caso de erro: { code : EV004" } Parâmetro Formato Tamanho Exemplo code Código de sucesso ou erro. EV000 em caso de sucesso. Para AN 1..5 EV004 os demais erros, ver seção 6 docnumber Número do documento que o estabelecimento utiliza para identificar a transação N transactionnumberevc additionalinfo Número de Transação EvoluCard. Esse será o número usado pelo estabelecimento para identificar a transação deste passo em diante Campo que indica o que deve ser devolvido no campo birthinfo na próxima etapa (confirmtokentransaction). 0 Vazio, 1 Dia do aniversário, 2 Mês do aniversário, 3 - Ano do aniversário do cliente N N 1 2 resend Indica o número de reenvios ainda permitidos, com valor máximo de 2. resend = 0 : nenhum reenvio é permitido. resend = 1 : É permitido um reenvio que será feito por ligação. resend = 2 : São permitidos 2 reenvios, o 1º por SMS e o 2º por ligação N 1 2 EvoluCard Manual de Integração Versão 1.1 Dezembro

11 Considerações Enviado o TOKEN pela primeira vez, o estabelecimento possui o tempo de 15 minutos para informar a resposta à EvoluCard. Caso o cliente não responda o TOKEN dentro 30 segundos, o estabelecimento deve fornecer ao cliente, desde que seja possível ( resend maior que zero) uma opção para solicitar o reenvio do TOKEN, seja por SMS ou ligação. O processo de solicitação do reenvio do TOKEN está descrito na próxima etapa. Deve ser respeitado, entretanto, um intervalo de tempo mínimo de 30 segundos entre dois envios consecutivos. O campo additionalinfo segue a seguinte lógica: se o cliente teve as duas últimas compras reprovadas por erro de TOKEN (EV019 ou EV029), não necessariamente no mesmo estabelecimento, então será necessário enviar uma informação adicional na próxima transação do cliente (com additionalinfo tendo valor 1, 2 ou 3 para indicar dia, mês ou ano do aniversário, respectivamente). O envio do TOKEN é feito de forma alternativa no ambiente de teste, para mais informações veja a seção 6.2. O campo resend possui um comportamento fixo no caso do ambiente de teste, para mais informações veja a seção Reenvio do TOKEN para o cliente (Etapa EXTRA) Corresponde a solicitação do reenvio do TOKEN ao cliente, efetuada pelo estabelecimento. Escopo Protocolo/Método Endereço Formato da resposta HTTPS/POST JSON Protocolo/Método Endereço Formato da resposta Webservice/SOAP JSON Parâmetros Na tabela a seguir estão os parâmetros que o Estabelecimento enviará a EvoluCard para o reenvio do TOKEN. EvoluCard Manual de Integração Versão 1.1 Dezembro

12 Parâmetro Formato Obrigatoriedade Tamanho Exemplo transactionnumberevc Número de Transação EvoluCard. É o número recebido na resposta do newtransaction (Etapa 4) N O Resposta da EvoluCard A EvoluCard retorna uma JSON a requisição de envio de TOKEN como mostrado abaixo. Em seguida a tabela com a explicação dos campos. JSON em caso de sucesso: { "code": EV000, "resend":"1" } JSON em caso de erro: { code : EV004" } Parâmetro Formato Tamanho Exemplo code Código de sucesso ou erro. EV000 em caso de sucesso. Para os demais erros, ver seção 6 AN 1..5 EV004 resend Indica o número de reenvios ainda permitidos, com valor máximo de 2 N 1 2 EvoluCard Manual de Integração Versão 1.1 Dezembro

13 Considerações Vale ressaltar que essa etapa estará disponível no máximo duas vezes, como definido no campo resend do método newtransaction (e posteriormente pelo resend retornado pelo método resendtoken). Desta forma, se o campo resend for 0 (zero), nenhum reenvio é permitido. Se for 1, é permitido um reenvio que será feito por ligação. Se for 2, são permitidos dois reenvios, o primeiro por SMS e o segundo por ligação. Deve ser respeitado, entretanto, um intervalo de tempo de 30 segundos entre dois envios consecutivos, independentemente do primeiro ser envio ou reenvio. Além disso, o reenvio de TOKEN só pode ser solicitado até 5 minutos após o início da transação. O envio do TOKEN é feito de forma alternativa no ambiente de teste, para mais informações veja a seção 9.2. O campo resend possui um comportamento fixo no caso do ambiente de teste, para mais informações ver seção Envio do TOKEN de duas variáveis, informado pelo cliente (Etapa 5) Para autenticar a transação, o estabelecimento envia à EvoluCard o TOKEN recebido pelo cliente, e quando solicitado os dados pessoais adicionais para confirmação do cliente. Escopo Protocolo/Método Endereço Formato da resposta HTTPS/POST JSON Protocolo/Método Endereço Formato da resposta Webservice/SOAP JSON Parâmetros Na tabela a seguir, estão os parâmetros que o estabelecimento enviará o TOKEN e as informações adicionais quando solicitadas. Parâmetro Formato Obrigatoriedade Tamanho Exemplo transactionnumberevc Número de Transação EvoluCard. É o número recebido na resposta do newtransaction (Etapa 4) N O token TOKEN digitado pelo cliente. N O EvoluCard Manual de Integração Versão 1.1 Dezembro

14 birthinfo Informação adicional do cliente. Pode ser vazio, dia, mês ou ano de nascimento dependendo do campo additionalinfo N C 2 06 Considerações O campo birthinfo pode estar em branco, se o campo additionalinfo (informado na etapa anterior) for 0 (zero). Senão, deve seguir o requisitado pelo campo additionalinfo como resposta do método newtransaction anteriormente detalhado Retorno da EvoluCard à solicitação na Etapa 5 (Etapa 6) Retorno a solicitação da Etapa 5, contendo os dados do cliente para que o estabelecimento possa enviar a transação para o adquirente/gateway de pagamentos. Parâmetros Abaixo temos o exemplo JSON em caso de sucesso e de erro. Em seguida, na tabela, temos a especificação dos parâmetros. JSON em caso de sucesso: { "code": "EV000", "transactionnumberevc": " ", "cardinfodto": { "consumer": "José da Silva", "mobile": "+55 (19) ", "cardname": "Cartão Principal", "holder": "José da Silva", paymentbrand : VISA "cardnumber": " ", "cardyear": "2025", "cardmonth": "12", "cardcode": "123" } } { } JSON em caso de erro: code : EV019", "transactionnumberevc":" ", EvoluCard Manual de Integração Versão 1.1 Dezembro

15 Parâmetro Formato Tamanho Exemplo code transactionnumberevc Código de sucesso ou erro. EV000 em caso de sucesso. Para os demais erros, ver seção 6 Número de Transação EvoluCard. É o número recebido na resposta do newtransaction (Etapa 4) AN 1..5 EV019 N cardinfodto Campo no JSON de resposta que contém as informações do cliente e/ou da compra. Seus campos estão descritos abaixo. JSON n/a Ver o exemplo acima consumer Informa a nome do cliente T n/a José da Silva mobile Informa o celular do cliente T n/a +55 (19) cardname holder paymentbrand Informa a descrição do cartão do cliente Informa o nome do portador do cartão (pode ser diferente do nome do cliente do campo consumer ) Informa a bandeira do cartão do cliente T n/a Cartão Principal T n/a José da Silva T n/a VISA cardnumber Informa o número do cartão do cliente N n/a cardcode Informa o código de segurança do cartão do cliente N n/a 123 cardyear Informa o ano da data de validade do cartão do cliente N cardmonth Informa o mês da data de validade do cartão do cliente N 2 06 Considerações A EvoluCard retorna atualmente as seguintes bandeiras como parâmetro: VISA, MASTERCARD, ELO, AMERICAN EXPRESS, DINERS E HIPERCARD. 5.8 Reenvio do token fornecido pelo cliente (Etapa EXTRA 2) Essa etapa é opcional e idêntica à etapa 5. Consiste, basicamente, em fornecer ao cliente uma segunda tentativa de finalizar a transação, caso a 1 a tentativa tenha EvoluCard Manual de Integração Versão 1.1 Dezembro

16 dado errada, devido à digitação incorreta do TOKEN ou da informação adicional (birthinfo). Esses casos se dão quando o código de retorno da EvoluCard na Etapa 6 (resposta da etapa 5) é EV019 (Token incorreto na primeira tentativa) ou EV021 (Informação adicional de nascimento incorreta na primeira tentativa). Considerações O escopo e os parâmetros dessa etapa são idênticos aos da Etapa 5. Entretanto, não é possível efetuar essa etapa extra sem que os erros na etapa 6 (resposta da etapa 5) tenham sido EV019 ou EV021. Os erros que poderão ocorrer nessa etapa estão descritos na seção 6.4, dado que essa etapa utiliza o mesmo método (confirmtokentransaction) da etapa Atualização do status da transação (Etapa 7) O estabelecimento enviará a EvoluCard o status final da transação independentemente de ter sido aprovada ou não. Escopo Protocolo/Método Endereço Formato da resposta HTTPS/POST JSON Protocolo/Método Endereço Formato da resposta Webservice/SOAP JSON Parâmetros Na tabela a seguir, estão os parâmetros que o estabelecimento enviará o TOKEN e as informações adicionais quando solicitadas. Parâmetro Formato Obrigatoriedade Tamanho Exemplo transactionnumberevc Número de Transação EvoluCard. N O 19 status Status da Transação: 1 para aprovada, 0 caso contrário. N O acquirernumber Número de transação do adquirente. AN O n/a n/a EvoluCard Manual de Integração Versão 1.1 Dezembro

17 authorization Número de autorização da transação. (Deve ser enviado se a transação tiver sido aprovada) AN C n/a n/a Considerações Caso o estabelecimento informe a EvoluCard que a transação não foi aprovada (status=0), esta ficará com com o status Reprovada pelo Estabelecimento Retorno da EvoluCard à solicitação na Etapa 7 (Etapa 8) Retorno a solicitação da Etapa 7, finalizando o processo. Parâmetros Abaixo temos o exemplo JSON em caso de sucesso e de erro. Em seguida, na tabela, temos a especificação dos parâmetros. JSON em caso de sucesso: { "code": EV000, "transactionnumberevc":" , } JSON em caso de erro: { code : EV114", } Parâmetro Formato Tamanho Exemplo code transactionnumberevc Código de sucesso ou erro. EV000 em caso de sucesso. Para os demais erros, ver seção 6 Número de Transação EvoluCard. É o número recebido na resposta do newtransaction (Etapa 4) AN 1..5 EV114 N EvoluCard Manual de Integração Versão 1.1 Dezembro

18 6. Codificação de Erros A EvoluCard utiliza como padrão, para todos os códigos de erro gerados pela EvoluCard o formato EVnnn. Assim, se a EvoluCard tem um erro de código 3, o campo code do JSON de resposta será code : EV003. Lembramos que code : EV000 significa que nenhum erro ocorreu, caso de sucesso Erros gerados no método getcards Na tabela abaixo encontram-se os códigos de erro e descrições do erros no método getcards da integração EvoluCard. Código EV000 EV002 EV003 EV004 EV005 EV006 EV007 EV027 EV028 EV101 EV102 EV103 EV104 Nenhum erro ocorreu. Nenhum cliente válido foi encontrado com os parâmetros passados. Não existe cliente com esse número. Nenhum cliente válido foi encontrado com os parâmetros passados. O status do cliente está inválido para efetuar transações. Nenhum estabelecimento foi encontrado com os parâmetros passados. Nenhum estabelecimento válido foi encontrado com os parâmetros passados. O status do estabelecimento está inválido para efetuar transações. Um erro inesperado aconteceu em nosso servidor. Entre em contato com a EvoluCard com o código do erro. O IP utilizado para efetuar a chamada ao método é inválido. O estabelecimento não cadastrou o IP utilizado na EvoluCard. Consumidor não possui nenhum cartão aprovado. Consumidor não possui nenhum cartão aprovado com bandeira aceita pelo estabelecimento. Código do estabelecimento inválido. Verifique o formato enviado no campo "merchantcode". DDI do celular do cliente inválido. Verifique o formato enviado no campo "mobilecc". DDD do celular do cliente inválido. Verifique o formato enviado no campo "mobileac". Número do celular do cliente inválido. Verifique o formato enviado no campo "mobilenb" Erros gerados no método newtransaction Na tabela abaixo estão listados os códigos de erro e a descrição de cada erro no método newtransaction da integração EvoluCard. Código EV000 EV002 EV003 Nenhum erro ocorreu. Nenhum cliente válido foi encontrado com os parâmetros passados. Não existe cliente com esse número ou ele não possui cartões válidos para compras. Nenhum cliente válido foi encontrado com os parâmetros passados. O status do cliente está inválido para efetuar transações. EvoluCard Manual de Integração Versão 1.1 Dezembro

19 EV004 EV005 EV007 EV008 EV011 EV025 EV027 EV028 EV032 EV101 EV105 EV106 EV107 EV108 EV117 Nenhum estabelecimento foi encontrado com os parâmetros passados. Nenhum estabelecimento válido foi encontrado com os parâmetros passados. O status do estabelecimento está inválido para efetuar transações. O IP utilizado para efetuar a chamada ao método é inválido. O estabelecimento não cadastrou o IP utilizado na EvoluCard. O cartão do cliente está inválido para efetuar transações. TOKEN não enviado. Entre em contato com a EvoluCard. Erro na criação da transação. Entre em contato com a EvoluCard. Consumidor não possui nenhum cartão aprovado. Consumidor não possui nenhum cartão aprovado com bandeira aceita pelo estabelecimento. Este cartão possui uma compra não finalizada, espere 30 segundos para iniciar uma nova compra. Código do estabelecimento inválido. Verifique o formato enviado no campo "merchantcode". ID do cartão do cliente inválido. Verifique o formato enviado no campo "cardid". Valor da transação inválido. Verifique o formato enviado no campo "value". Número de parcelas da transação inválido. Verifique o formato enviado no campo "numberpayment". Número de documento do estabelecimento inválido. Verifique o formato enviado no campo "docnumber". Estabelecimento não tem permissão para utilizar essa integração. Verifique seu cadastro com a EvoluCard Erros gerados no método resendtoken Na tabela abaixo estão listados os códigos de erro e a descrição de cada erro no método resendtoken da integração EvoluCard. Código EV000 EV004 EV005 EV007 EV013 EV014 EV015 EV016 EV017 EV018 EV026 EV111 Nenhum erro ocorreu. Nenhum estabelecimento foi encontrado com os parâmetros passados. Nenhum estabelecimento válido foi encontrado com os parâmetros passados. O status do estabelecimento está inválido para efetuar transações. O IP utilizado para efetuar a chamada ao método é inválido. O estabelecimento não cadastrou o IP utilizado na EvoluCard. Um erro inesperado aconteceu em nosso servidor. Entre em contato com a EvoluCard com o código do erro. Número máximo de reenvios de TOKEN excedido. Limite de tempo para reenvio de TOKEN excedido. Transação não está com status Incompleta. Não foi possível reenviar o TOKEN. Transação não encontrada. Tempo mínimo para reenvio de TOKEN é de 30 segundos. Aguarde e tente novamente. Número de transação inválido. Verifique o formato enviado no campo "transactionnumberevc". EvoluCard Manual de Integração Versão 1.1 Dezembro

20 6.4. Erros gerados no método confirmtokentransaction Na tabela abaixo estão listados os códigos de erro e a descrição de cada erro no método confirmtokentransaction da integração EvoluCard. Código EV000 EV004 EV005 EV007 EV018 EV019 EV021 EV022 EV029 EV030 EV099 EV110 EV111 EV112 EV117 Nenhum erro ocorreu. Nenhum estabelecimento foi encontrado com os parâmetros passados. Nenhum estabelecimento válido foi encontrado com os parâmetros passados. O status do estabelecimento está inválido para efetuar transações. O IP utilizado para efetuar a chamada ao método é inválido. O estabelecimento não cadastrou o IP utilizado na EvoluCard. Transação não encontrada. TOKEN incorreto na primeira tentativa. Se desejar, tente novamente. Informação adicional de nascimento incorreta na primeira tentativa. Se desejar, tente novamente. Tempo limite para finalização da transação excedido. TOKEN incorreto na segunda tentativa. Transação reprovada. Informação adicional de nascimento incorreta na segunda tentativa. Transação reprovada. Um erro inesperado aconteceu em nosso servidor. Entre em contato com a EvoluCard com o código do erro. TOKEN inválido. Verifique o formato enviado no campo "token". Número de transação inválido. Verifique o formato enviado no campo "transactionnumberevc". Informação adicional de nascimento inválida. Verifique o formato enviado no campo "birthinfo". Estabelecimento não tem permissão para utilizar essa integração. Verifique seu cadastro com a EvoluCard Erros gerados no método updatetransaction Na tabela abaixo estão listados os códigos de erro e a descrição de cada erro no método updatetransaction da integração EvoluCard. Código EV000 EV004 EV005 EV007 EV018 EV099 EV111 Nenhum erro ocorreu. Nenhum estabelecimento foi encontrado com os parâmetros passados. Nenhum estabelecimento válido foi encontrado com os parâmetros passados. O status do estabelecimento está inválido para efetuar transações. O IP utilizado para efetuar a chamada ao método é inválido. O estabelecimento não cadastrou o IP utilizado na EvoluCard. Transação não encontrada. Um erro inesperado aconteceu em nosso servidor. Entre em contato com a EvoluCard com o código do erro. Número de transação inválido. Verifique o formato enviado no campo "transactionnumberevc". EvoluCard Manual de Integração Versão 1.1 Dezembro

21 EV113 EV114 EV115 EV117 Número de autorização inválido. Verifique o formato enviado no campo "authorization". Número de transação do adquirente inválido. Verifique o formato enviado no campo "acquirernumber". Status da transação inválido. Verifique o formato enviado no campo "status". Estabelecimento não tem permissão para utilizar essa integração. Verifique seu cadastro com a EvoluCard. 7. Operações de Teste Antes que as transações sejam encaminhadas para o ambiente de produção real, é fornecido um ambiente de teste, no qual as transações não são de fato realizadas. Esse serve, portanto, apenas para testar o sistema do estabelecimento sem submeter as transações reais. As operações para teste estão disponíveis em: para o webservice de teste. Nele, os métodos estão em Para os estabelecimentos que utilizam HTTPS/POST, os métodos de teste estão em Abaixo há uma tabela exemplificando a mudança da url de produção para testes no método getcards, tanto para webservice quanto para HTTPS/POST. Protocolo/Método Endereço de produção Endereço de teste Webservice (SOAP) Protocolo/Método Endereço de produção Endereço de teste HTTPS/POST Destacamos que os parâmetros de todas as funcionalidades são mantidos de acordo com o que foi estabelecido para a fase real. Previamente à realização dos testes, é importante que o desenvolvedor do estabelecimento contate o suporte técnico da EvoluCard, com o propósito de verificar se o cadastro do estabelecimento está correto e liberado para utilização. EvoluCard Manual de Integração Versão 1.1 Dezembro

22 Para a realização dos testes é essencial que os dados do estabelecimento sejam reais. Quanto aos demais dados da transação, inclusive os do cliente, dados fictícios serão aceitos, pois não acontecerá o envio dessas transações para o adquirente ou gateway de pagamentos Envio do TOKEN No ambiente de teste o TOKEN não é enviado por SMS/ligação, mas é retornado junto dos demais campos de resposta do newtransaction no campo tokensent. Dessa forma, o método resendtoken não tem função no ambiente de testes, mas responde parâmetros válidos Campo resend Nos métodos newtransaction e resendtoken, é retornado o campo resend que poderia ter valor 0,1,2. No ambiente de teste, entretanto, o valor será sempre fixo. O método newtransaction retornará sempre valor 2 para resend e o resendtoken sempre valor 1. Isso acontece pois no ambiente de teste o envio de TOKENs não é realizado Informações dos cartões de crédito No método confirmtokentransaction, há, no retorno, informações referentes ao cartão de crédito do cliente que está utilizando a EvoluCard. Nas operações de teste, entretanto, as informações retornadas serão sempre as mesmas para uma dada bandeira de cartão independentemente do número de celular ou quaisquer outros dados do cliente. Assim, se o cartão VISA do cliente de celular é , para o cliente com celular também será o mesmo número de cartão (assim como validade e código de segurança). Além disso, o campo holder terá sempre valor Holder Test, o campo cardmonth terá valor 12 e o campo cardyear será sempre o ano atual + 1 (se 2011 for o ano atual, então virá 2012). Abaixo a tabela de dados retornados de acordo com a bandeira do cartão: Bandeira cardnumber cardcode cardname holder cardmonth cardyear VISA VISA TEST Holder Test 12 Atual + 1 MASTERCARD MASTERCARD TEST Holder Test 12 Atual + 1 AMEX AMEX TEST Holder Test 12 Atual + 1 DINERS DINERS TEST Holder Test 12 Atual + 1 HIPERCARD HIPERCARD TEST Holder Test 12 Atual + 1 ELO ELO TEST Holder Test 12 Atual + 1 EvoluCard Manual de Integração Versão 1.1 Dezembro

23 8. Processo de Homologação Para iniciar as operações em ambiente de produção, o desenvolvedor do estabelecimento deve contatar o suporte técnico da EvoluCard e realizar essa solicitação. Uma bateria de testes será realizada antes da migração de ambientes. Após o estabelecimento ser aprovado nos testes, a EvoluCard notificará a liberação do ambiente de produção e, a partir daí, o ambiente de testes ficará indisponível automaticamente. Caso seja necessária alguma alteração no cadastro do estabelecimento, o desenvolvedor do estabelecimento deverá notificar a EvoluCard, através do suporte técnico, para que essa modificação seja realizada. 9. Suporte Técnico Em caso de dúvidas ou problemas durante o desenvolvimento do processo de integração, a EvoluCard disponibiliza o suporteweb@evolucard.com.br Para entrar em contato, tenha em mãos, o código de identificação do estabelecimento junto à EvoluCard. Os colaboradores do suporte da EvoluCard não estão autorizados a: - Receber ou fornecer dados de cadastro do cliente, ainda que seja para finalidade de testes; - Fornecer informações comerciais sobre o estabelecimento; - Realizar alterações no código fonte do estabelecimento, independentemente da linguagem de programação. EvoluCard Manual de Integração Versão 1.1 Dezembro

24 ANEXO I Diagrama da integração EvoluCard Manual de Integração Versão 1.1 Dezembro