DOCUMENTAÇÃO DE INTEGRAÇÃO 3DS

DOCUMENTAÇÃO DE INTEGRAÇÃO 3DS V 1.0.0

ÍNDICE INTRODUÇÃO 2 CENÁRIOS DE TESTES (SANDBOX) 3 CARTÕES PARA TESTES (SANDBOX) 3 TRANSAÇÃO COM 3DS 3 3DS URLs Para Envio dos Dados... 6 3DS Exemplo de Requisição... 6 3DS Exemplo de Retorno em Caso de Sucesso... 8 3DS Parâmetros Retornados Após Efetivação do Pagamento... 8 3DS Tabela de Parâmetros de Envio... 9 3DS Tabela de Parâmetros de Retorno... 10 ANEXOS... 12 Parâmetros retornados no <transaction-response/>... 12 Retorno de Transação... 13 Transação Aprovada... 13 Transação Negada... 14 Transação com Erro... 15 Tabela de Erros 1024... 15 SUPORTE... 15 MAXIPAGO! SMART PAYMENTS 2013 1

Introdução Este manual tem como finalidade, auxiliar nossos clientes no processo de integração do 3DS. Nossa intenção é minimizar suas dúvidas, no entanto, se elas surgirem estaremos à disposição para auxiliá-lo através dos nossos canais de atendimento, listados abaixo: Suporte ao Cliente maxipago! E-mail: suporte@maxipago.com Telefone: (11) 2121-8536 MAXIPAGO! SMART PAYMENTS 2013 2

Cenários de Testes (Sandbox) No ambiente de testes é possível simular a maioria das requisições e transações. Tipo de Requisição Cenário Resultado Venda Direta (Sale) Valor par menor que R$: 300,00 e maior que R$: 500,00 Aprovada Venda Direta (Sale) Valor impar menor que R$: 300,00 e maior que R$: 500,00 Negada Venda Direta (Sale) Valor entre R$: 300,00 e R$: 500,00 Parcialmente Aprovada Autorização (Auth) Valor par menor que R$: 300,00 ou maior que R$: 500,00 e com número de cartão Negada por Fraude 4901720380077300 Autorização (Auth) Valor par menor que R$: 300,00 ou maior que R$: 500,00 e com número de cartão 4901720366459100 Em Revisão de Fraude Cartões para Testes (Sandbox) Tipo Número Data Vencimento Código Segurança American Express 378282246310005 06/18 123 American Express 371449635398431 06/18 123 Diners 30569309025904 06/18 123 JCB 3528888888888000 06/18 123 MasterCard 5555555555554444 06/18 123 MasterCard 5111111111111100 06/18 123 Visa 4111111111111111 06/18 123 Visa 4012888888881881 06/18 123 Transação com 3DS Para poder efetuar pagamentos via 3DS, o lojista deverá informar a maxipago! solicitar a ativação do serviço através da equipe suporte via e-mail (suporte@maxipago.com) e também informar a URL de callback (URL para a qual a maxipago! enviará as alterações de status das transações). A estrutura do XML de INPUT deverá ficar da seguinte forma: MAXIPAGO! SMART PAYMENTS 2013 3

<transaction-request> <version/> <verification> <merchantid/> <merchantkey/> </verification> <order> <auth> <referencenum/> <ipaddress/> <invoicenumber/> <useragent/> <authentication> <!-- Se ausente, ou vazio <authentication/>, a autenticação será processada --> <mpiprocessorid/> <onfailure/> </authentication> <fraudcheck/> <frauddetails/> <!-- Análise de fraude pode ser solicita, mas somente será processada se o cartão não estiver habilitado para 3DS somente e a tag onfailure contiver o valor continue, indicando que o processo deve continuar mesmo que a autenticação não seja possível --> <billing> <name/> <address/> <address2/> <city/> <state/> <postalcode/> <country/> <phones/> <email/> </billing> <shipping> <name/> <address/> <address2/> <city/> <state/> <postalcode/> <country/> <phones/> <email/> </shipping> MAXIPAGO! SMART PAYMENTS 2013 4

