DOCUMENTAO DE INTEGRAO

v1.9

Histrico de Revises

Verso 1.0 1.1 1.2 1.3 1.4

Data 30/01/2012 13/02/2012 27/02/2012 16/03/2012 03/04/2012 Verso inicial do manual.

Descrio

Adicionada observao sobre pular linha nas instrues de boleto. Adicionados campos no Post da smartPage!. Adicionado o campo transactionState no retorno das consultas. Adicionados comentrios em outros campos do retorno das consultas. Modificados campos no comando add-consumer. Removido o campo hp_cmd (obsoleto) da smartPage! Adicionada a seo de carto salvo da smartPage! Adicionado o Anexo A com os fluxos de pagamento. Adicionada referncia ao processorID = 1 (Simulador de Testes de carto). Adicionados os campos currencyCode e hp_currency para definir a moeda da transao. Adicionado comando para cancelamento de recorrncia. Adicionada a adquirente Chase Paymentech (EUA multi-moeda) Adicionado o campo hp_lang para escolha de idioma na smartPage! Adicionados os campos hp_cf_1 a hp_cf_5 na smartPage! Adicionado o campo hp_customer_token na smartPage! Corrigido nomenclatura do campo hp_savepayment na smartPage! Removido o campo campo eCommInd (obsoleto) Adicionada a nova funcionalidade fraudControl! Corrigido exemplo do XML do comando delete-card-onfile Adicionado o meio de pagamento Dbito Online Adicionada a lista de erros mais comuns

1.5

16/04/2012

1.6

02/08/2012

1.7 1.8 1.9

10/12/2012 04/01/2013 25/02/2013

maxiPago! Smart Payments 2013

ndice
Sobre este manual .................................................................................................................................................... 5 Glossrio ...................................................................................................................................................................... 5 Escolhendo o seu tipo de integrao .................................................................................................................. 6 Ambiente de Testes .................................................................................................................................................. 7 Credenciais do Estabelecimento .......................................................................................................................... 8 Tipos de Requisio ................................................................................................................................................. 9 Requisies de Transao - Carto de Crdito .............................................................................................. 10 Autorizao ....................................................................................................................................................................................... 11 Captura ............................................................................................................................................................................................... 14 Venda Direta ..................................................................................................................................................................................... 16 Void ....................................................................................................................................................................................................... 18 Estorno ................................................................................................................................................................................................ 19 Recorrncias ..................................................................................................................................................................................... 21 Criar uma recorrncia ....................................................................................................................................................... 21 Cancelar uma recorrncia ................................................................................................................................................ 23 Dados do Comprador .................................................................................................................................................................... 24 fraudControl! Controle de Fraude .................................................................................................................. 26 Requisies de Fraude .................................................................................................................................................................. 26 Exemplo de chamada com fraudControl!: ................................................................................................................ 26 Exemplo de chamada sem fraudControl! : ................................................................................................................ 27 Respostas de Fraude ...................................................................................................................................................................... 28 iFrame para anlise de browser .............................................................................................................................................. 29 Requisies de Transao - Boleto ................................................................................................................... 30 Gerando um boleto ........................................................................................................................................................................ 30 Conciliando pagamentos de boleto ........................................................................................................................................ 32 Requisies de Transao Dbito Online .................................................................................................... 33 Enviando uma transao de dbito ........................................................................................................................................ 33 Retorno de Transao ........................................................................................................................................... 35 Transao Aprovada ..................................................................................................................................................................... 37 Transao Negada ......................................................................................................................................................................... 37 Parmetros Invlidos ................................................................................................................................................................... 37 Outros erros ...................................................................................................................................................................................... 38 Requisies de Cadastro ....................................................................................................................................... 39 Adicionar um cliente ..................................................................................................................................................................... 40 Remover um cliente ....................................................................................................................................................................... 42 maxiPago! Smart Payments 2013 3

Atualizar um cliente ...................................................................................................................................................................... 43 Salvar um carto na base ........................................................................................................................................................... 45 Remover um carto da base ...................................................................................................................................................... 48 Retorno do Cadastro .............................................................................................................................................. 49 Transaes com token .......................................................................................................................................... 50 Recorrncias com token ....................................................................................................................................... 51 Salvar o carto automaticamente ..................................................................................................................... 52 Requisio de Consulta ......................................................................................................................................... 54 Consultar uma nica transao ............................................................................................................................................... 55 Consultar uma lista de transaes .......................................................................................................................................... 56 Retorno da Consulta .............................................................................................................................................. 59 Utilizando o sistema de paginao .................................................................................................................... 64 Consultas em massa ...................................................................................................................................................................... 66 Sondando o resultado de uma busca em massa ................................................................................................................ 67 smartPage! - Integrao por HTTPS Post ........................................................................................................ 69 Envio da transao ........................................................................................................................................................................ 70 Salvar o carto automaticamente .......................................................................................................................................... 73 Resultado da transao ............................................................................................................................................................... 74 Assinatura de validao do Post .............................................................................................................................................. 77 Suporte integrao .............................................................................................................................................. 78 Anexo A Fluxos de Transaes ..................................................................................................................... 79 Autorizao e Captura Pedido em duas etapas ............................................................................................................. 79 Venda Direta Resposta imediata ao comprador ........................................................................................................... 80 Venda Direta Resposta assncrona ...................................................................................................................................... 80 Emisso e pagamento de Boleto .............................................................................................................................................. 81 Estorno Adquirente com resposta online ......................................................................................................................... 82 Estorno Adquirente com resposta offline ......................................................................................................................... 82 Salvar carto automaticamente .............................................................................................................................................. 83 smartPage Integrao via HTTPS POST ........................................................................................................................... 84 Anexo B Moedas ................................................................................................................................................ 85

maxiPago! Smart Payments 2013

Sobre este manual

Este manual cobre os conceitos bsicos das operaes de pagamento e os detalhes tcnicos de integrao com a plataforma da maxiPago!. Ele contm exemplos funcionais das requisies, que podem ser copiados e usados nos primeiros testes, alm de observaes importantes a serem levadas em conta durante a integrao. A ltima verso deste manual est disponvel em http://www.maxipago.com/docs/maxiPago_API_Ultima.pdf

Glossrio
Empresa responsvel pelo processamento do carto e pelo pagamento do valor da compra ao Estabelecimento (ex: Cielo, Redecard) Empresa que licencia seu nome para a emisso de cartes. Ela a "marca" do carto (ex: Visa, Mastercard, Diners) Combinao do ID de Loja e da Chave de Loja, ambas fornecidas pela maxiPago! Cdigo de segurana do carto Banco responsvel por verificar se o Portador possui limite de crdito para fazer aquela compra. (ex.: Ita, Bradesco, HSBC). Lojista que vende seus produtos e servios online Identificador nico da loja dentro da maxiPago! e parte da Credencial. Cliente, comprador, titular do carto de crdito

Adquirente Bandeira Credenciais CVV ou CVN Emissor Estabelecimento ID de Loja Portador

maxiPago! Smart Payments 2013

Escolhendo o seu tipo de integrao

Integrao via API
A principal caracterstica da integrao via API que os dados do carto de crdito so digitados no site do estabelecimento e ento enviados para a maxiPago!. No existe pop-up nem redirecionamentos. A responsabilidade de coletar os dados do carto do comprador do estabelecimento, logo, deve existir uma preocupao com a segurana dos dados. necessria a compra de um certificado de segurana SSL.

A maxiPago! possui bibliotecas de integrao em Java, .NET e PHP disposio para ajudar com o desenvolvimento de sua plataforma. As bibliotecas esto disponveis online no endereo http://www.maxipago.com/api.

Integrao via smartPage!

A smartPage! uma forma rpida de integrao a nossa plataforma. O comprador, aps finalizar o pedido, redirecionado para o nosso ambiente e l ele informa os dados do carto de crdito para fazer o pagamento. Assim o Estabelecimento no o responsvel por gerenciar e proteger os dados desse comprador, a maxiPago! cuida disso.

maxiPago! Smart Payments 2013

Ambiente de Testes
No ambiente de testes possvel simular a maioria das requisies e transaes. Lembre-se que no ambiente de testes nenhuma transao ser de fato processada. Abaixo temos a lista de cenrios que geraro respostas programadas da nossa plataforma: Cenrio Transao com valor par, menor que R$300,00 ou maior que R$500,00 Exemplo: R$1,00 ou R$299,92 ou R$610,06 Transao com valor mpar, menor que R$300,00 ou maior que R$500,00 Exemplo: R$1,01 ou R$20,09 ou R$700,55 Transao com valor entre R$300,00 e R$500,00 Exemplo: R$310,00 ou R$499,99 Transao com valor par, menor que R$300,00 ou maior que R$500,00 e com o nmero de carto 4901720380077300 Transao com valor par, menor que R$300,00 ou maior que R$500,00 e com o nmero de carto 4901720366459100 Resultado da Transao Aprovada

Negada Parcialmente Aprovada (funcionalidade disponvel apenas nos EUA) Negada por Fraude Em Reviso de Fraude

Abaixo h uma lista de cartes teste disponveis. O campo de CVV pode ser preenchido com qualquer nmero com 3 ou 4 dgitos e a data de vencimento precisa apenas ser vlida, ou seja, sempre no futuro: Tipo American Express American Express MasterCard MasterCard Visa Visa JCB JCB Nmero de Teste 378282246310005 371449635398431 5555555555554444 5111111111111100 4111111111111111 4012888888881881 3112222222222225 3528888888888000

maxiPago! Smart Payments 2013

Credenciais do Estabelecimento
Para qualquer chamada feita em nossa base preciso que o Estabelecimento se identifique com as suas credenciais. O ID de Loja e a sua Chave so informados pela nossa equipe quando seu cadastro criado.

Independentemente da requisio que estiver chamando voc dever informar suas credenciais dentro do elemento <verification/>, da seguinte forma: <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification>

Caso haja um erro nas credenciais voc ver algum destes erros: ErrorCode ErrorMsg Causa merchantId ou merchantKey no existe ou est incorreto Erro no merchantKey URL da requisio errada -ouErro no merchantId O elemento merchantKey no foi enviado

Unable to authenticate merchant empty element detected in setPsInParams for field=vertical_id empty element detected in setPsInParams for field=merchant_id The content of element 'verification' is not complete. One of {merchantKey} is expected

maxiPago! Smart Payments 2013

Tipos de Requisio
A troca de informaes com a maxiPago! feita atravs de XML enviado diretamente no corpo do Post -ele no deve estar dentro de nenhum parmetro e nem ser enviado em um formulrio.

O content type deve ser text/xml e o charset deve ser UTF-8.

H trs tipos de requisio que podem ser feitas plataforma: Requisio de Transao: Processa pedidos de Carto de Crdito e Boleto N raiz do XML: <transaction-request/>, retornando <transaction-response/> Requisio de Cadastro: Efetua operaes cadastrais, como salvar um carto da nossa base N raiz do XML: <api-request/>, retornando <api-response/> Requisio de Consulta: Busca pedidos em nossa base N raiz do XML: <rapi-request/>, retornando <rapi-response/> Cada tipo de requisio tem uma URL de teste especfica: URL https://testapi.maxipago.net/UniversalAPI/postXML https://testapi.maxipago.net/UniversalAPI/postAPI https://testapi.maxipago.net/ReportsAPI/servlet/ReportsAPI https://testsecure.maxipago.net/hostpay/HostPay

TRANSAES CADASTRO CONSULTA smartPage! (HTTPS POST)

maxiPago! Smart Payments 2013

Requisies de Transao - Carto de Crdito

