DOCUMENTAÇÃO DE INTEGRAÇÃO 3DS

Transcrição

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

2 Í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 DS Exemplo de Requisição DS Exemplo de Retorno em Caso de Sucesso DS Parâmetros Retornados Após Efetivação do Pagamento DS Tabela de Parâmetros de Envio DS Tabela de Parâmetros de Retorno ANEXOS Parâmetros retornados no <transaction-response/> Retorno de Transação Transação Aprovada Transação Negada Transação com Erro Tabela de Erros SUPORTE MAXIPAGO! SMART PAYMENTS

3 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! Telefone: (11) MAXIPAGO! SMART PAYMENTS

4 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 Autorização (Auth) Valor par menor que R$: 300,00 ou maior que R$: 500,00 e com número de cartão Em Revisão de Fraude Cartões para Testes (Sandbox) Tipo Número Data Vencimento Código Segurança American Express / American Express / Diners / JCB / MasterCard / MasterCard / Visa / Visa / 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 (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

5 <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/> < /> </billing> <shipping> <name/> <address/> <address2/> <city/> <state/> <postalcode/> <country/> <phones/> < /> </shipping> MAXIPAGO! SMART PAYMENTS

6 <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

7 3DS URLs Para Envio dos Dados SANDBOX: PRODUÇÃO: 3DS Exemplo de Requisição <transaction-request> <version> </version> <verification> <merchantid>store-id</merchantid> <merchantkey>secret-key</merchantkey> </verification> <order> <auth> <processorid>1</processorid> <referencenum>mpi3ds-001</referencenum> <ipaddress> </ipaddress> <useragent> Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/ (KHTML, like Gecko) Chrome/ Safari/ </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> </postalcode> <country>br</country> <phone> </phone> <phones> <phone> <phonetype>commercial</phonetype> <phonecountrycode>55</phonecountrycode> <phoneareacode>11</phoneareacode> <phonenumber> </phonenumber> <phoneextension>b101</phoneextension> </phone> MAXIPAGO! SMART PAYMENTS

8 <phone> <phonetype>residential</phonetype> <phonecountrycode>55</phonecountrycode> <phoneareacode>11</phoneareacode> <phonenumber> </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> </postalcode> <country>br</country> <phones> <phone> <phonetype>commercial</phonetype> <phonecountrycode>55</phonecountrycode> <phoneareacode>11</phoneareacode> <phonenumber> </phonenumber> <phoneextension>b101</phoneextension> </phone> <phone> <phonetype>residential</phonetype> <phonecountrycode>55</phonecountrycode> <phoneareacode>11</phoneareacode> <phonenumber> </phonenumber> <phoneextension>b101</phoneextension> </phone> </phones> </shipping> <transactiondetail> <paytype> <creditcard> <number> </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

9 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> </transactiontimestamp> <responsecode>0</responsecode> <responsemessage>enrolled</responsemessage> <creditcardscheme>visa</creditcardscheme> <authenticationurl> 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] => [hp_processorrefno] => [hp_processormsg] => Authorized successfully [hp_refnum] => MPI3DS-001 [hp_transid] => [hp_avsresponse] => [hp_cvvresponse] => [hp_authcode] => [hp_orderid] => 7F000101:01547C17882C:8158:7D804E45 [hp_amount] => [hp_errormsg] => [hp_authenticated] => Y [hp_creditcardscheme] => Visa MAXIPAGO! SMART PAYMENTS

10 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 Sim Billing/ Shipping: 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

11 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

12 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

13 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

14 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> </referencenum> <transactionid> </transactionid> <transactiontimestamp> </transactiontimestamp> <responsecode>0</responsecode> <responsemessage>captured</responsemessage> <avsresponsecode/> <cvvresponsecode/> <processorcode>0</processorcode> <processormessage>approved</processormessage> <errormessage/> <processortransactionid> </processortransactionid> <processorreferencenumber> </processorreferencenumber> </transaction-response> MAXIPAGO! SMART PAYMENTS

15 Transação Negada <?xml version="1.0" encoding="utf-8"?> <transaction-response> <authcode/> <orderid>7f000001:013d16cf1461:f0ef:014eda77</orderid> <referencenum> </referencenum> <transactionid>3308</transactionid> <transactiontimestamp> </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> </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

16 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 suporte@maxipago.com com o assunto "maxipago! de boas-vindas" para o usado no credenciamento. A equipe de suporte da maxipago! pode lhe ajudar com a integração do seu sistema. Suporte ao Cliente maxipago! suporte@maxipago.com Telefone: (11) MAXIPAGO! SMART PAYMENTS