Manual de Integração Web Service

Transcrição

1 Manual de Integração Web Service Integração EvoluCard Versão 3.4 Janeiro de 2012

2 Histórico de versões Data Versão Descrição Responsável 28/09/ Criação do documento Erivelton Oliveira 15/10/ Adição da seção 6.8 Reenvio do token fornecido pelo cliente Erivelton Oliveira 21/11/ Adição das informações do Suporte Técnico Erivelton Oliveira 05/12/ Adição de novos erros na seção Codificação de Erros Erivelton Oliveira 22/12/ Adição dos campos para integração com Erivelton gateways e adquirentes 26/01/ Adição de erro EV031 na seção Codificação de Erros. Adição do parâmetro consumerfare no método getcards. Adição de novos pârametros (consumervalue, monthlypaymentvalue, consumercardname e consumercardnumber) no retorno do método confirmtransaction. Atualização do anexo I. 15/02/ Adição de erro EV032 na seção Codificação de Erros. Oliveira Erivelton Oliveira Erivelton Oliveira EvoluCard Manual de Integração Versão 3.2 Setembro

3 Índice 1. Introdução O que é a EvoluCard? Informações importantes Comunicação EvoluCard <-> Gateway de pagamentos 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 final da EvoluCard (Etapa 6) Reenvio do token fornecido pelo cliente (ETAPA EXTRA 2) Codificação de Erros Erros gerados no método getcards Erros gerados no método preapprovetransaction Erros gerados no método resendtoken Erros gerados no método confirmtransaction Campos para integração com gateways e adquirentes Integração CIELO Integração REDECARD Operações de Teste Aprovação e reprovação Envio do TOKEN Campo resend Processo de Homologação Suporte Técnico ANEXO I Diagrama da integração ANEXO II Diagrama dos atores da integração EvoluCard Manual de Integração Versão 3.2 Setembro

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. Caso o estabelecimento não possua o formulário, requisite através do mesmo 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, uma exigência é 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. O estabelecimento que já possui uma integração com o gateway de pagamento, terá as características de seu fluxo mantido. Como mostrado no Anexo II Diagrama dos atores da integração, a EvoluCard entrará no fluxo da transação apenas intermediando a comunicação entre o estabelecimento e o adquirente/gateway de pagamentos. Essa intermediação acontecerá apenas nas transações que envolvam a EvoluCard, todas as demais transações enviadas no modelo tradicional manterão seu fluxo direto para o gateway/adquirente, sem o envolvimento da EvoluCard. Para isso, a EvoluCard irá configurar o cadastro do estabelecimento de acordo com o gateway de pagamentos utilizado pelo estabelecimento, e então utilizará o mesmo gateway para enviar as transações. Caso a integração em questão ainda não exista, será necessário um período de desenvolvimento e adaptação, por parte da EvoluCard. EvoluCard Manual de Integração Versão 3.2 Setembro

5 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. Para utilizar essa forma de integração é necessário que o endereço do IP de onde as transações partirão seja fixo. Os parâmetros de cada etapa da integração encontram-se detalhados no item 6 deste manual. 4. Comunicação EvoluCard <-> Gateway de pagamentos Como dito anteriormente, nas transações realizadas com EvoluCard atuaremos como intermediários do fluxo entre o estabelecimento e o gateway. Para que isso seja possível, a EvoluCard fará uma integração com o gateway desejado (se ainda não existir) e cadastrará em seu sistema todos os parâmetros que o gateway espera receber. Dessa forma, para que a EvoluCard possa enviar uma transação pelo estabelecimento é necessário cadastrar os parâmetros de identificação do estabelecimento no sistema. Por exemplo, cadastrar a chave de acesso do gateway a ser utilizado. Além disso, os dados específicos de cada gateway devem ser mandados para cada transação no método confirmtransaction (Etapa 5 do processo de transação), todos eles descritos na seção 8 deste manual. 5. Fases e fluxo de dados O processo de uma transação é composto por três 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. EvoluCard Manual de Integração Versão 3.2 Setembro