Estas requisies so responsveis por processar pedidos de carto de crdito e so identificadas atravs do n raiz <transaction-request/>. Esta API recebe os dados de cobrana, como valor do pedido e nmero de carto de crdito. O seu retorno contm o status da transao (aprovada ou negada) e os principais dados do pedido. As requisies de transao devem conter o nmero da verso da API dentro da tag <version/>, e deve ser o primeiro elemento do XML.

Verso atual da API: 3.1.1.15 URL de Teste: https://testapi.maxipago.net/UniversalAPI/postXML

A tag <order/>, enviada logo abaixo da verificao das credenciais, deve conter os dados para efetuar a transao. H 6 tipos de operaes suportadas pelo sistema da maxiPago!. Sua escolha feita de acordo com o elemento enviado dentro da tag <order/>: Autorizao: Envia os dados do carto para autorizao Captura: Captura uma transao previamente autorizada Venda Direta: Efetua a autorizao e captura na mesma requisio Void: Cancela um pedido capturado (at s 23h59m do mesmo dia) Estorno: Solicita o estorno de um pedido j confirmado Recorrncia: Agenda cobranas futuras no carto de crdito

A estrutura do XML deve ficar da seguinte forma: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <auth> | <capture> | <sale> | <void> | <return> | <recurringPayment> <order/> <transaction-request/>

maxiPago! Smart Payments 2013

10

Autorizao
A Autorizao verifica se o carto de crdito usado vlido (nmero, CVV e data de validade), se o Portador possui limite suficiente para a compra e se a transao passou na verificao de fraude do Banco e da Adquirente. Esta a fase mais importante da transao, pois a autorizao bloqueia o valor do pedido no carto do cliente e garante o pagamento para o Estabelecimento, "reservando" aquele valor. Contudo, a autorizao sozinha no efetiva a transao -- ela depois precisa ser capturada. Os parmetros aceitos na Autorizao so: Nome version (obrigatrio) merchantId (obrigatrio) merchantKey (obrigatrio) referenceNum (obrigatrio) Verso da API ID de Loja que identifica o Estabelecimento Chave associada ao ID de Loja Identificador do pedido no Estabelecimento Este valor deve ser nico Cdigo da Adquirente que ir processar esta transao SIMULADOR DE TESTES = 1 Redecard = 2 Amex = 3 Cielo = 4 ChasePaymentech = 8 Flag para enviar transao para verificao de fraude. Se deixado em branco a transao ser verificada Y ou vazio/nulo = Checar N = No checar Este campo s funciona para clientes que possuem o servio de antifraude contratado ipAddress number (obrigatrio) Endereo de IP do comprador Nmero do carto de crdito do cliente Descrio

processorID (obrigatrio)

fraudCheck

maxiPago! Smart Payments 2013

11

expMonth (obrigatrio) expYear (obrigatrio)

Ms de vencimento do carto com 2 dgitos Exemplo: Janeiro = 01; Novembro = 11 Ano de vencimento do carto com 4 dgitos Cdigo de segurana do carto Obs: Embora o campo no seja obrigatrio em nosso sistema as Adquirentes podem bloquear transaes caso este campo esteja vazio. Por favor cheque suas permisses na Adquirente. Cdigo da moeda da transao no formado ISO 4217 Vlido somente para transaes Chase Paymentech. Lista completa de moedas: anexo B. Valor do pedido Os decimais devem ser separados por ponto (".") Exemplo: 15.00 ou 1649.99 Nmero de parcelas da transao Para transaes vista no enviar. Define se o parcelamento do tipo Loja ou Carto Para transaes vista no enviar. N = Sem juros (parcelamento Loja) Y = Com juros (parcelamento Carto)

cvvNumber

currencyCode

chargeTotal (obrigatrio) numberOfInstallments

chargeInterest

Este XML envia uma autorizao para a loja teste: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <auth> <processorID>1</processorID> <fraudCheck>N</fraudCheck> <referenceNum>123456789</referenceNum> <transactionDetail> <payType> <creditCard> <number>4111111111111111</number> <expMonth>12</expMonth> <expYear>2020</expYear> <cvvNumber>999</cvvNumber> </creditCard> </payType> </transactionDetail> <payment>
maxiPago! Smart Payments 2013

12

<currencyCode>BRL</currencyCode> <chargeTotal>10.00</chargeTotal> <creditInstallment> <numberOfInstallments>2</numberOfInstallments> <chargeInterest>N</chargeInterest> </creditInstallment> </payment> </auth> </order> </transaction-request>

maxiPago! Smart Payments 2013

13

Captura
A Captura de uma transao confirma e completa aquele pedido. Se a transao nunca for capturada o Estabelecimento no receber o dinheiro e o Portador no ser cobrado. Neste caso a autorizao vence aps 5 dias. A captura no faz nenhuma validao, ou seja, ela no verifica novamente os dados enviados na autorizao. Ao pedir a captura o Estabelecimento est apenas informando que ele quer, de fato, completar a venda.

Por que o Estabelecimento no capturaria uma compra? Os principais motivos so anlise de fraude e verificao de estoque, mas h diversas outras razes que so particulares de cada modelo de negcio. Entre a autorizao e a captura o Estabelecimento pode fazer uma anlise interna do pedido para determinar o seu grau de risco, por exemplo. Caso haja algo suspeito, ele pode tentar contatar diretamente o comprador para verificar o pedido antes de captur-lo. No caso da verificao de estoque, caso o produto no esteja mais disponvel o Estabelecimento pode simplesmente no capturar o pedido, deixando vencer a autorizao. Desta forma no h a necessidade de se gerar um Estorno.

Captura Total x Captura Parcial Algumas Adquirentes permitem que o Estabelecimento faa uma captura parcial do pedido. Isto significa que, apesar de se ter uma autorizao feita no valor total do pedido, o Estabelecimento capturar apenas uma parte dela, deixando o resto do valor vencer. Isto particularmente til quando o cliente pede mais de um produto no mesmo pedido e um deles no est mais disponvel no estoque. Digamos que temos pedido formato por dois produtos, um de R$60,00 e outro de R$40,00, que j foi autorizado em sua totalidade (R$100,00). Contudo, a checagem de estoque mostra que o segundo produto, de R$40,00, est em falta. Neste caso o Estabelecimento pode fazer uma captura parcial de R$60,00, completar parte de sua venda e notificar o cliente do ocorrido.

maxiPago! Smart Payments 2013

14

Um pedido nunca est completo se a captura no foi feita. Sem ela o Estabelecimento no garante que receber o valor devido!

Os parmetros aceitos pela Captura so: Nome version (obrigatrio) merchantId (obrigatrio) merchantKey (obrigatrio) orderID (obrigatrio) referenceNum (obrigatrio) chargeTotal (obrigatrio) Verso da API ID de Loja que identifica o Estabelecimento Chave associada ao ID de Loja Valor nico associado ao pedido pela maxiPago! no momento da Autorizao Identificador do pedido dentro do Estabelecimento Deve ser o mesmo enviado na Autorizao Valor a ser capturado. Pode ser igual ou menor que o valor da autorizao Os decimais devem ser separados por ponto (".") Exemplo: 10.00 Descrio

Este XML captura a autorizao anterior, basta apenas trocar o campo "orderID": <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <capture> <orderID>C0A8C866:0119C7CF0530:3B39:009770A3</orderID> <referenceNum>123456789</referenceNum> <payment> <chargeTotal>6.00</chargeTotal> </payment> </capture> </order> </transaction-request>

maxiPago! Smart Payments 2013

15

Venda Direta
A Venda Direta (ou "Sale") combina a Autorizao e a Captura em uma mesma chamada. Ao usar a requisio de Venda Direta voc estar fazendo uma autorizao no carto do cliente e imediatamente executando uma captura total do valor. O retorno da maxiPago! j vir com o status final da transao. Os parmetros da Venda Direta so idnticos aos recebidos na autorizao: Nome version (obrigatrio) merchantId (obrigatrio) merchantKey (obrigatrio) referenceNum (obrigatrio) Verso da API ID de Loja que identifica o Estabelecimento Chave associada ao ID de Loja Identificador nico do pedido Cdigo da Adquirente que ir processar esta transao SIMULADOR DE TESTES = 1 Redecard = 2 Amex = 3 Cielo = 4 ChasePaymentech = 8 Flag para enviar transao para verificao de fraude. Se deixado em branco a transao ser verificada Y ou vazio/nulo = Checar N = No checar Este campo s funciona para clientes que possuem o servio de antifraude contratado ipAddress number (obrigatrio) expMonth (obrigatrio) expYear (obrigatrio) cvvNumber Endereo de IP do comprador Nmero do carto de crdito do cliente Ms de vencimento do carto com 2 dgitos Exemplo: Janeiro = 01; Novembro = 11 Ano de vencimento do carto com 4 dgitos Cdigo de segurana do carto Descrio

processorID (obrigatrio)

fraudCheck

maxiPago! Smart Payments 2013

16

Obs: Embora o campo no seja obrigatrio em nosso sistema as Adquirentes podem bloquear transaes caso este campo esteja vazio. Por favor cheque suas permisses na Adquirente. currencyCode Cdigo da moeda da transao no formado ISO 4217 Vlido somente para transaes Chase Paymentech. Lista completa de moedas: anexo B. Valor do pedido Os decimais devem ser separados por ponto (".") Exemplo: 15.00 ou 1649.99 Nmero de parcelas da transao Para transaes vista no enviar. Define se o parcelamento do tipo Loja ou Carto Para transaes vista no enviar. N = Sem juros (parcelamento Loja) Y = Com juros (parcelamento Carto)

chargeTotal (obrigatrio) numberOfInstallments

chargeInterest

A estrutura do XML tambm muito similar autorizao, mudando somente a operao: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <sale> <processorID>1</processorID> <referenceNum>987654321</referenceNum> <ipAddress>123.123.123.123</ipAddress> <fraudCheck>Y</fraudCheck> <transactionDetail> <payType> <creditCard> <number>4111111111111111</number> <expMonth>12</expMonth> <expYear>2020</expYear> <cvvNumber>999</cvvNumber> </creditCard> </payType> </transactionDetail> <payment> <currencyCode>BRL</currencyCode> <chargeTotal>12.00</chargeTotal> </payment> </sale> </order> </transaction-request>
maxiPago! Smart Payments 2013

17

Void
O Void o cancelamento de uma captura antes do fechamento do lote final do dia. Se por alguma razo o pedido no pode ser completado e a transao j foi capturada o Void cancela a venda efetuada, anulando aquela transao.

Importante: o Void s permitido at as 23:59 do dia da captura (horrio de Braslia).

Os parmetros mais comuns aceitos pelo Void so: Nome version (obrigatrio) merchantId (obrigatrio) merchantKey (obrigatrio) transactionID (obrigatrio) Verso da API ID de Loja que identifica o Estabelecimento Chave associada ao ID de Loja ID da transao gerado pela maxiPago! na Autorizao Descrio

O XML do Void simples e possui poucos campos: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <void> <transactionID>32165498701</transactionID> </void> </order> </transaction-request>

maxiPago! Smart Payments 2013

18

Estorno
O Estorno a reverso de uma transao de carto de crdito, debitando o valor do Estabelecimento e devolvendo-o ao Portador. O estorno uma operao financeira e envolve outros departamentos dentro das Adquirentes. Por esta razo, em geral os estornos demoram alguns dias para serem aprovados. A tabela abaixo indica o prazo de resposta de um Estorno para cada adquirente: Adquirente Cielo Redecard Amex Prazo de resposta 1-2 dias teis 2-3 dias teis Online, resposta imediata