<transactiondetail> <paytype> <creditcard> <number/> <expmonth/> <expyear/> <cvvnumber/> <cvvind/> </creditcard> </paytype> </transactiondetail> <payment> <chargetotal/> <salestaxtotal/> <shippingtotal/> <currencycode/> </payment> </auth> <clientdata> <comments/> </clientdata> </order> </transaction-request> A estrutura do XML de OUTPUT deverá ficar da seguinte forma: <transaction-response> <authcode/> <orderid/> <referencenum/> <transactionid/> <transactiontimestamp/> <responsecode/> <responsemessage/> <avsresponsecode/> <cvvresponsecode/> <processorcode/> <processormessage/> <processorreferencenumber/> <processortransactionid/> <errormessage/> <authenticationurl/> <authenticated/> </transaction-response> Or, if there is an error: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <api-error> <errorcode></errorcode> <errormsg></errormsg> </api-error> MAXIPAGO! SMART PAYMENTS 2013 5

3DS URLs Para Envio dos Dados SANDBOX: https://testapi.maxipago.net/universalapi/postxml PRODUÇÃO: https://api.maxipago.net/universalapi/postxml 3DS Exemplo de Requisição <transaction-request> <version>3.1.1.15</version> <verification> <merchantid>store-id</merchantid> <merchantkey>secret-key</merchantkey> </verification> <order> <auth> <processorid>1</processorid> <referencenum>mpi3ds-001</referencenum> <ipaddress>123.123.123.123</ipaddress> <useragent> Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.112 Safari/537.36 </useragent> <authentication> <mpiprocessorid>15</mpiprocessorid> <onfailure>decline</onfailure> </authentication> <billing> <name>fulano de Tal</name> <address>av. Paulista, 1728</address> <address2>7 Andar</address2> <district>bela Vista</district> <city>sao Paulo</city> <state>sp</state> <postalcode>01310200</postalcode> <country>br</country> <phone>1140099400</phone> <email>fulanodetal@email.com</email> <phones> <phone> <phonetype>commercial</phonetype> <phonecountrycode>55</phonecountrycode> <phoneareacode>11</phoneareacode> <phonenumber>55554444</phonenumber> <phoneextension>b101</phoneextension> </phone> MAXIPAGO! SMART PAYMENTS 2013 6

<phone> <phonetype>residential</phonetype> <phonecountrycode>55</phonecountrycode> <phoneareacode>11</phoneareacode> <phonenumber>55554444</phonenumber> <phoneextension>b101</phoneextension> </phone> </phones> </billing> <shipping> <name>fulanica de Tal</name> <address>rua de Teste, 123</address> <district>centro</district> <city>são Paulo</city> <state>sp</state> <postalcode>12345000</postalcode> <country>br</country> <phones> <phone> <phonetype>commercial</phonetype> <phonecountrycode>55</phonecountrycode> <phoneareacode>11</phoneareacode> <phonenumber>55554444</phonenumber> <phoneextension>b101</phoneextension> </phone> <phone> <phonetype>residential</phonetype> <phonecountrycode>55</phonecountrycode> <phoneareacode>11</phoneareacode> <phonenumber>55554444</phonenumber> <phoneextension>b101</phoneextension> </phone> </phones> </shipping> <transactiondetail> <paytype> <creditcard> <number>4000000000000002</number> <expmonth>01</expmonth> <expyear>2020</expyear> <cvvnumber>915</cvvnumber> </creditcard> </paytype> </transactiondetail> <payment> <chargetotal>50.00</chargetotal> </payment> </auth> </order> </transaction-request> MAXIPAGO! SMART PAYMENTS 2013 7