6 II) Envio das condições da transação à EvoluCard Método preapprovetransaction 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) Confirmação da transação com envio do TOKEN de duas variáveis Método confirmtransaction A confirmação da transação ocorre mediante ao recebimento de um TOKEN, que será validado pela EvoluCard (Etapas 5 e 6). A EvoluCard reencaminhará a resposta obtida pelo adquirente, e todos os dados da transação. 6. 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: 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 6.1. Obtenção dos cartões disponíveis do cliente (Etapa 1) Descrição A Etapa 1 corresponde à requisição para obter os cartões cadastrados do cliente com a EvoluCard, que podem ser utilizados no estabelecimento. EvoluCard Manual de Integração Versão 3.2 Setembro

7 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 Descrição 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 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) Descrição 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. EvoluCard Manual de Integração Versão 3.2 Setembro

8 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.80 }, { "binnumber":"111222", "description":"cartão Exemplo 2", "id":"nti3na*3", paymentbrand : MASTERCARD, consumerfare : 0.80 } ] } JSON em caso de erro: { code : EV004" } Parâmetro Descrição Formato Tamanho Exemplo code Código de sucesso ou erro. EV000 em caso de sucesso. Para os demais erros, ver seção 7 AN 1..5 EV004 EvoluCard Manual de Integração Versão 3.2 Setembro

9 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 N description id paymentbrand consumerfare Campo de cardlist. Descrição do cartão do cliente Campo de cardlist. Id do cartão do cliente Campo de cardlist. Bandeira do cartão do cliente Campo de cardlist. Juros do consumidor T n/a Cartão Principal T n/a NTI3MQ*3 AN n/a VISA M n/a 0.80 Considerações Vale lembrar que quando o campo consumerfare de cardlist retornar 0.00, indica que não tem juros pro consumidor pois é uma integração com recebimento pelo adquirente. 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 3.2 Setembro

10 6.3. Envio das condições da transação à EvoluCard (Etapa 3) Descrição O estabelecimento enviará o cartão a ser utilizado pelo cliente, e os dados da transação, incluindo as condições 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 Descrição 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 installmentresponsible Responsável pelo parcelamento: Estabelecimento(M) ou Administradora(A) AN O 1 M Considerações O campo installmentresponsible deve ser enviado com o valor M, caso a transação seja feita em 1 parcela, ou caso o estabelecimento esteja passando uma transação com recebimento pela EvoluCard. EvoluCard Manual de Integração Versão 3.2 Setembro

11 6.4. Retorno da EvoluCard à solicitação na Etapa 3 (Etapa 4) Descrição 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. 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 Descrição Formato Tamanho Exemplo code docnumber transactionnumberevc Código de sucesso ou erro. EV000 em caso de sucesso. Para os demais erros, ver seção 7 Número do documento que o estabelecimento utiliza para identificar a transação Número de Transação EvoluCard. Esse será o número usado pelo estabelecimento para identificar a transação deste passo em diante AN 1..5 EV004 N N EvoluCard Manual de Integração Versão 3.2 Setembro

12 additionalinfo Campo que indica o que deve ser devolvido no campo birthinfo na próxima etapa (confirmtransaction). 0 Vazio, 1 Dia do aniversário, 2 Mês do aniversário, 3 - Ano do aniversário do cliente 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 Considerações Enviado o TOKEN pela primeira vez, o estabelecimento possui o tempo de 15 minutos para informar à 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 funciona da seguinte maneira: se o cliente teve as duas últimas compras reprovadas por erro de TOKEN (EV019 ou EV029), 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 7.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) Descrição 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 EvoluCard Manual de Integração Versão 3.2 Setembro