No caso das adquirentes que no possuem resposta online, aps solicitar um estorno o Estabelecimento deve checar o status da transao na maxiPago! para verificar se a operao foi aprovada pela Adquirente. Enquanto a Adquirente no responde o estorno ficar como pendente em nossa plataforma. Os parmetros recebidos pela operao de Estorno so: Nome version (obrigatrio) merchantId (obrigatrio) merchantKey (obrigatrio) orderID (obrigatrio) referenceNum (obrigatrio) chargeTotal (obrigatrio) Verso da API ID de Loja que identifica o Estabelecimento Descrio

Chave associada ao ID de Loja Valor nico associado ao pedido pela maxiPago! no momento da Autorizao Identificador do pedido dentro do Estabelecimento Deve ser o mesmo enviado na Autorizao Valor a ser estornado. Pode ser igual ou menor que o valor da autorizao Os decimais devem ser separados por ponto (".") Exemplo: 10.00 ou 1699.00

maxiPago! Smart Payments 2013

19

Este XML executa um estorno de R$5,00: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <return> <orderID>C0A8C866:0119C7CF0530:3B39:009770A3</orderID> <referenceNum>123456789</referenceNum> <payment> <chargeTotal>5.00</chargeTotal> </payment> </return> </order> </transaction-request>

maxiPago! Smart Payments 2013

20

Recorrncias
A maxiPago! oferece aos seus clientes a possibilidade de agendar cobranas recorrentes de carto de crdito. Nesta modalidade o nmero e a data de vencimento do carto so guardados em nossos servidores seguros, junto com o intervalo de cobrana. A maxiPago! ficar encarregada de cobrar o seu cliente quando chegar a hora.

Criar uma recorrncia A estrutura do XML de uma transao recorrente muito similar ao de uma requisio de Venda Direta. O n <recurring/> deve ser utilizado para determinar o intervalo de cobrana do pedido, e o nome do elemento da transao <recurringPayments/> (ao invs de <sale/> ou <auth/>) Os parmetros recebidos pelo n <recurring/> so: Nome action (obrigatrio) startDate (obrigatrio) period (obrigatrio) Sempre ser new. Data de incio da cobrana. Formato: AAAA-MM-DD Intervalo de tempo entre cobranas daily = dia(s) weekly = semana(s) monthly = ms(es) Frequncia da cobrana. Este campo combinado com o <period> para definir o intervalo. Exemplo: Se "frequency" = 2 e "period" = weekly, ento cobrar a cada 2 semanas. Se deixado em branco ser entendido como "1". installments (obrigatrio) Nmero de cobranas a serem efetuadas Exemplo: Se "installments" = 5, ento sero feitas 5 cobranas seguindo o intervalo definido acima, a partir da data de incio. Nmero de tentativas negadas necessrias para ativar notificao por e-mail loja. Mnimo = 1 Descrio

frequency (obrigatrio)

failureThreshold (obrigatrio)

maxiPago! Smart Payments 2013

21

Este XML cria um novo pagamento a cada 2 meses, comeando em 25/12/2020, com 5 cobranas: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <recurringPayment> <processorID>1</processorID> <referenceNum>12304560</referenceNum> <ipAddress>123.123.123.123</ipAddress> <transactionDetail> <payType> <creditCard> <number>4111111111111111</number> <expMonth>12</expMonth> <expYear>2020</expYear> <cvvNumber>999</cvvNumber> </creditCard> </payType> </transactionDetail> <payment> <currencyCode>BRL</currencyCode> <chargeTotal>22.00</chargeTotal> </payment> <recurring> <action>new</action> <startDate>2020-12-25</startDate> <frequency>2</frequency> <period>monthly</period> <installments>5</installments> <failureThreshold>1</failureThreshold> </recurring> </recurringPayment> </order> </transaction-request>

maxiPago! Smart Payments 2013

22

Cancelar uma recorrncia Para cancelar uma recorrncia via API preciso enviar o comando cancel-recurring e o orderID retornado pela maxiPago! no momento da criao do pedido.

Note que a requisio de cancelamento segue o mesmo padro as Requisies de Cadastro, descritos na seo de mesmo nome, e cuja URL de teste est abaixo: URL de Teste: https://testapi.maxipago.net/UniversalAPI/postAPI

Os parmetros recebidos pelo command cancel-recurring so: Nome merchantId (obrigatrio) merchantKey (obrigatrio) command (obrigatrio) orderID (obrigatrio) Descrio ID de Loja que identifica o Estabelecimento. Chave associada ao ID de Loja. Sempre ser cancel-recurring. ID do pedido gerado pela maxiPago! na criao da recorrncia.

Este XML cancela uma transao recorrente: <api-request> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <command>cancel-recurring</command> <request> <orderID>C0A8C866:0119C7CF0530:3B39:009770A3</orderID> </request> </api-request>

maxiPago! Smart Payments 2013

23

Dados do Comprador
A maxiPago! permite que voc nos envie os dados de cobrana (<billing/>) e de entrega (<shipping/>) do seu cliente final. Apesar destes dados serem opcionais recomendamos enviar ao menos o nome do portador do carto, para facilitar a referncia ao pedido. Os campos devem ser enviados na mesma chamada da Autorizao, Venda Direta, Recorrncia ou Boleto: Nome name (recomendado) address address2 city state postalcode country phone email Descrio Billing: Nome do portador do carto (recomendado) Shipping: Nome do destinatrio Billing: Endereo da fatura do carto Shipping: Endereo de entrega do produto Billing/Shipping: Complemento Billing/Shipping: Cidade Billing/Shipping: Estado Billing/Shipping: CEP Billing/Shipping: Pas Billing: Nmero de telefone do portador do carto Shipping: Nmero de telefone do destinatrio Billing: Email do portador do carto Shipping: Email do destinatrio

Abaixo temos o exemplo de um XML de Venda Direta com os dados de cobrana e entrega: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <sale> <processorID>1</processorID> <referenceNum>1234567890</referenceNum>
maxiPago! Smart Payments 2013

24

<billing> <name>Fulano de Tal</name> <address>Av. Repblica do Chile, 230</address> <address2>16 Andar</address2> <city>Rio de Janeiro</city> <state>RJ</state> <postalcode>20031-170</postalcode> <country>BR</country> <phone>2140099400</phone> <email>fulanodetal@email.com</email> </billing> <shipping> <name>Ciclano de Tal</name> <address>Av. Prestes Maia, 737</address> <address2>20 Andar</address2> <city>So Paulo</city> <state>SP</state> <postalcode>01031-001</postalcode> <country>BR</country> <phone>1121737900</phone> <email>ciclanodetal@email.com</email> </shipping> <transactionDetail> <payType> <creditCard> <number>4111111111111111</number> <expMonth>12</expMonth> <expYear>2020</expYear> <cvvNumber>999</cvvNumber> </creditCard> </payType> </transactionDetail> <payment> <currencyCode>BRL</currencyCode> <chargeTotal>20.00</chargeTotal> <creditInstallment> <numberOfInstallments>2</numberOfInstallments> <chargeInterest>N</chargeInterest> </creditInstallment> </payment> </sale> </order> </transaction-request>

maxiPago! Smart Payments 2013

25

fraudControl! Controle de Fraude

A maxiPago! fez uma parceria com uma das mais comentadas solues contra fraude que existem atualmente, a Kount (www.kount.com). Suas ferramentas contra fraudes esto totalmente integradas na nossa soluo e permitem que o lojista envie uma transao de carto e faa a anlise de fraude em uma requisio nica e com resposta em tempo real. Uma das grandes vantagens da Kount que ela conta com um sistema de Anlise em Tempo-Real que possui Device Fingerprinting multi-camada, Proxy Piercing, Geolocalizao, Velocity, Ligao entre lojitas, Proteo a aparelhos Mobile e Score dinmico. Para que a anlise seja completa o Lojista precisa incluir no seu carrinho um iFrame que aponta para a maxiPago!. Este iFrame, detalhado mais abaixo, permite que o browser do comprador seja analisado pelo algoritmo da Kount e de extrema importncia para o funcionamento do sistema de fraude.

Apesar da soluo Kount estar integrada na nossa plataforma de pagamentos, ela um produto contratado separadamente. Portanto, antes de testar, verifique com nossa equipe se voc adquiriu este produto.

Requisies de Fraude
As chamadas para o fraudControl! fazem parte da nossa API. Portanto, no h a necessidade de mtodos ou parmetros adicionais. Se o servio estiver contratado, basta enviar uma transao para que ela seja verificada. Todas as transaes de carto de crdito Aprovadas sero enviadas para o fraudControl!. Se quiser escolher quais transaes sero passadas pelo servio e quais sero processadas sem checagem de fraude, basta incluir o campo <fraudCheck/> na requisio com os valores Y ou N .

Exemplo de chamada com fraudControl!: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <sale> <processorID>1</processorID>
maxiPago! Smart Payments 2013

26

<referenceNum>ORD837283</referenceNum> <!-- Session ID --> <fraudCheck>Y</fraudCheck> <!-- ou campo omitido --> <transactionDetail> <payType> <creditCard> <number>4111111111111111</number> <expMonth>12</expMonth> <expYear>2020</expYear> <cvvNumber>999</cvvNumber> </creditCard> </payType> </transactionDetail> <payment> <currencyCode>BRL</currencyCode> <chargeTotal>12.00</chargeTotal> </payment> </sale> </order> </transaction-request>

Exemplo de chamada sem fraudControl! : <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <sale> <processorID>1</processorID> <referenceNum>987654321</referenceNum> <fraudCheck>N</fraudCheck> <transactionDetail> <payType> <creditCard> <number>4111111111111111</number> <expMonth>12</expMonth> <expYear>2020</expYear> <cvvNumber>999</cvvNumber> </creditCard> </payType> </transactionDetail> <payment> <currencyCode>BRL</currencyCode> <chargeTotal>12.00</chargeTotal> </payment> </sale> </order> </transaction-request>

maxiPago! Smart Payments 2013

27

Respostas de Fraude
A resposta da avaliao de fraude retornada junto com a resposta da transao de carto de crdito. O valor do campo responseCode indicar o status da transao e o campo fraudScore trar a nvel de risco para a transao, sendo 0 a mais segura e 99 a mais arriscada. Abaixo temos a lista completa de valores retornados no responseCode: Valor 0 1 2 Descrio Transao APROVADA Transao NEGADA pela Adquirente Transao NEGADA: alto risco de FRAUDE Aes do Lojista Nenhuma, pedido Aprovado Nenhuma, pedido Negado Nenhuma, pedido Negado Revisar pedido e executar ao manual no Portal: APROVAR NEGAR Tentar novamente Revisar requisio Contatar Suporte maxiPago!

Transao EM REVISO: anlise de FRAUDE

1022 1024 2048

Erro de processamento na Adquirente Erro nos parmetros enviados pelo lojista Erro interno na maxiPago!

maxiPago! Smart Payments 2013

28

iFrame para anlise de browser

Uma pea chave do fraudControl! a anlise do browser do comprador. Com esta informao possvel traar um perfil da mquina do comprador e avaliar a probabilidade daquela transao ser uma fraude onde, por exemplo, o computador est em um fuso horrio da Rssia mas o endereo de entrega no RJ. Para permitir a anlise o Lojista precisa incluir no seu carrinho um iFrame, passando em GET os campos abaixo: Campo m s Descrio Corresponde ao ID de Loja (merchantId) criado pela maxiPago! Nmero do pedido (referenceNum) criado pelo Lojista. Este valor deve ser o mesmo passado no campo referenceNum da API Hash HMAC-MD5 de validao, formado pela concatenao dos campos m e s, intercalados pelo smbolo * (asterisco). Exemplo: 100*ORD12345678

O iFrame fica, ento, da seguinte forma: <iframe width="1" height="1" frameborder="0" src="https://testauthentication.maxipago.net/redirection_service/logo?m=100&s=OR D12345678&h=a0195edb19af06462af4be978b921dd5"></iframe>