3DS Exemplo de Retorno em Caso de Sucesso <?xml version="1.0" encoding="utf-8"?> <transaction-response> <orderid>7f000101:01547c17882c:8158:7d804e45</orderid> <transactionid>488636</transactionid> <transactiontimestamp>1462370790</transactiontimestamp> <responsecode>0</responsecode> <responsemessage>enrolled</responsemessage> <creditcardscheme>visa</creditcardscheme> <authenticationurl> https://server/auth?ref=zksqpgqtdwlrvvwqj%2f%2bpzgudzmmft 2qIlwYlmazCZseHxGHzV%2BSXzIjq%2FIf%2FwvJizHMeUDcJXIMR1K </authenticationurl> <authenticated>n</authenticated> </transaction-response> 3DS Parâmetros Retornados Após Efetivação do Pagamento Após a autenticação do ACS, o pagamento é processado e o resultado será retornado ao Merchant através "URL de sucesso" (a partir das configurações do comerciante) para que o mesmo possa exibir o resultado do pagamento. Parâmetros HTTP em resposta: [hp_time] => 05/06/16 06:14:36 PM [hp_responsecode] => 0 [hp_responsemsg] => AUTHORIZED [hp_processortxnid] => 251444 [hp_processorrefno] => 51246255 [hp_processormsg] => Authorized successfully [hp_refnum] => MPI3DS-001 [hp_transid] => 488636 [hp_avsresponse] => [hp_cvvresponse] => [hp_authcode] => 325645 [hp_orderid] => 7F000101:01547C17882C:8158:7D804E45 [hp_amount] => 50.00 [hp_errormsg] => [hp_authenticated] => Y [hp_creditcardscheme] => Visa MAXIPAGO! SMART PAYMENTS 2013 8

No exemplo acima, a resposta indica que pagamento está em autorizado. Quando essa transação muda de status no 3DS, a maxipago! recebe uma mensagem assíncrona informando o novo status. Esse novo status é repassado ao lojista através de um POST na sua URL de callback. 3DS Tabela de Parâmetros de Envio Nome Obrigatório Descrição version Sim Versão da API merchantid Sim Id da loja que identifica o estabelecimento merchantkey Sim Chave associada ao ID da loja Identificador do pedido no estabelecimento referencenum Sim Este campo aceita apenas valores alfanuméricos e deve ser único. Código da Adquirente que irá processar a transação processorid Sim 3DS = 20 ipaddress Não Endereço IP do comprador useragent Sim Navegador utilizado pelo comprador mpiprocessorid Sim Código da Lyra (VAN) que irá processar a transação. Crédito é possível a escolhar de aprovação via transação normal caso a Lyra reprove o 3DS. onfailure Sim Decline para cancelar Approve para aprovar name Sim Billing: nome impresso no cartão Shipping: nome do destinatário address Sim Billing: endereço da fatura do cartão Shipping: endereço de entrega do produto address2 Sim Billing/ Shipping: complemento district Sim Billing/ Shipping: bairro city Sim Billing/ Shipping: cidae state Sim Billing/ Shipping: estado postalcode Sim Billing/ Shipping: cep country Sim Billing/ Shipping: país phone Sim Número de telefone email Sim Billing/ Shipping: email Utilize: - Residential - Commercial phonetype Sim - Mobile - Fax - Underfined - Message - Billing phonecountrycode Sim DDI do número de telefone phoneareacode Sim DDD (utiliza sempre 2 dígitos sem adição de 0 ) phonenumber Sim Número de telefone MAXIPAGO! SMART PAYMENTS 2013 9