13 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. Parâmetro Descrição Formato Obrigatoriedade Tamanho Exemplo transactionnumberevc Número de Transação EvoluCard. É o número recebido na resposta do preapprovetransaction (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 Descrição Formato Tamanho Exemplo code Código de sucesso ou erro. EV000 em caso de sucesso. Para os demais erros, ver seção 7 AN 1..5 EV004 EvoluCard Manual de Integração Versão 3.2 Setembro

14 resend Indica o número de reenvios ainda permitidos, com valor máximo de 2 N 1 2 Considerações Vale ressaltar que essa etapa estará disponível no máximo duas vezes, como definido no campo resend do método preapprovetransaction (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) Descrição 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 EvoluCard Manual de Integração Versão 3.2 Setembro

15 Parâmetros Na tabela a seguir, os parâmetros que o estabelecimento enviará o TOKEN e as informações adicionais quando solicitadas. Parâmetro Descrição Formato Obrigatoriedade Tamanho Exemplo transactionnumberevc token birthinfo Número de Transação EvoluCard. É o número recebido na resposta do preapprovetransaction (Etapa 4) TOKEN digitado pelo cliente. Composto do TOKEN aleatório + senha Informação adicional do cliente. Pode ser vazio, dia, mês ou ano de nascimento dependendo do campo additionalinfo N O N O N C 2 06 Campos para integração com gateway/adquirente Devem ser enviados todos os campos referente a sua integração descritos na seção 8 deste manual n/a n/a n/a n/a 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 preapprovetransaction anteriormente detalhado. Os campos da integração com o gateway/adquirente, como descrito na seção 8, tem uma maneira específica para serem enviados, que depende da forma de integração utilizada (POST ou webservice). A aprovação ou reprovação da transação no ambiente de testes está detalhada na seção (Etapa 6) Retorno final da EvoluCard Descrição É concedido nessa etapa o retorno final da EvoluCard. Dependendo da validação do TOKEN, do retorno do gateway de pagamento e do adquirente, a transação estará aprovada ou reprovada. 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. EvoluCard Manual de Integração Versão 3.2 Setembro

16 JSON em caso de sucesso: { "code": EV000, "transactionnumberevc":" , "transactionnumberacq":" ", "authorizationnumber":" ", "merchantsalesnewdto": { "consumercard":"cartão Principal", "consumermobile":"+55 (19) ", "consumername":"josé da Silva", " monthlypayment ":"2", "value":"r$ 1.690,00", consumervalue : R$ 1.844,80, monthlypaymentvalue : R$ 230,60, consumercardname : JOSE DA SILVA, consumercardnumber : XXXX1234 } } JSON em caso de erro: { code : EV019", "transactionnumberevc":" ", "merchantsalesnewdto": { "consumercard":"cartão Principal", "consumermobile":"+55 (19) ", "consumername":"josé da Silva", " monthlypayment ":"8", "value":"r$ 1.690,00", consumervalue : R$ 1.844,80, monthlypaymentvalue : R$ 230,60, consumercardname : JOSE DA SILVA, consumercardnumber : XXXX1234 } } Parâmetro Descrição Formato Tamanho Exemplo code transactionnumberevc Código de sucesso ou erro. EV000 em caso de sucesso. Para os demais erros, ver seção 7 Número de Transação EvoluCard. É o número recebido na resposta do preapprovetransaction (Etapa 4) AN 1..5 EV019 N EvoluCard Manual de Integração Versão 3.2 Setembro

17 transactionnumberacq Número de Transação do Adquirente AN n/a authorizationnumber merchantsalesnewdto Número de autorização da transação enviado pelo adquirente Campo no JSON de resposta que contém as informações da compra. Este é composto por 7 campos descritos a seguir AN n/a JSON n/a Ver o exemplo acima consumercard Informa a descrição do cartão do cliente T n/a Cartão Principal consumermobile Informa o celular do cliente T n/a +55 (19) consumername Informa a nome do cliente T n/a José da Silva monthlypayment value consumervalue Informa o número de parcelas da transação Informa o valor da transação sem juros Informa o valor da transação com juros N T n/a R$ 1.690,00 T n/a R$ 1.844,80 monthlypaymentvalue Informa o valor da parcela com juros T n/a R$ 230,60 consumercardname consumercardnumber Informa o nome do consumidor que está em seu cartão Informa os primeiros 6 dígitos e os últimos 4 dígitos do cartão do cliente com 4 caracteres X entre eles T n/a JOSE DA SILVA T n/a XXXX1234 Considerações Caso seja uma transação com recebimento pelo adquirente, os campos consumervalue e monthlypaymentvalue não serão retornados. O estabelecimento que possuir uma integração com captura manual deve consultar o seguinte manual: Manual Integração EvoluCard Captura Manual. A aprovação ou reprovação da transação no ambiente de testes está detalhada na seção Reenvio do token fornecido pelo cliente (ETAPA EXTRA 2) Descrição 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 3.2 Setembro

18 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 7.4, dado que essa etapa utiliza o mesmo método (confirmtransaction) da etapa 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. Qualquer erro que tenha sido gerado por um adquirente ou gateway de pagamentos será devolvido exatamente como recebido pela EvoluCard. Assim facilitará para que o estabelecimento identifique o erro ocorrido, apenas observando o manual de seu adquirente ou gateway de pagamento. 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 Descrição 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". EvoluCard Manual de Integração Versão 3.2 Setembro

19 EV104 Número do celular do cliente inválido. Verifique o formato enviado no campo "mobilenb" Erros gerados no método preapprovetransaction Na tabela abaixo estão listados os códigos de erro e a descrição de cada erro no método preapprovetransaction da integração EvoluCard. Código EV000 EV002 EV003 EV004 EV005 EV007 EV008 EV009 EV010 EV011 EV020 EV025 EV027 EV028 EV031 EV032 EV101 EV105 EV106 EV107 EV108 EV109 Descrição 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. 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. Não foi encontrada uma integração para efetuar a transação. Verifique o cadastro do estabelecimento, para certificar que há integrações para a bandeira do cartão escolhido. Transação reprovada por crédito. (APENAS AMBIENTE DE TESTES) TOKEN não enviado. Entre em contato com a EvoluCard. Erro de comunicação com o integrador (adquirente ou gateway). 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. Plano do estabelecimento não possui o número de parcelas da transação efetuada. 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". Responsável pelo parcelamento inválido. Verifique o formato enviado no campo "installmentresponsible" 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. EvoluCard Manual de Integração Versão 3.2 Setembro

20 Código EV000 EV004 EV005 EV007 EV013 EV014 EV015 EV016 EV017 EV018 EV026 EV111 Descrição 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" Erros gerados no método confirmtransaction Na tabela abaixo estão listados os códigos de erro e a descrição de cada erro no método confirmtransaction da integração EvoluCard. Código EV000 EV004 EV005 EV007 EV009 EV012 EV018 EV019 EV020 EV021 EV022 EV023 EV029 EV030 EV031 EV099 EV110 Descrição 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. Não foi encontrada uma integração para efetuar a transação. Verifique o cadastro do estabelecimento para certificar que há integrações para a bandeira do cartão escolhido. Transação reprovada pelo adquirente. (APENAS AMBIENTE DE TESTES) Transação não encontrada. TOKEN incorreto na primeira tentativa. Se desejar, tente novamente. Erro de comunicação com o integrador (adquirente ou gateway). Informação adicional de nascimento incorreta na primeira tentativa. Se desejar, tente novamente. Tempo limite para finalização da transação excedido. Não foi encontrado integrador para efetuar a transação. Verifique o cadastro do estabelecimento para certificar que há integrações para a bandeira do cartão escolhido. TOKEN incorreto na segunda tentativa. Transação reprovada. Informação adicional de nascimento incorreta na segunda tentativa. Transação reprovada. Plano do estabelecimento não possui o número de parcelas da transação efetuada. 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". EvoluCard Manual de Integração Versão 3.2 Setembro

21 EV111 EV112 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". 8. Campos para integração com gateways e adquirentes Como explicado anteriormente, a EvoluCard mantém o mesmo fluxo utilizado pelo estabelecimento para efetuar as transações. Por isso, temos no cadastro do estabelecimento todos os parâmetros fixos, que ele precisa enviar aos gateways de pagamento ou adquirentes, para se identificar. Além disso, para alguns estabelecimentos será necessário enviar parâmetros adicionais a cada transação, como Taxa de Embarque para uma companhia aérea. Esses parâmetros são enviados juntamente com os demais parâmetros do método confirmtransaction, identificados por additionalparams.parâmetro, na integração por HTTPS/POST. Por exemplo, caso tenha que ser enviado o parâmetro IATA, o nome do parâmetro na requisição será additionalparams.iata. Quando utilizada a integração por webservice (SOAP), os parâmetros devem ser enviados dentro de uma instância da classe AdditionalParamsDTO (como especificado na WSDL), ou seja, caso tenha que ser enviado o parâmetro IATA com valor 123, então o atributo IATA da classe AdditionalParamsDTO deve ser preenchido com 123. Abaixo teremos as tabelas referentes a cada integração e seus parâmetros com a seguinte legenda: OF Obrigatório e Fixo O campo é fixo e sempre será enviado para o gateway. Portanto, este ficará cadastrado em nosso sistema. OV Obrigatório e Variável - O campo sempre será enviado para o gateway. Entretanto, este sempre será enviado pelo estabelecimento à EvoluCard pois varia a cada transação. NF Não obrigatório e Fixo - O campo pode ou não ser enviado ao gateway. Sendo assim, no cadastro do estabelecimento será preenchido como obrigatório ou não de acordo com a definição do estabelecimento. Se obrigatório, seu valor ficará cadastrado em nosso sistema e será sempre enviado pela EvoluCard ao gateway. NV Não obrigatório e Variável - O campo pode ou não ser enviado ao gateway, então no cadastro do estabelecimento será preenchido como obrigatório ou não de acordo com a opção do estabelecimento. Se obrigatório, seu valor deve sempre ser enviado pelo estabelecimento à EvoluCard a cada transação. Caso contrário, mesmo que enviado pelo estabelecimento, a EvoluCard não repassará esse campo ao gateway. Serão colocadas apenas as descrições dos parâmetros obrigatórios, os demais parâmetros devem ser avaliados utilizando os manuais de cada gateway/adquirente. EvoluCard Manual de Integração Versão 3.2 Setembro

22 8.1. Integração CIELO Parâmetro Descrição Tipo Exemplo Chave de Acesso Número da Afiliação Chave de acesso fixa usada pela Cielo Número de afiliação do estabelecimento com a Cielo OF n/a OF Integração REDECARD Parâmetro Descrição Tipo Exemplo Número de Filiação Número de afiliação do estabelecimento com a Redecard OF ENTRADA n/a NF n/a IATA n/a NF n/a DISTRIBUIDOR n/a NF n/a CONCENTRADOR n/a NF n/a TAXAEMBARQUE n/a NV n/a NUMDOC1 n/a NV n/a NUMDOC2 n/a NV n/a NUMDOC3 n/a NV n/a NUMDOC4 n/a NV n/a ADD_DATA n/a NV n/a PABX1 n/a NV n/a PABX2 n/a NV n/a PABX3 n/a NV n/a PABX4 n/a NV n/a 9. 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. EvoluCard Manual de Integração Versão 3.2 Setembro

23 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. 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 Aprovação e reprovação A aprovação ou reprovação no ambiente de teste depende do valor da transação. Caso a transação tenha centavos no valor, como R$ , então a transação será reprovada. Senão, como em R$ , será aprovada 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 preapprovetransaction 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 preapprovetransaction 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 preapprovetransaction 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 acontece por SMS/ligação. EvoluCard Manual de Integração Versão 3.2 Setembro

24 10. 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. Um 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. 11. 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 3.2 Setembro

25 ANEXO I Diagrama da integração Aprovação com Captura Automática: EvoluCard Manual de Integração Versão 3.2 Setembro

26 Aprovação com Captura Manual: EvoluCard Manual de Integração Versão 3.2 Setembro

27 ANEXO II Diagrama dos atores da integração EvoluCard Manual de Integração Versão 3.2 Setembro