maxiPago! Smart Payments 2013

29

Requisies de Transao - Boleto

As transaes feitas com Boleto funcionam um pouco diferente das transaes com carto de crdito. Ao receber os dados do pedido ns geramos um boleto, disponvel online, e retornamos ao Estabelecimento a URL de acesso para este boleto. Ela pode ser acessada a qualquer momento antes do vencimento do boleto e at 60 dias aps o vencimento. O Estabelecimento tem a opo abrir o boleto imediatamente em seu site, fornecer o link para que o comprador abra o boleto ou enviar o link por email. Seja qual for a escolha, recomendamos guardar a URL do boleto caso seja necessria uma 2a. via.

Gerando um boleto
Para gerar um boleto, alm de passar os dados bsicos da transao preciso enviar o Nosso Nmero, ou nmero do boleto. Este campo identifica o boleto dentro do banco e usado para conciliar o pagamento. Portanto, o Nosso Nmero deve ser nico para cada boleto a fim de evitar problemas na conciliao. O boleto uma transao de venda direta, ou seja, utiliza a mesma tag <sale/>. Os dados do boleto, contudo, so passados dentro do elemento <boleto/>. Um boleto sempre nominal, portanto faz-se necessrio o envio dos dados do comprador no elemento <billing/>, sendo obrigatrio somente o nome. Os parmetros recebidos na gerao de um boleto so: Nome version (obrigatrio) merchantId (obrigatrio) merchantKey (obrigatrio) referenceNum (obrigatrio) processorID (obrigatrio) Verso da API ID de Loja que identifica o Estabelecimento Chave associada ao ID de Loja Identificador nico do pedido Cdigo do meio de pagamento Boleto Ita = 11 Boleto Bradesco = 12 (USE 12 PARA TESTES) Boleto Banco do Brasil = 13 Descrio

maxiPago! Smart Payments 2013

30

ipAddress chargeTotal (obrigatrio) expirationDate (obrigatrio)

Endereo de IP do comprador Valor do pedido. Os decimais devem ser separados por ponto (".") Exemplo: 15.00 ou 1649.99 Data de vencimento do boleto. Formato AAAA-MM-DD Nmero do boleto (Nosso Nmero), usado para identificar o boleto dentro do banco. Este valor deve ser nico para cada pedido, seno a transao ser rejeitada. O campo no deve passar de 8 caracteres. Instrues a serem impressas no boleto. Use ponto e vrgula (;) para pular uma linha. Exemplo: Sr. Caixa, no aceitar aps o vencimento.;Referente ao pedido 123.

number (obrigatrio)

instructions

Abaixo temos um exemplo de XML de gerao de boleto: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <sale> <processorID>12</processorID> <referenceNum>00987</referenceNum> <ipAddress>123.123.123.123</ipAddress> <billing> <name>Fulano de Tal</name> <address>Av. Repblica do Chile, 230</address> <address2>16 Andar</address2> <city>Rio de Janeiro</city> <state>RJ</state> <postalcode>20031-170</postalcode> <country>BR</country> <phone>2140099400</phone> <email>fulanodetal@email.com</email> </billing> <transactionDetail> <payType> <boleto>
maxiPago! Smart Payments 2013

31

<expirationDate>2022-12-25</expirationDate> <number>0112233</number> </boleto> </payType> </transactionDetail> <payment> <chargeTotal>12.00</chargeTotal> </payment> </sale> </order> </transaction-request>

Conciliando pagamentos de boleto

A confirmao de pagamento do boleto offline. A maxiPago! recebe um arquivo de pagamento do banco listando os boletos pagos para o Estabelecimento. Ns ento processamos este arquivo e atualizamos o status do pedido, que pode ser checado pelo Portal ou pela Requisio de Consulta. Para mais informaes sobre a confirmao de pagamentos de Boleto contate nossa equipe de Suporte.

maxiPago! Smart Payments 2013

32

Requisies de Transao Dbito Online

O dbito on-line um mtodo de pagamento onde o comprador redirecionado para a pgina de pagamento do seu banco, entra em sua conta corrente e autoriza o dbito para o Estabelecimento. Esse um mtodo de pagamento sem risco de fraude ou chargeback, j que uma vez que o pagamento foi confirmado o banco no poder estorn-lo. Depois de ter autorizado o pagamento o comprador redirecionado para a URL de Sucesso ou para a URL de Erro cadastradas pelo lojista, a depender do resultado da transao.

Enviando uma transao de dbito

Por se tratar de um meio de pagamento que obriga o redirecionamento para um ambiente externo, permitimos o envio de parmetros adicionais em GET para facilitar o rastreamento do pedido. Os campos aceitos pela requisio de dbito online esto abaixo: Name version (Obrigatrio) merchantId (Obrigatrio) merchantKey (Obrigatrio) referenceNum (Obrigatrio) processorID (Obrigatrio) chargeTotal (Obrigatrio) A verso da API ID de Loja que identifica o Estabelecimento Description

Chave associada ao ID de Loja

Identificador nico do pedido Cdigo do mtodo de pagamento Bradesco = 17 (USE 17 PARA TESTES) Ita = 18 Valor do pedido. Os decimais devem ser separados por ponto (".") Exemplo: 15.00 ou 1649.99 Parmetro que ser enviado em GET para a URL de Sucesso ou URL de Falha ao redirecionar o comprador de volta para o lojista. Por favor, deixe o campo vazio (no nulo) se no for usado. Exemplo: purchaseCode=123456&customer=987

parametersURL (Obrigatrio)

maxiPago! Smart Payments 2013

33

Abaixo temos o XML para uma transao de dbito on-line: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <sale> <processorID>17</processorID> <referenceNum>ORD4827294</referenceNum> <ipAddress>123.123.123.123</ipAddress> <billing> <name>Fulano de Tal</name> <address>Av. Repblica do Chile, 230</address> <address2>16 Andar</address2> <city>Rio de Janeiro</city> <state>RJ</state> <postalcode>20031-170</postalcode> <country>BR</country> <phone>2140099400</phone> <email>fulanodetal@email.com</email> </billing> <transactionDetail> <payType> <onlineDebit> <parametersURL>id=123456&tp=3</parametersURL> </onlineDebit> </payType> </transactionDetail> <payment> <chargeTotal>1.00</chargeTotal> </payment> </sale> </order> </transaction-request>

maxiPago! Smart Payments 2013

34

Retorno de Transao
O retorno das requisies de transao possui um padro nico, independentemente do tipo de transao efetuada. Contudo, nem todos os campos so retornados em todas as transaes. Os seguintes parmetros so retornados dentro do n raiz <transaction-response/>: Nome boletoURL Descrio URL para gerao do Boleto Recomenda-se salvar esta URL para uso futuras URL para redirecionamento do Dbito Online O cliente deve ser redirecionado para esta URL para completar a transao URL de autenticao O cliente deve ser redirecionado para esta URL para completar a etapa de autenticao. Cdigo de autorizao retornado pela adquirente Confirmao do cdigo enviado na requisio. ID do pedido, gerado pela maxiPago!. Deve-se salvar este campo para futuras referncias ao pedido. ID da transao, gerado pela maxiPago!. Deve-se salvar este campo para futuras referncias ao pedido. Data/hora da transao em formato epoch . 2 Veja aqui instrues de converso. Indicador do status da transao na maxiPago!. 0 = Aprovada 1 = Negada 2 = Negada por Fraude 5 = Em Reviso (Anlise Manual de Fraude) 1022 = Erro na operadora de carto 1024 = Erro nos parmetros enviados Ver 'responseMessage' para mais informaes 1025 = Erro nas credenciais
1

debitURL

authenticationURL authCode referenceNum orderID

transactionID

transactionTimestamp

responseCode

1 2

Mais informaes sobre o formato epoch (ou Unix time): http://pt.wikipedia.org/wiki/Era_Unix Exemplos de converso dos valores: http://www.epochconverter.com/#code

maxiPago! Smart Payments 2013

35

2048 = Erro interno na maxiPago! responseMessage avsResponseCode processorCode processorMessage processorReferenceNumber Mensagem de resposta da transao Resposta da verificao AVS, se houver Cdigo de retorno da Adquirente Mensagem de retorno da Adquirente Nmero de referncia da Adquirente Cielo: NSU Redecard: Comprovante de Venda (CV) ID da transao na Adquirente. Cielo: TID Redecard: NSU Valor de score retornado pelo fraudControl! Quanto menor o valor, menor o risco da transao Mensagem de erro, se houver Presente s quando um carto salvo automaticamente, traz o token nico daquele carto. Vem dentro do elemento <save-on-file/>. muito importante guardar esta informao para futura referncia! Presente s quando h erro na tentativa de salvar automaticamente o carto, traz a mensagem de erro. Vem dentro do elemento <save-on-file/>.

processorTransactionID

fraudScore errorMessage

token

error

maxiPago! Smart Payments 2013

36

Transao 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> <fraudScore>29</fraudScore> <save-on-file> <token>eBUv/SIBJv0=</token> </save-on-file> </transaction-response>

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

Parmetros Invlidos
<?xml version="1.0" encoding="UTF-8"?> <transaction-response> <authCode/> <orderID/> <referenceNum/> <transactionID/>
maxiPago! Smart Payments 2013

37

<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> Na tabela abaixo temos as mensagens de erro mais comuns para o Erro 1024: Mensagem Credit Card Number is not a valid credit card number The transaction has an expired credit card A transaction with boletoNumber = XXX already exists in the database Transaction Amount is not a valid number in the range of 0.01 to 1.0E14 Request is invalid and can not be processed Descrio Nmero de carto de crdito no vlido Data de vencimento do carto no vlida O campo boletoNumber enviado j existe em nosso sistema para este lojista O valor da transao no vlido O campo processorID enviado no vlido

Outros erros
<?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>

maxiPago! Smart Payments 2013

38

Requisies de Cadastro
As requisies de cadastro executam aes no-transacionais no sistema. Estas funes esto ligadas principalmente ao produto quickPago!, que permite salvar o carto de crdito do cliente em nossa base e gerenciar futuras transaes a partir de um token nico.

Ateno! A URL das Requisies de Cadastro diferente da usada para as transaes, e no h verso de API. URL de Teste: https://testapi.maxipago.net/UniversalAPI/postAPI

A estrutura do XML um pouco diferente nas requisies de Transao. A validao das credenciais permanece a mesma, mas surgem dois novos elementos, alm de ter outro n-raiz: <api-request/>. O elemento <command/> determina a funo a ser executada, enquanto que o n <request/> contm os detalhes da requisio. Os comandos disponveis so: add-consumer: cria um cadastro para o cliente com as suas informaes bsicas. Sem um cadastro no possvel executar as demais funes. delete-consumer: remove o cadastro do cliente update-consumer: atualiza o cadastro do cliente add-card-onfile: adiciona um carto de crdito ao cadastro do cliente delete-card-onfile: remove um carto de crdito do cadastro do cliente

A estrutura bsica do XML fica, ento, da seguinte forma: <api-request> <verification> <merchantId/> <merchantKey/> </verification> <command/> <request> </request> </api-request>

maxiPago! Smart Payments 2013

39