phoneextension Sim Ramal ou complemento chargetotal Sim Valor do pedido number Sim Número do cartão de crédito do cliente expmonth Sim Mês de vencimento do cartão com 2 dígitos expyear Sim Ano de vencimento do cartão com 4 dígitos cvvnumber Sim Código de segurança do cartão 3DS Tabela de Parâmetros de Retorno hp_time Nome Descrição Data e hora da transação Status da transação na maxipago! Você deve utilizar APENAS este campo para validar o resultado de uma transação. Não utilize outros campos da resposta para determinar o sucesso ou falha de uma transação. hp_responsecode 0 = aprovada (*) 1 = negada 2 = Negada por Duplicidade ou Fraude 5 = Em Revisão (Análise Manual de Fraude) 1022 = Erro na operadora de cartão 1024 = Erro nos parâmetros enviados (**) 1025 = Erro nas credenciais 2048 = Erro interno na maxipago! 4097 = Timeout com a adquirente (*): Para adquirentes com estorno online, o valor 0 significa que o estorno já foi processado, para os off-line significa que o estorno está sendo processado (neste caso pode ser posteriormente verificado pela API de consulta) hp_responsemsg hp_processortxnid hp_processorrefno hp_processormsg hp_refnum hp_transid (**): Ver Tabela de Erros 1024' na página 18 deste manual. Mensagem de resposta da transação ID da transação na adquirente Número de referência do adquirente Mensagem de retorno da adquirente Número de referência da adquirente ID da transação, gerado pela maxipago!. Deve-se salvar este campo para futuras referências ao pedido. Resposta da verificação AVS, se houver: hp_avsresponse hp_authcode - X: O número da rua e o CEP conferem; - A: O número da rua confere, mas o CEP não; - N: O número da rua e o CEP não conferem; - W: O CEP confere, mas o número da rua não. - S: O serviço não está disponível para este cartão, - C: Serviço indisponível OBSERVAÇÃO: sugerimos que a resposta AVS seja usada para avaliação manual do risco Código de autorização retornado pela adquirente MAXIPAGO! SMART PAYMENTS 2013 10

hp_orderid hp_amount hp_errormsg hp_authenticated ID do pedido, gerado pela maxipago!. Deve-se salvar este campo para futuras referências ao pedido. Valor do Item. Os decimais devem ser separados por ponto (".") Mensagem de erro, se houver Y Quando a autenticação ocorre a transação com sucesso. N ou vazio - Quando o processo de autenticação não for realizado. MAXIPAGO! SMART PAYMENTS 2013 11

Anexos Parâmetros retornados no <transaction-response/> Nome authcode referencenum orderid transactionid transactiontimestamp Descrição Código de autorização retornado pela adquirente Confirmação do código enviado na requisição ID do pedido, gerado pela maxipago! Deve-se salvar este campo para futuras referências ao pedido Id da transação, gerado pela maxipago! Deve-se salvar este campo para futuras referências ao pedido Data/hora da transação em formato epoch Indicador do status da transação na maxipago! Você deve utilizar apenas este campo para validar o resultado de uma transação. Não utilize outros campos da resposta para determinar o sucesso ou falha de uma transação. responsecode 0 = aprovada (*) 1 = negada 2 = negada por duplicidade ou fraude 5 = em revisão (análise manual de fraude) 1022 = erro na operadora do cartão 1024 = erro nos parâmetros enviados (**) 1025 = erro nas credenciais 2048 = erro interno na maxipago! 4097 = timeout com a adquirente (*): Para adquirente com estorno online, o valor 0 significa que o estorno já foi processado, para os off-line significa que o estorno está sendo processado (neste caso pode ser posteriormente verificado pela API de consulta). responsemessage avsresponsecode processorcode processormessage processorreferencenumber (**): Ver Tabela de Erros 1024' na página 18 deste manual. Mensagem de resposta da transação Resposta da verificação AVS, se houver: - X: O número da rua e o CEP conferem; - A: O número da rua confere, mas o CEP não; - N: O número da rua e o CEP não conferem; - W: O CEP confere, mas o número da rua não. - S: O serviço não está disponível para este cartão, - C: Serviço indisponível Obs.: sugerimos que a resposta AVS seja usada para avaliação manual do risco. Código de retorno da Adquirente Linha digitável do boleto Mensagem de retorno da adquirente Número de referência da adquirente Cielo: TID MAXIPAGO! SMART PAYMENTS 2013 12