Adicionar um cliente
Antes de se adicionar um carto base preciso criar um cadastro do cliente usando o comando addconsumer. Os parmetros aceitos no comando add-consumer esto abaixo. Se o campo for vazio, no enviar. Nome merchantId (obrigatrio) merchantKey (obrigatrio) command (obrigatrio) customerIdExt (obrigatrio) firstName (obrigatrio) lastName (obrigatrio) address1 address2 city state zip country phone email dob sex Descrio ID de Loja que identifica o Estabelecimento Chave associada ao ID de Loja Comando a ser executado Para criar um cadastro: add-consumer Identificador interno do Estabelecimento para o cliente. Nome do cliente Sobrenome do cliente Endereo da residncia do cliente Endereo da residncia do cliente - Complemento Cidade da residncia do cliente UF da residncia do cliente 2 letras seguindo padro brasileiro. ZZ = Fora do Brasil. CEP da residncia do cliente Pas (ISO 3166-2) Telefone do cliente E-mail do cliente Data de nascimento do cliente Formato MM/DD/AAAA Sexo do cliente. F = Feminino | M = Masculino

maxiPago! Smart Payments 2013

40

O XML exemplo abaixo cria a conta de um cliente: <api-request> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <command>add-consumer</command> <request> <customerIdExt>00000001</customerIdExt> <firstName>Fulano</firstName> <lastName>de Tal</lastName> <zip>20031170</zip> <email>fulano@exemplo.com</email> <dob>12/25/1970</dob> <ssn>12345678909</ssn> <sex>M</sex> </request> </api-request>

maxiPago! Smart Payments 2013

41

Remover um cliente
O comando delete-consumer remove o cliente e todas as informaes ligadas ao cadastro da base. Esta operao no pode ser desfeita. Os parmetros aceitos no comando delete-consumer so: Nome merchantId (obrigatrio) merchantKey (obrigatrio) command (obrigatrio) customerId (obrigatrio) Descrio ID de Loja que identifica o Estabelecimento Chave associada ao ID de Loja Comando a ser executado Para remover um cadastro: delete-consumer ID nico do cadastro, retornado quando o cliente foi adicionado base

O XML abaixo remove o cadastro de um cliente fictcio: <api-request> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <command>delete-consumer</command> <request> <customerId>999</customerId> </request> </api-request>

maxiPago! Smart Payments 2013

42

Atualizar um cliente
O comando update-consumer permite atualizar os dados salvos dentro do cadastro do cliente. Os parmetros aceitos e o formato da chamada so muito similares ao comando add-consumer. A principal diferena que este mtodo requer o envio do campo customerId. Os parmetros aceitos so: Nome merchantId (obrigatrio) merchantKey (obrigatrio) command (obrigatrio) customerId (obrigatrio) customerIdExt (obrigatrio) firstName lastName address1 address2 city state zip phone email dob ssn Descrio ID de Loja que identifica o Estabelecimento Chave associada ao ID de Loja Comando a ser executado Para atualizar um cadastro: update-consumer ID nico do cadastro, retornado quando o cliente foi adicionado base Identificador interno do Estabelecimento para o cliente. Nome do cliente Sobrenome do cliente Endereo da residncia do cliente Endereo da residncia do cliente - Complemento Cidade da residncia do cliente UF da residncia do cliente 2 letras seguindo padro brasileiro. ZZ = Fora do Brasil. CEP da residncia do cliente Telefone do cliente E-mail do cliente Data de nascimento do cliente Formato MM/DD/AAAA CPF ou CNPJ do cliente Obs: Este campo apenas para referncia. No sero feitas

maxiPago! Smart Payments 2013

43

validaes dos dados enviados. sex Sexo do cliente. F = Feminino | M = Masculino

O XML exemplo abaixo atualiza o cadastro de um cliente: <api-request> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <command>update-consumer</command> <request> <customerId>999</customerId> <customerIdExt>00000001</customerIdExt> <firstName>Fulano</firstName> <lastName>de Tal</lastName> <zip>20031170</zip> <email>fulano@exemplo.com</email> <dob>12/25/1970</dob> <ssn>12345678909</ssn> <sex>M</sex> </request> </api-request>

maxiPago! Smart Payments 2013

44

Salvar um carto na base

O quickPago! permite ao Estabelecimento salvar o carto de crdito do cliente para futuras compras. O nmero de carto e a data de vencimento ficam guardados em nossos servidores e o Estabelecimento recebe um token nico referente ao carto. Em uma futura compra, ao invs de pedir novamente o nmero de carto ao cliente o Estabelecimento envia o token para a maxiPago!, agilizando o checkout.

Como funciona o armazenamento de nmeros de cartes? A maxiPago! possui servidores de alta disponibilidade e alta performance, localizados nos Estados Unidos. Somos auditados periodicamente dentro dos padres PCI-DSS , que determinam as regras de segurana para o armazenamento de cartes de crdito. O nmero de carto fica criptografado e no pode ser visualizado por nenhum membro de nossa equipe.
3

Por medida de segurana preciso enviar os dados de cobrana do Portador, ou seja, o endereo onde o cliente do carto recebe a fatura. Os parmetros recebidos pelo comando add-card-onfile so: Nome merchantId (obrigatrio) merchantKey (obrigatrio) command (obrigatrio) customerId (obrigatrio) creditCardNumber (obrigatrio) expirationMonth Descrio ID de Loja que identifica o Estabelecimento Chave associada ao ID de Loja Comando a ser executado Para adicionar um carto ao cadastro: add-card-onfile ID nico do cadastro, retornado quando o cliente foi adicionado base Nmero do carto de crdito a ser salvo Ms de vencimento do carto com 2 dgitos

Mais informaes (ingls): http://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard

maxiPago! Smart Payments 2013

45

(obrigatrio) expirationYear (obrigatrio) billingName (obrigatrio) billingAddress1 (obrigatrio) billingAddress2 billingCity (obrigatrio) billingState (obrigatrio) billingZip (obrigatrio) billingCountry (obrigatrio) billingPhone (obrigatrio) billingEmail (obrigatrio) onFileEndDate Ano de vencimento do carto com 4 dgitos Nome do Portador do carto Obs: preciso informar o nome do Portador mesmo que o cliente j tenha cadastro pelo comando add-consumer. Endereo de cobrana para onde enviada a fatura do carto Complemento do endereo de cobrana Cidade UF da residncia do cliente 2 letras seguindo padro brasileiro. ZZ = Fora do Brasil. CEP sem trao Cdigo do pas com 2 letras (ISO 3166-2 ) Telefone de contato do Portador Com DDD, sem trao ou espao (Ex.: 2140099400) Endereo de email do Portador Data limite para manter o carto na base Formato MM/DD/AAAA Durao limite do uso do carto salvo ongoing = indefinidamente use_once = apenas uma vez aps a 1a. cobrana Comentrios adicionais sobre este carto Valor mximo que permitido cobrar deste carto Decimais separados por ponto ("."). Ex.: 100.00
4

onFilePermissions

onFileComment onFileMaxChargeAmount

O XML abaixo adiciona um carto ao cadastro do cliente criado anteriormente: <api-request> <verification>

Mais sobre o ISO 3166-2: http://pt.wikipedia.org/wiki/ISO_3166-2

maxiPago! Smart Payments 2013

46

<merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <command>add-card-onfile</command> <request> <customerId>999</customerId> <creditCardNumber>4111111111111111</creditCardNumber> <expirationMonth>12</expirationMonth> <expirationYear>2020</expirationYear> <billingName>Fulano de Tal</billingName> <billingAddress1>Av Republica do Chile, 230</billingAddress1> <billingAddress2>16. Andar</billingAddress2> <billingCity>Rio de Janeiro</billingCity> <billingState>RJ</billingState> <billingZip>20031170</billingZip> <billingCountry>BR</billingCountry> <billingPhone>2140099400</billingPhone> <billingEmail>fulano@exemplo.com</billingEmail> <onFileMaxChargeAmount>300.00</onFileMaxChargeAmount> </request> </api-request>

maxiPago! Smart Payments 2013

47

Remover um carto da base

O comando delete-card-onfile remove um carto salvo no cadastro do cliente. O cadastro em si continua ativo, pois a nica informao apagada o nmero do carto. Os parmetros aceitos pelo comando delete-card-onfile so: Nome merchantId (obrigatrio) merchantKey (obrigatrio) command (obrigatrio) customerId (obrigatrio) token (obrigatrio) Descrio ID de Loja que identifica o Estabelecimento Chave associada ao ID de Loja Comando a ser executado Para remover um carto do cadastro: delete-card-onfile ID nico do cadastro, retornado quando o cliente foi adicionado base Token nico associado ao carto

Este XML exemplo remove o carto salvo acima, bastando apenas trocar o token: <api-request> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <command>delete-card-onfile</command> <request> <customerId>999</customerId> <token>k11112233d</token> </request> </api-request>

maxiPago! Smart Payments 2013

48

Retorno do Cadastro
O retorno das requisies de cadastro contm a confirmao de que o comando foi executado com sucesso. Em alguns casos, como no comando add-customer, ele tambm traz de volta informaes que sero usadas para fazer referncia ao cadastro do cliente no futuro. Estas informaes so enviadas dentro do elemento <result/>. Os parmetros retornados pelas requisies de cadastro so: Nome errorCode errorMessage command time customerId Descrio Cdigo de retorno da operao. Sucesso = 0 Mensagem de erro, se houver Confirmao do comando enviado Data/hora da transao em formato epoch. Presente s no comando add-consumer. retornado o ID nico daquele cliente, dentro do elemento <result/>. muito importante guardar esta informao para futura referncia! Presente s no comando add-card-onfile. retornado o token nico daquele carto, dentro do elemento <result/>. muito importante guardar esta informao para futura referncia!

token

O XML de retorno segue esta estrutura: <api-response> <errorCode/> <errorMessage/> <command/> <time/> <result> </result> </api-response>

maxiPago! Smart Payments 2013

49

Transaes com token

Uma vez em posse do customerId e do token do carto possvel realizar autorizaes e vendas diretas sem a necessidade de pedir o nmero de carto ao cliente. A chamada muito similar s operaes de autorizao ou venda direta. Contudo, ao invs de se usar o elemento <creditCard/> deve-se usar o elemento <onFile/>, que aceita os seguintes parmetros: Nome customerId (obrigatrio) token (obrigatrio) Descrio ID nico do cadastro, retornado quando o cliente foi adicionado base Token nico associado ao carto

Este XML faz uma Venda Direta usando token e customerId fictcios: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <sale> <processorID>1</processorID> <referenceNum>987654321</referenceNum> <ipAddress>123.123.123.123</ipAddress> <transactionDetail> <payType> <onFile> <customerId>999</customerId> <token>k11112233d</token> </onFile> </payType> </transactionDetail> <payment> <currencyCode>BRL</currencyCode> <chargeTotal>7.00</chargeTotal> </payment> </sale> </order> </transaction-request>

maxiPago! Smart Payments 2013

50

Recorrncias com token

Durante a recorrncia o carto de crdito salvo automaticamente em nossa base. Porm se esse cliente j fez uma compra prvia no Estabelecimento e usou a opo quickPago! possvel usar no XML da Recorrncia o token previamente gerado ao invs do nmero do carto de crdito. Este XML cria uma recorrncia a partir de um token salvo anteriormente: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <recurringPayment> <processorID>1</processorID> <referenceNum>12304560</referenceNum> <ipAddress>123.123.123.123</ipAddress> <transactionDetail> <payType> <onFile> <customerId>999</customerId> <token>k11112233d</token> </onFile> </payType> </transactionDetail> <payment> <currencyCode>BRL</currencyCode> <chargeTotal>22.00</chargeTotal> </payment> <recurring> <action>new</action> <startDate>2020-12-25</startDate> <frequency>2</frequency> <period>monthly</period> <installments>5</installments> <failureThreshold>1</failureThreshold> </recurring> </recurringPayment> </order> </transaction-request>

maxiPago! Smart Payments 2013

51

Salvar o carto automaticamente

possvel tambm salvar o nmero de carto automaticamente durante uma operao de autorizao ou venda direta. Como um carto precisa sempre estar associado a um cadastro, preciso executar o comando addconsumer antes de se poder salvar o carto. Tambm preciso enviar os dados de cobrana (<billing/>), descritos anteriormente neste manual. Para indicar que deseja salvar o carto automaticamente preciso incluir, dentro do n da operao (<sale/> ou <auth/>), o elemento <saveOnFile/>, que aceita os seguintes parmetros: Nome customerToken (obrigatrio) onFileEndDate Descrio ID nico do cadastro, retornado quando o cliente foi adicionado base (customerId) Data limite para manter o carto na base Formato MM/DD/AAAA Durao limite do uso do carto salvo ongoing = indefinidamente use_once = apenas uma vez aps a 1a. cobrana Comentrios adicionais sobre este carto Valor mximo que permitido cobrar deste carto Decimais separados por ponto ("."). Ex.: 100.00

onFilePermission onFileComment onFileMaxChargeAmount

O XML abaixo passa uma Venda Direta e salva o carto de um cliente: <transaction-request> <version>3.1.1.15</version> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <order> <sale> <processorID>1</processorID> <referenceNum>3211230001</referenceNum> <billing> <name>Fulano de Tal</name> <address>Av. Repblica do Chile, 230</address>
maxiPago! Smart Payments 2013

52

<address2>16 Andar</address2> <city>Rio de Janeiro</city> <state>RJ</state> <postalcode>20031-170</postalcode> <country>BR</country> <phone>2140099400</phone> <email>fulanodetal@email.com</email> </billing> <transactionDetail> <payType> <creditCard> <number>4111111111111111</number> <expMonth>12</expMonth> <expYear>2020</expYear> <cvvNumber>999</cvvNumber> </creditCard> </payType> </transactionDetail> <payment> <currencyCode>BRL</currencyCode> <chargeTotal>33.00</chargeTotal> </payment> <saveOnFile> <customerToken>999</customerToken> <onFileEndDate>12/25/2020</onFileEndDate> </saveOnFile> </sale> </order> </transaction-request>

maxiPago! Smart Payments 2013

53

Requisio de Consulta
A API de consulta e relatrios permite que o Estabelecimento extraia do banco de dados da maxiPago! as informaes detalhadas de qualquer transao. permitido resgatar os detalhes de apenas uma transao ou receber uma relao de transaes, filtradas por perodo. O XML de resposta trar no mximo 100 transaes, a fim de no tornar a resposta muito pesada. Caso a lista de transaes filtradas seja maior, ser utilizado um mecanismo de paginao, detalhado mais abaixo. A estrutura do XML similar s requisies de Cadastro e possui <rapi-request/> como n-raz. O XML contm a verificao das credenciais no elemento <verification/>; a ao a ser executada na tag <command/>; e os dados para filtragem dentro do n <request/>. No h verso de API.

URL de Teste: https://testapi.maxipago.net/ReportsAPI/servlet/ReportsAPI

Os comandos disponveis so: transactionDetailReport: resgata todos os detalhes das transaes filtradas. checkRequestStatusCommand: verifica o resultado de uma pesquisa em massa.

A estrutura bsica do XML fica da seguinte forma: <rapi-request> <verification> <merchantId/> <merchantKey/> </verification> <command/> <request> </request> </rapi-request>

maxiPago! Smart Payments 2013

54

Consultar uma nica transao

A sondagem de uma nica transao permite verificar o seu status e resgatar os detalhes do pedido. Esta sonda necessria para confirmar os pagamentos de pedidos feitos com boletos, alm de verificar a situao de um estorno solicitado anteriormente. Para filtrar uma nica transao deve-se usar o elemento <filterOptions/>, dentro da tag <request/>: Nome merchantId (obrigatrio) merchantKey (obrigatrio) command (obrigatrio) transactionId (obrigatrio) Descrio ID de Loja que identifica o Estabelecimento Chave associada ao ID de Loja Comando a ser executado: transactionDetailReport ID da transao gerado pela maxiPago!

O XML abaixo busca uma transao especfica na base: <rapi-request> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <command>transactionDetailReport</command> <request> <filterOptions> <transactionId>32165498701</transactionId> </filterOptions> </request> </rapi-request>

maxiPago! Smart Payments 2013

55

Consultar uma lista de transaes

A maxiPago! recomenda que os Estabelecimentos mantenham em seu prprio banco de dados os detalhes das transaes. Entendemos que isto nem sempre possvel, e por esta razo permitimos a sondagem de transaes por perodo. A busca por transaes dentro de um perodo especialmente til para a produo de relatrios para plataformas onde no possvel manter um banco de dados local, como em um aplicativo para celular. Para filtrar transaes deve-se usar o elemento <filterOptions/>, dentro da tag <request/>: Nome merchantId (obrigatrio) merchantKey (obrigatrio) command (obrigatrio) Descrio ID de Loja que identifica o Estabelecimento Chave associada ao ID de Loja Comando a ser executado: transactionDetailReport Perodo de busca de das transaes. Pode ser um filtro prestabelecido ou um perodo especfico. period (obrigatrio) today = busca as transaes do dia de hoje yesterday = traz transaes do dia anterior (ontem) lastmonth = retorna as transaes do ms anterior thismonth = traz as transaes do ms atual (desde o dia 1o. at hoje) range = indica que ser escolhido um perodo especfico para busca Determina o nmero mximo de transaes em cada pgina. Mximo = 100 No caso de period = range, este campo estabelece o primeiro dia do perodo de busca das transaes Formato: mm/dd/aaaa No caso de period = range, este campo estabelece o ltimo dia do perodo de busca das transaes Formato: mm/dd/aaaa No caso de period = range, este campo inicial da busca Formato: hh:mm:ss (Exemplo: 00:00:00) estabelece a hora

pageSize

startDate

endDate

startTime

maxiPago! Smart Payments 2013

56

endTime

No caso de period = range, este campo estabelece a hora final da busca Formato: hh:mm:ss (Exemplo: 23:59:59) Determina o campo usado para ordenar a listagem das transaes. Exemplo: usar 'transactionAmount' para ordenar a partir do valor do pedido. transactionDate = Data do pedido transactionAmount = Valor do pedido transactionType = Tipo de operao transactionId = ID da Transao billingName = Nome de Cobrana, se disponvel orderId = ID do Pedido paymentType = Meio de Pagamento status = Status Determina se a listagem ser crescente ou decrescente. asc = Crescente desc = Decrescente Define a partir de qual transao do resultado total voc quer receber. Exemplo: se a busca gerou 100 resultados e voc quer ver apenas o terceiro quartil, ento "startRecordNumber=50" Nmero da ltima transao da busca. Exemplo: se a busca gerou 100 resultados e voc quer ver apenas o terceiro quartil, ento "endRecordNumber=75"

orderByName

orderByDirection

startRecordNumber

endRecordNumber

O XML abaixo busca transaes feitas entre 18/12/2010 e 31/12/2010, ordenando-as por data, comeando pelo pedido mais recente: <rapi-request> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <command>transactionDetailReport</command> <request> <filterOptions> <period>range</period> <pageSize>25</pageSize> <startDate>12/18/2010</startDate> <endDate>12/31/2010</endDate> <startTime>00:00:00</startTime> <endTime>23:59:59</endTime>
maxiPago! Smart Payments 2013

57

<orderByName>transactionDate</orderByName> <orderByDirection>desc</orderByDirection> </filterOptions> </request> </rapi-request>

maxiPago! Smart Payments 2013

58

Retorno da Consulta
O retorno da chamada de consulta trar todas as informaes da transao solicitada, ou uma lista de transaes. As informaes incluem dados como o status da transao, o valor do pedido, o ID do Pedido, ID da Transao e os cdigos de retorno da adquirente.

Na eventualidade de o servidor postergar a sondagem do perodo, voc receber um token nico que identifica aquela pesquisa. Guarde-o, pois ele ser usado na re-sondagem dos dados.

O XML de retorno est dividido em trs partes, <header/>, <resultSetInfo/> e <record/>: <rapi-response> <header> ... </header> <result> <resultSetInfo> <totalNumberOfRecords/> <pageToken/> <pageNumber/> </resultSetInfo> <records> <record> </record> <record> </record> </records> </result> </rapi-response>

O elemento <header/> contm as informaes da requisio de consulta, com os seguintes campos: Nome errorCode errorMsg command Descrio Cdigo de resposta da requisio. Sucesso = 0 Mensagem descritiva do erro (em ingls) Confirmao do comando enviado na requisio

maxiPago! Smart Payments 2013

59

time

Data e hora de gerao do relatrio no fuso PST. Formato mm/dd/aaaa hh:mm:ss

J o elemento <resultSetInfo/> traz o total de registros encontrados e os dados do sistema de paginao: Nome totalNumberOfRecords pageToken Descrio Quantidade total de transaes retornadas. Identificador de paginao desta resposta. Ele deve ser guardado para permitir a navegao nas pginas. S enviado caso haja mais de uma pgina Nmero da pgina retornada. S enviado caso haja mais de uma pgina.

pageNumber

O elemento <record/> contm os detalhes das transaes individuais. Nem todos os campos so sempre retornados: Nome approvalCode comments Descrio Cdigo de autorizao da Adquirente Comentrios inseridos na autorizao Bandeira de carto utilizada na transao VISA MASTERCARD AMEX DINERS DISCOVER ID nico do cadastro, se o cliente consta na base ID do Pedido gerado pela maxiPago! Carto de crdito (Bandeira + 4 ltimos dgitos) Exemplo: (Visa) ...1234 Nome da Adquirente/Banco que processou esta transao Flag de pagamento recorrente. Recorrente = 1 Identificador do pedido no Estabelecimento

creditCardType

customerId orderId paymentType processorID recurringPaymentFlag referenceNumber

maxiPago! Smart Payments 2013

60

responseCode

Cdigo de resposta da transao 0 = Aprovada 1 = Negada 2 = Negada por Fraude 5 = Reviso de Fraude 1022 = Erro na operadora de carto 2048 = Erro interno na maxiPago! Valor do pedido, em centavos (R$1,00 = 100) ID da transao gerado pela maxiPago! Status da transao ORIGINAL. altamente recomendado usar o campo transactionState para determinar a situao da transao. Status ATUAL da transao 1 - Em andamento 3 - Capturada 4 - Pendente de captura 5 - Pendente de autorizao 6 - Autorizada 7 - Negada 8 - Revertida 9 - Cancelada (Voided) 10 - Paga 12 - Pendente de Reviso (verificar com Suporte) 13 - Pendente de Reverso 14 - Pendente de Captura (retentativa) 16 - Pendente de Estorno 18 - Pendente de Void 19 - Pendente de Void (retentativa) 22 - Boleto Emitido 29 - Pendente de Autenticao 30 - Autenticada 31 - Pendente de Estorno (retentativa) 32 - Autenticao em andamento 33 - Autenticao enviada 34 - Boleto Visualizado 35 - Boleto Pago A Menor 36 - Boleto Page A Maior 38 - Pendente de envio de arquivo de Estorno 44 Aprovada na Fraude 45 Negada por Fraude 46 Reviso de Fraude

transactionAmount transactionId

transactionStatus

transactionState

maxiPago! Smart Payments 2013

61

transactionType

Operao realizada Auth = Autorizao Capture = Capturea Sale = Venda Direta Return = Estorno Void = Void (Cancelamento) Boleto Payment = Boleto Data da transao em fuso PST5. Formato MM/DD/AAAA hh:mm:ss tt Resposta do AVS, se disponvel Dados de cobrana, se foi enviado Dados de cobrana Dados de cobrana Dados de cobrana Dados de cobrana Dados de cobrana Dados de cobrana Dados de cobrana Dados de cobrana Nmero identificador do boleto ("Nosso Nmero") Data de vencimento do boleto. Formato MM/DD/AAAA Data de pagamento do boleto, se o banco a informou Formato MM/DD/AAAA