processortransactionid fraudscore errormessage error Rede: NSU ID da transação na adquirente Cielo: NSU Rede: comprovante de venda (CV) Valor de score retornado pelo antifraude Quanto menor o valor, menor o risco da transação. Mensagem de erro, se houver Presente só quando há erro na tentativa de salvar automaticamente o cartão, traz a mensagem de erro. Vem dentro do elemento <save-on-file/>. Retorno de Transação O retorno das requisições de transação possui um padrão único, independentemente do tipo de transação efetuada. Contudo, nem todos os campos são retornados em todas as transações. Transação Aprovada <?xml version="1.0" encoding="utf-8"?> <transaction-response> <authcode>005772</authcode> <orderid>7f000001:013829a1c09e:8de9:016891f0</orderid> <referencenum>123456789</referencenum> <transactionid>1418605</transactionid> <transactiontimestamp>1340728262</transactiontimestamp> <responsecode>0</responsecode> <responsemessage>captured</responsemessage> <avsresponsecode/> <cvvresponsecode/> <processorcode>0</processorcode> <processormessage>approved</processormessage> <errormessage/> <processortransactionid>2612953</processortransactionid> <processorreferencenumber>689472845</processorreferencenumber> </transaction-response> MAXIPAGO! SMART PAYMENTS 2013 13

Transação Negada <?xml version="1.0" encoding="utf-8"?> <transaction-response> <authcode/> <orderid>7f000001:013d16cf1461:f0ef:014eda77</orderid> <referencenum>2012071201</referencenum> <transactionid>3308</transactionid> <transactiontimestamp>1361887302962</transactiontimestamp> <responsecode>1</responsecode> <responsemessage>declined</responsemessage> <avsresponsecode>nnn</avsresponsecode> <cvvresponsecode>n</cvvresponsecode> <processorcode>d</processorcode> <processormessage>declined</processormessage> <errormessage/> </transaction-response> Transação com Parâmetros Inválidos <?xml version="1.0" encoding="utf-8"?> <transaction-response> <authcode/> <orderid/> <referencenum/> <transactionid/> <transactiontimestamp>1361887531821</transactiontimestamp> <responsecode>1024</responsecode> <responsemessage>invalid REQUEST</responseMessage> <avsresponsecode/> <cvvresponsecode/> <processorcode/> <processormessage/> <errormessage>credit Card Number is not a valid credit card number.</errormessage> </transaction-response> MAXIPAGO! SMART PAYMENTS 2013 14

Transação com Erro <?xml version="1.0" encoding="utf-8" standalone="yes"?> <api-error> <errorcode>1</errorcode> <errormsg><![cdata[schema validation for the vertical SA for the incoming transaction xml failed. Reason Parser Error: URI=null Line=1: cvcdatatype-valid.1.2.1:'100,01' is not a valid value for 'decimal'.]]></errormsg> </api-error> Tabela de Erros 1024 Mensagem Credit Card Number is not a valid credit card number The transaction has an expired credit car A transaction with boletonumber = XXX already exists in the data base Transaction Amount is not a valid number in the range of 0.01 to 1.0E14 Reques tis invalid and can not be processed Descrição Número de cartão de crédito não é válido Data de vencimento do cartão não é válida O campo boletonumber enviado já existe em nosso sistema para este lojista O valor da transação não é válido O campo processorid enviado não é válido. Suporte O suporte aos desenvolvedores é feito exclusivamente através do nosso Portal de Suporte. Os dados de acesso são enviados para os nossos clientes a partir do e-mail suporte@maxipago.com com o assunto "maxipago! e-mail de boas-vindas" para o e-mail usado no credenciamento. A equipe de suporte da maxipago! pode lhe ajudar com a integração do seu sistema. Suporte ao Cliente maxipago! E-mail: suporte@maxipago.com Telefone: (11) 2121-8536 MAXIPAGO! SMART PAYMENTS 2013 15