transactionDate avsResponseCode billingAddress1 billingAddress2 billingCity billingCountry billingEmail billingName billingPhone billingState billingZip boletoNumber expirationDate dateOfPayment

Fuso horrio PST ou UTC-8: http://pt.wikipedia.org/wiki/UTC-8.

maxiPago! Smart Payments 2013

62

dateOfFunding bankOfPayment branchOfPayment paidAmount bankFee netAmount returnCode clearingCode

Data de liquidao do valor, se o banco a informou Formato MM/DD/AAAA Cdigo FEBRABAN do banco onde foi feito o pagamento Agncia onde foi feito o pagamento Valor pago pelo cliente Taxa de cobrana do boleto, se o banco a informou Valor lquido a receber (valor pago - taxa) Cdigo de pagamento do boleto no banco Apenas para referncia Cdigo de liquidao do banco, se informado Apenas para referncia

maxiPago! Smart Payments 2013

63

Utilizando o sistema de paginao

Ao puxar um relatrio filtrado por perodo voc provavelmente ir receber um nmero considervel de transaes. Para evitar problemas de performance temos um sistema de paginao de resultados, que divide o nmero total de transaes em vrias pginas. preciso puxar as demais pginas para obter todos os resultados. O XML abaixo mostra um exemplo de resposta com 350 transaes: <rapi-response> <header> ... </header> <result> <resultSetInfo> <totalNumberOfRecords>350</totalNumberOfRecords> <pageToken>xyz35Hiua834</pageToken> <pageNumber>1</pageNumber> </resultSetInfo> <records> <record> <record> </records> </result> </rapi-response>

Para poder reaver os dados das demais pginas preciso executar o comando transactionDetailReport novamente, passando outros parmetros no elemento <filterOptions/>: Nome pageToken pageNumber Descrio Identificador de paginao da resposta a ser sondada. Nmero da pgina que se quer obter o resultado

O XML de requisio para a sondagem da 3a. pgina de uma busca fica, ento, desta forma: <rapi-request>
maxiPago! Smart Payments 2013

64

<verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <command>transactionDetailReport</command> <request> <filterOptions> <pageToken>xyz35Hiua834</pageToken> <pageNumber>3</pageNumber> </filterOptions> </request> </rapi-request>

maxiPago! Smart Payments 2013

65

Consultas em massa
Dependendo da quantidade de registros solicitados a maxiPago! poder aguardar um perodo de menor pico no servidor para executar a busca. Isto quer dizer que, nestes raros casos, o Estabelecimento dever sondar novamente nossos servidores para verificar que a busca foi completada. Nestes casos, a resposta da solicitao de envio de relatrio diferente. Os campos recebidos so: Nome errorCode errorMsg command time Descrio Cdigo de retorno da requisio. Sucesso = 0 Mensagem descritiva do erro, se houver Confirmao do comando enviado na requisio Data e hora do recebimento da requisio Formato MM/DD/AAAA hh:mm:ss Token da requisio, usado para verificar se o relatrio j est pronto. Deve-se salvar este token para fazer uma nova sondagem

requestToken

O XML abaixo mostra um exemplo de uma resposta para estes casos: <rapi-response> <header> <errorCode>0</errorCode> <errorMsg/> <command>transactionDetailReport</command> <time>12-01-2011 11:27:54</time> </header> <result> <requestToken>8cIjsO7cmeY=</requestToken> </result> </rapi-response>

maxiPago! Smart Payments 2013

66

Sondando o resultado de uma busca em massa

O Estabelecimento poder posteriormente sondar a maxiPago! para ver se o relatrio foi finalizado. Para isto preciso executar o comando checkRequestStatus, cujo nico campo aceito o <requestToken>: <rapi-request> <verification> <merchantId>100</merchantId> <merchantKey>secret-key</merchantKey> </verification> <command>checkRequestStatus</command> <request> <requestToken>fSawEgQqNqg=</requestToken> </request> </rapi-request>

A resposta informar se o relatrio foi finalizado ou se ainda est sendo processado pelo sistema. Os campos retornados pelo comando checkRequestStatus so: Nome errorCode errorMsg command time Descrio Cdigo de resposta da requisio. Sucesso = 0 Mensagem descritiva do erro, se houver Confirmao do comando enviado na requisio. Data e hora de recebimento da requisio Formato MM/DD/AAAA hh:mm:ss Mensagem de indicao do status do relatrio. REQUESTPROCESSED = Processado com sucesso REQUESTNOTPROCESSED = Gerao no finalizada REQUESTNOTFOUND = O pedido de gerao de relatrio no foi encontrado Quantidade total de transaes retornadas. Identificador de paginao desta resposta. Ele deve ser guardado para permitir a navegao nas pginas. Este valor ser retornado inclusive para relatrios que possuam apenas uma pgina Data e hora de gerao do relatrio.

statusMessage

totalNumberOfRecords

pageToken

processedTime

maxiPago! Smart Payments 2013

67

Um exemplo do XML enviado na resposta : <rapi-response> <header> <errorCode>0</errorCode> <errorMsg/> <command>checkRequestStatusCommand</command> <time>03-24-2011 15:45:42</time> </header> <result> <statusMessage>REQUESTPROCESSED</statusMessage> <resultSetInfo> <totalNumberOfRecords>150</totalNumberOfRecords> <pageToken>temp1300919096768.1</pageToken> <processedTime>03-23-201115:24:56</processedTime> </resultSetInfo> </result> </rapi-response>

maxiPago! Smart Payments 2013

68

smartPage! - Integrao por HTTPS Post

A maxiPago! oferece um ambiente seguro para a digitao e armazenamento dos dados do carto do comprador. Isto tira do Estabelecimento a necessidade de possuir certificado de segurana SSL, pois a maxiPago! fica responsvel pelo tratamento das informaes sigilosas. Para utilizar a smartPage! preciso redirecionar o comprador para o ambiente seguro da maxiPago!, postando os dados do pedido. O cliente entrar em nosso ambiente, customizado com o logotipo do Estabelecimento e protegido por um certificado de segurana SSL. Ao finalizar o pedido a maxiPago! ir redirecionar o comprador de volta para o site do Estabelecimento. O endereo para onde o comprador ser redirecionado depender do resultado da transao. Se o pedido for aprovado a maxiPago! o enviar para a URL de Sucesso do Estabelecimento, mas se o pedido for negado postaremos para a URL de Erro.

ATENO Para que possamos habilitar esse servio preciso que voc envie para a nossa equipe de Suporte as seguintes informaes: * URL de Sucesso, para onde o comprador ser redirecionado se a compra for Aprovada * URL de Erro, para onde o comprador ser redirecionado se a compra for Negada * URL de Envio, de onde o comprador ser redirecionado a partir do seu site (REFERER). * Logotipo da loja, para ser mostrado na pgina, com resoluo recomendada de 300x80.

maxiPago! Smart Payments 2013

69

Envio da transao
O envio da transao pode ser feito atravs de um simples Post HTML. Recomendamos fazer um redirecionamento para a URL da maxiPago! evitando os pop-ups ou qualquer tipo de frame.

URL de Teste: https://testsecure.maxipago.net/hostpay/HostPay

Os campos recebidos pela smartPage! so: Nome hp_merchant_id (obrigatrio) Descrio ID de Loja fornecido pela maxiPago! Cdigo da Adquirente que ir processar esta transao SIMULADOR DE TESTES = 1 Redecard = 2 Amex = 3 Cielo = 4 Chase Paymentech = 8 Meio de pagamento usado. Sempre ser ccard. Tipo de requisio a ser realizada auth = Autorizao sale = Venda Direta Cdigo da moeda utilizada na transao de acordo com a norma ISO 4217. Lista completa de moedas: anexo B. Valor do pedido. Os decimais devem ser separados por vrgula (","). Ex.: 10,00 Nmero de parcelas de transao Se for vista, no enviar Tipo de parcelamento (com ou sem juros) N = Sem juros (parcelamento Loja) Y = Com juros (parcelamento Carto) Se for vista, no enviar Identificador do pedido no Estabelecimento

hp_processor_id (obrigatrio)

hp_method (obrigatrio) hp_txntype (obrigatrio)

hp_currency

hp_amount (obrigatrio)

hp_number_of_installments

hp_charge_interest

hp_refnum
maxiPago! Smart Payments 2013

70

(obrigatrio) hp_sig_itemid (obrigatrio) hp_sig_timestamp (obrigatrio) hp_sig_id (obrigatrio) hp_signature (obrigatrio) hp_bname (obrigatrio) hp_baddr hp_baddr2 hp_bcity

Este valor deve ser nico Cdigo do pedido usado na assinatura de validao Deve-se usar um valor diferente ao enviado em "hp_refnum". Data/hora da transao em formato epoch , usado na assinatura de validao Valor aleatrio de 4 dgitos, usado na assinatura de validao Assinatura de validao da transao. 7 Chave HMAC-MD5 de validao, detalhada mais abaixo. Nome do portador do carto Endereo do cliente Complemento o endereo Cidade do cliente UF da residncia do cliente 2 letras seguindo padro brasileiro. ZZ = Fora do Brasil. CEP do cliente Pas do cliente (ISO 3166-2) Telefone do cliente Email do cliente Idioma da tela de pagamentos pt = Portugus (padro) en = Ingls es = Espanhol Estes campos devolvero qualquer valor enviado e
6

hp_bstate

hp_bzip hp_bcountry hp_phone hp_email

hp_lang

hp_cf_1

6 7

Mais informaes sobre o formato epoch (ou Unix time): http://pt.wikipedia.org/wiki/Era_Unix Mais informaes sobre a funo HMAC (em ingls): http://en.wikipedia.org/wiki/HMAC

maxiPago! Smart Payments 2013

71

hp_cf_2 hp_cf_3 hp_cf_4 hp_cf_5

podem ser usados como eco, guardando a sesso do cliente ou qualquer outro identificador. possvel tambm mostrar o valor enviado na pgina de pagamento, permitindo a insero de textos e instrues para o comprador. Caso faa a utilizao desta funcionalidade preciso enviar todos os 5 campos, mesmo que vazios.

Abaixo temos um exemplo do formulrio HTML enviado para uma transao: <form method="POST" action="https://testsecure.maxipago.net/hostpay/HostPay"> <input name="hp_merchant_id" value="100"> <input name="hp_processor_id" value="1"> <input name="hp_method" value="ccard"> <input name="hp_txntype" value="sale"> <input name="hp_currency" value="BRL"> <input name="hp_amount" value="15,00"> <input name="hp_number_of_installments" value="2"> <input name="hp_charge_interest" value="N"> <input name="hp_refnum" value="ORD1325248408"> <input name="hp_sig_itemid" value="123123"> <input name="hp_sig_timestamp" value="1325248408"> <input name="hp_sig_id" value="5038"> <input name="hp_signature" value="799074cdb40ce532ed97bf11a9e7963f"> <input name="hp_bname" value="Fulano de Tal"> <input name="hp_baddr" value="Av. Repblica do Chile, 230"> <input name="hp_bcity" value="Rio de Janeiro"> <input name="hp_bstate" value="RJ"> <input name="hp_bcountry" value="BR"> <input name="hp_lang" value="pt"> <input name="submit" type="submit" value="Finalizar pedido"> </form>

maxiPago! Smart Payments 2013

72

Salvar o carto automaticamente

possvel combinar o uso da smartPage! com o sistema de armazenamento de cartes. O comprador digita os dados do seu carto no ambiente da maxiPago! e o Estabelecimento recebe de volta o status da transao e o token do carto do comprador. Desta forma possvel utilizar a plataforma quickPago! sem que o Estabelecimento veja o nmero de carto. Para salvar um carto automaticamente preciso enviar, alm dos dados da transao, as informaes do cliente. Se j houver um perfil de cliente criado preciso enviar tambm o seu ID, gerado pela maxiPago!.

Os campos abaixo devem ser enviados juntamente com os dados da transao: Nome hp_c_firstname (obrigatrio) hp_c_lastname (obrigatrio) hp_savepayment (obrigatrio) hp_customer_token (obrigatrio*) hp_save_customer (obrigatrio*) hp_c_customer_id (obrigatrio*) hp_c_addr hp_c_addr2 hp_c_city hp_c_state hp_c_zip hp_c_country hp_c_phone hp_c_email Nome do portador do carto Sobrenome do portador do carto Flag para salvar o carto 1 = Salvar ID do perfil do cliente gerado pela maxiPago!. * Somente ao salvar o carto sob um perfil j existente Flag para salvar o perfil do cliente 1 = Salvar * Somente ao criar o perfil do cliente Nmero de referncia do cadastro para o lojista. * Somente ao criar o perfil do cliente Endereo de cobrana Complemento do endereo Cidade UF do cliente 2 letras seguindo padro brasileiro. ZZ = Fora do Brasil. CEP Pas do cliente (ISO 3166-2) Telefone Endereo de email Descrio

maxiPago! Smart Payments 2013

73

Resultado da transao
O comprador pode retornar ao site do Estabelecimento atravs de duas URLs, a de Sucesso ou de Erro. O cliente ser redirecionado para a URL de Sucesso quando a transao for aprovada pela processadora de carto. Por outro lado, se o pedido for negado enviaremos o cliente para a URL de Erro, avisando de algum problema na transao. Estas duas URLs devem ser hospedadas pelo Estabelecimento e seus endereos devem ser informados nossa equipe de Suporte durante o processo de integrao. O Estabelecimento tem a opo receber os dados da transao -- como cdigo de autorizao, mensagem da operadora e ID do pedido -- no momento em que o comprador volta para o ambiente da loja. Neste caso a maxiPago! ir postar estes dados junto com o redirecionamento do navegador. Contudo, esta funcionalidade s est disponvel para Estabelecimentos com certificado de segurana SSL.

Por que apenas Estabelecimentos com certificado SSL podem receber os dados via Post? Os navegadores modernos possuem uma srie de medidas para garantir a segurana do usurio. Uma delas, mostrada abaixo, avisa que o usurio est saindo de um ambiente seguro (HTTPS) para um ambiente no-seguro (HTTP), e que qualquer informao postada pode ficar visvel, j que a comunicao no est criptografada.

Um comprador que v esta mensagem pode ficar inseguro. Logo, para evitar problemas, recomendamos postar os dados da transao para uma URL hospedada em um ambiente HTTPS. Caso seu site no possua certificado de segurana possvel obter os dados da transao atravs do Portal maxiPago! ou da requisio de consulta, detalhada neste manual.

maxiPago! Smart Payments 2013

74

Os dados retornados tanto para a URL de Sucesso como para a URL de Erro so: Nome hp_time hp_responsecode hp_responsemsg hp_refnum hp_transid hp_avsresponse hp_authcode hp_orderid Descrio Data e hora da transao Indicador do status da transao. Sucesso = 0 Mensagem descritiva da resposta Confirmao do cdigo enviado ID da transao, gerado pela maxiPago!. Salve este campo para futuras referncias. Resposta da verificao AVS (somente nos EUA) Cdigo de autorizao retornado pela adquirente Valor nico associado ao pedido pela maxiPago!. Salve este campo para futuras referncias/ Cdigo da moeda utilizada na transao de acordo com a norma ISO 4217. Lista completa de moedas: anexo B. Confirmao do valor enviado ID da transao na Adquirente. Cielo: TID Redecard: NSU Nmero de referncia da Adquirente Cielo: NSU Redecard: Comprovante de Venda (CV) Valor de score retornado pelo fraudControl! Quanto menor o valor menor o risco da transao Assinatura de validao da transao Chave HMAC-MD5 de validao, detalhada abaixo. Presente s quando um cadastro de cliente criado, traz o ID do perfil do cliente. muito importante guardar esta informao para futura referncia! Presente s quando um carto salvo automaticamente, traz o token nico daquele carto. muito importante guardar esta informao para

hp_currency

hp_amount hp_processortxnid

hp_processorrefno

hp_fraud_score hp_signature_response

hp_customer_token

hp_payment_token

maxiPago! Smart Payments 2013

75

futura referncia! hp_save_payment_responsemsg Presente s quando um carto salvo automaticamente, traz o resultado da operao

maxiPago! Smart Payments 2013

76

Assinatura de validao do Post

Para garantir a segurana da transao e a integridade dos dados postados a maxiPago! utiliza uma assinatura nica por pedido, que valida se os dados do Post so originais ou se foram alterados por algum. A assinatura montada utilizando a funo HMAC-MD5 , que recebe dados do pedido concatenados e uma chave secreta, fornecida ao Estabelecimento durante o processo de integrao. A maxiPago! utilizar a assinatura para validar os dados recebidos e checar se a requisio legtima. O Estabelecimento tambm dever checar a assinatura no Post de retorno, verificando que a resposta veio realmente do nosso sistema. Os dados do pedido devem estar concatenados em uma ordem especfica e separados por um asterisco, conforme mostra a tabela abaixo. A chave secreta, por sua vez, utilizada na funo hash e no includa nos dados concatenados.
8

Requisio

Dados: hp_sig_timestamp*hp_sig_id*hp_amount*hp_sig_itemid Exemplo: 1325248408*5038*15,00*123123 Assinatura: 799074cdb40ce532ed97bf11a9e7963f Dados: hp_refnum*hp_amount*hp_responsemsg Exemplo: ORD1325248408*15,00*APPROVED Assinatura: d79ab630fe050b1ef9c4f8ccc5e18ad5 A chave secreta utilizada nos exemplos acima jM13K8hdbWi2V9ab
9

Retorno

Chave secreta

A seo de referncias do artigo da Wikipdia sobre HMAC possui exemplos de implementao em diferentes linguagens de programao.

8 9

Mais informaes sobre a funo HMAC (em ingls): http://en.wikipedia.org/wiki/HMAC Exemplos de implementao da HMAC-MD5: http://en.wikipedia.org/wiki/HMAC#External_links

maxiPago! Smart Payments 2013

77

Suporte integrao
O suporte aos desenvolvedores feito exclusivamente atravs do nosso Portal de Suporte. Os dados de acesso so enviados para os nossos clientes a partir do email suporte@maxipago.com com o assunto "maxiPago! email de boas-vindas" para o email usado no credenciamento.

A equipe de suporte da maxiPago! pode lhe ajudar com a integrao do seu sistema. Atualmente temos bibliotecas de integrao em PHP, Java e .NET. Suporte ao Cliente maxiPago! Portal de Suporte: http://suporte.maxipago.com Email: suporte@maxipago.com

maxiPago! Smart Payments 2013

78

Anexo A Fluxos de Transaes

Este anexo contm os fluxos de transaes (diagramas de sequncia) da maioria das operaes descritas neste manual. Estes so os fluxos mais comuns adotados na integrao com a maxiPago!.

Autorizao e Captura Pedido em duas etapas

maxiPago! Smart Payments 2013

79

Venda Direta Resposta imediata ao comprador

Venda Direta Resposta assncrona

maxiPago! Smart Payments 2013

80

Emisso e pagamento de Boleto

maxiPago! Smart Payments 2013

81

Estorno Adquirente com resposta online

Estorno Adquirente com resposta offline

maxiPago! Smart Payments 2013

82

Salvar carto automaticamente

maxiPago! Smart Payments 2013

83

smartPage Integrao via HTTPS POST

maxiPago! Smart Payments 2013

84

Anexo B Moedas
Este anexo possui a listagem das moedas apresentadas no ISO 4217 e que so aceitas em nosso sistema. Cdigo Moeda Cdigo Moeda

AED AMD ANG ARS AUD AWG BBD BDT BGN BIF BMD BND BOB BRL BSD BWP BYR BZD CAD CHF CLP CNY COP CRC CVE CZK DJF DKK DOP DZD EGP

Dirham dos Emirados Dram armnio Florim holands Peso Argentino Dlar australiano Florim de Aruba Dlar de Barbados Taka de Bangladesh Lev blgaro Franco do Burundi Dlar de Bermuda Dlar do Brunei Boliviano Real Dlar das Bahamas Pula da Botswana Rublo bielorrusso Dlar do Belize Dlar canadense Franco suo Peso chileno Yuan chins Peso colombiano Colon da Costa Rica Escudo cabo-verdiano Coroa checa Franco do Djibuti Coroa dinamarquesa Peso dominicano Dinar argelino Libra egpcia

LBP LKR LTL LVL MAD MDL MNT MOP MRO MUR MVR MWK MXN MYR NAD NGN NIO NOK NPR NZD PAB PEN PGK PHP PKR PLN PYG QAR RUB RWF SAR

Libra libanesa Rupia do Sri Lanka Litas da Litunia Lats do Leto Dirham marroquino Leu da Moldvia Tugrik da Monglia Pataca macauense Ouguiya da Mauritnia. Rupia da Maurcia Rufiyaa maldvia Kwacha malauiano Peso Mexicano Ringgit malsio Dlar da Nambia Naira da Nigria Cordoba Oro Coroa norueguesa Rupia nepalesa Dlar da Nova Zelndia Balboa moeda Nuevo Sol peruano Kina da Nova Guin Peso filipino Rupia paquistanesa Zloty polaco Guarani paraguaio Rial do Qatar Rublo russo Franco do Ruanda Riyal saudita
85

maxiPago! Smart Payments 2013

ETB EUR FJD FKP GBP GEL GIP GMD GNF GTQ GYD HKD HNL HTG HUF IDR ILS INR ISK JMD JPY KES KGS KHR KMF KRW KYD KZT LAK

Birr etope Euro Dlar das Fiji Libra das Malvinas Libra Esterlina Lari (moeda) Libra de Gibraltar Dalasi gambiano Franco da Guin Quetzal guatemalteco Dlar da Guiana Dlar de Hong Kong Lempira de Honduras Gourde haitiano Forint hngaro Rupia indonsia Shekel israelita Rupia indiana Krona islandesa Dlar jamaicano Iene japons Xelim queniano Som do Quirguisto Riel do Camboja Franco das Comoros Won sul coreano Dlar das Ilhas Caim Tenge do Cazaquisto Kip do Laos

SBD SCR SEK SGD SHP SLL SOS STD SZL THB TOP TRY TTD TWD TZS UAH UGX USD UYU UZS VND VUV WST XAF XCD XOF XPF YER ZAR ZMK

Dlar das Ilhas Salomo Rupia das Seychelles Coroa Sueca Dlar de Cingapura Libra de Santa Helena Leone de Serra Leoa Xelim somali Dobra de So Tom e Prncipe Lilangeni Baht tailands Pa'anga tongans Nova Lira turca Dlar de Trindade e Tobago Novo Dlar de Taiwan Xelim da Tanznia Hryvnia ucraniano Xelim do Uganda Dlar Americano Peso Uruguaio Som Uzbeque Dong vietnamita Vatu de Vanuatu Tala de Samoa Franco CFA BEAC Dlar das Carabas Orientais Franco CFA BCEAO Franco CFP Rial do Imene Rand Sul-africano Kwacha da Zmbia

maxiPago! Smart Payments 2013

86