ESPECIFICAÇÃO TÉCNICA CIELO MOBILE CAIXA RÁPIDO Julho de 2015 Fevereiro, 2015
Í N D I C E VERSÃO DO DOCUMENTO... 7 INTRODUÇÃO... 7 OBJETIVO... 7 CENÁRIO... 7 FUNCIONAMENTO... 7 INTEGRAÇÃO... 8 MENSAGENS... 9 PAGAMENTO... 9 URL... 9 Parâmetros... 9 Detalhamento parâmetro MENSAGEM... 10 Método de envio... 10 Android... 10 IOS... 10 Diagrama de sequência pagamento com sucesso... 11 Fluxo de exceção 1 transação aprovada já realizada... 11 Diagrama de sequência Re-tentativa de pagto. aprovado... 12 Fluxo de exceção 2 Transação negada... 12 3
Fluxo de exceção 3 Cielo Mobile bloqueado ou em estado de Terminal Inoperante... 12 RESPOSTA DO PAGAMENTO... 13 URL... 13 Parâmetros... 13 Detalhamento parâmetro MENSAGEM... 14 Método de recebimento... 15 Android... 15 IOS... 15 CANCELAMENTO... 16 URL... 16 Parâmetros... 16 Detalhamento parâmetro MENSAGEM... 17 Método de envio... 17 Android... 17 IOS... 17 Diagrama de sequência Cancelamento com sucesso... 18 Fluxo de exceção Cancelamento já realizado... 19 RESPOSTA DO CANCELAMENTO... 19 URL... 19 Parâmetros... 19 Detalhamento parâmetro MENSAGEM... 20 Método de recebimento... 21 Android... 21 4
IOS... 22 HISTÓRICO... 22 URL... 22 Parâmetros... 22 RETORNO HISTÓRICO... 22 URL... 22 Parâmetros... 22 Detalhamento parâmetro MENSAGEM... 23 Método de recebimento... 23 Android... 23 IOS... 23 CONSULTAR TRANSAÇÃO... 23 URL... 23 Parâmetros... 24 Detalhamento parâmetro MENSAGEM... 24 Método de envio... 24 Android... 24 IOS... 24 RESPOSTA DA CONSULTA... 25 URL... 25 Parâmetros... 25 Detalhamento parâmetro MENSAGEM... 26 Método de recebimento... 27 Android... 27 5
IOS... 28 EXPORTAÇÃO DE HISTÓRICO... 28 URL... 28 Parâmetros... 28 Detalhamento parâmetro MENSAGEM... 28 Método de envio... 28 Android... 28 IOS... 29 RESPOSTA DA EXPORTAÇÃO DO HISTÓRICO... 29 URL... 29 Parâmetros... 29 Detalhamento parâmetro MENSAGEM... 30 Método de recebimento... 31 Android... 31 IOS... 31 EXEMPLO DE IMPLEMENTAÇÃO DE CLIENTE IOS... 31 Envio IOS (Pagamento)... 31 Recebimento IOS (Pagamento)... 32 Validação IOS... 32 PList Cadastro URL CallBack... 32 EXEMPLO DE IMPLEMENTAÇÃO DE CLIENTE ANDROID... 33 Envio (Pagamento)... 33 Recebimento (Pagamento)... 33 Validação... 33 6
Dados de Retorno ActivityResult... 34 Android Manifest... 34 DADOS DE RETORNO... 35 Fluxo... 35 Tipo de captura... 36 Códigos de Resposta... 36 Retorno da Aplicação... 36 ORIENTAÇÕES FINAIS... 37 7
V E R S Ã O D O D O C U M E N T O Essa é a versão 1.11 do manual de integração, de Junho de 2015, contemplando as alterações abaixo: Inclusão do retorno do nome da bandeira, nome do produto primário e nome do produto secundário no retorno do pagamento, cancelamento e consulta. INTRODUÇÃO Para iniciar o desenvolvimento de integração ao Cielo Mobile, favor enviar e-mail para integracaocielomobile@cielo.com.br para receber os dados necessários para desbloqueio do aplicativo e configuração ao ambiente de certificação. Importante destacar que os dados enviados funcionarão apenas no ambiente de teste até a conclusão do desenvolvimento. O ambiente de certificação é disponibilizado para você efetuar os testes de integração entre o seu aplicativo e o Cielo Mobile. O seu estabelecimento comercial em produção pode não possuir todos os serviços financeiros disponíveis no ambiente de certificação. Em casos de dúvidas durante o período de Integração ao Cielo Mobile, favor direcionálas ao e-mail integracaocielomobile@cielo.com.br, com o seguinte conteúdo: - Número Lógico de teste. - Número do Estabelecimento. - Dúvida ou Evidência de erro encontrado, caso houver. OBJETIVO Permitir que aplicações de terceiros realizem um pagamento utilizando o aplicativo Cielo mobile. CENÁRIO Ao final de uma venda utilizando um aplicativo móvel, o vendedor seleciona a opção de pagamento com Cielo Mobile. A aplicação móvel de venda abre o aplicativo Cielo Mobile com o valor da venda já informado. FUNCIONAMENTO 8
O aplicativo Cielo Mobile é iniciado após a escolha do tipo de venda (crédito, débito, crediário ou refeição) e segue o fluxo normal com exceção de alguns parâmetros, como por exemplo, o valor que já estará preenchido. Finalizando o processo, o Cielo Mobile retornará ao aplicativo original, informando o resultado da transação. INTEGRAÇÃO Haverá mudança de contexto e a aplicação que irá para foreground será a do Cielo mobile. Para as interfaces de Consulta e Exportação o retorno é feito para a aplicação cliente sem a interação do usuário com o Cielo Mobile; Transações realizadas no modelo de Caixa Rápido serão identificadas como tal no histórico; A comunicação com o Cielo Mobile é feita em duas pernas: pagamento e resposta do pagamento; A comunicação com o Cielo Mobile é assíncrona, a aplicação de venda faz uma chamada ao Cielo Mobile e informa uma URL de retorno; Se a aplicação de venda não receber uma resposta deve repetir a transação com os mesmos dados informados anteriormente. A aplicação Cielo Mobile verificará se o pagamento já foi realizado e não repetirá a transação retornando à aplicação de venda os dados do resultado do pagamento já realizado (apenas para transações autorizadas); Outra opção é a aplicação de venda realizar uma consulta para verificar o status da venda. Se for aprovada, o Cielo Mobile retornará os dados da venda. Caso contrário, informará que a venda não foi encontrada; A cada transação (pagamento ou cancelamento) a aplicação de venda deve enviar um novo identificador de transação (idtransacao). 9
MENSAGENS Os parâmetros identificados na coluna forma de envio como GET devem ser enviados junto à URL e codificados para serem usados como tal (URL Encode); Os parâmetros identificados na coluna forma de envio como EXTRA devem ser enviados no formato JSON, conforme exemplificado abaixo, como um EXTRA da Intent, cuja chave (KEY) deve ser a string definida como nome do parâmetro. PAGAMENTO Mensagem utilizada para iniciar uma transação de pagamento no aplicativo Cielo Mobile. O aplicativo é iniciado da mesma forma que ocorre no Cielo Mobile quando a opção Cartão é selecionada na tela principal. URL cielomobile://pagar PARÂMETROS Parâmetro Descrição Exemplo urlcallback Endereço de callback para a aplicação de venda. urlcallback=appcliente://retornopagamento MENSAGEM Objeto JSON { "idtransacao":"1", "valor":"200", estvenda":"0010000244470001", nomeaplicacao":"aplicação de Venda", referencia":"venda 123" tipoprodutoadministrativo":"false", email : cliente@email.com.br 10
} Detalhamento parâmetro MENSAGEM Parâmetro Descrição Exemplo idtransacao Id da transação na aplicação de venda. Deve ser único por transação. 100 valor Valor da transação sem o separador da casa decimal. 200 para o valor 2,00. estvenda Estabelecimento para Venda 0010000244470001 nomeaplicacao Nome da aplicação que está integrando com o Cielo Mobile Aplicação de Venda referencia Referência do pagamento que está sendo enviado Venda 100 tipoprodutoadministrativo Se deve exibir somente os produtos do tipo administrativo. False email E-mail do portador do cartão que receberá o comprovante da transação. cliente@email.com.br MÉTODO DE ENVIO Android Parâmetro Método urlcallback GET MENSAGEM Extra Exemplo: cielomobile://pagar?urlcallback=appcliente://retornopagamento 11
IOS Parâmetro Método urlcallback GET MENSAGEM GET Exemplo: cielomobile://pagar?urlcallback=appcliente://retornopagamento&mensage m=%7b%22datatransacao%22:%22141208104222%22,%22valor%22: %221200%22,%22idTransacao%22:%22123412%22,%22referencia%22: %22refer%C3%AAncia%22,%22tipoTransacao%22:1,%22nomeAplicacao %22:%22aplicado%20cliente%22,%22estVenda%22:%22000000000000 000004%22%7D,%22email%22%3A%22cliente%40email.com.br%22 DIAGRAMA DE SEQUÊNCIA PAGAMENTO COM SUCESSO 12
FLUXO DE EXCEÇÃO 1 TRANSAÇÃO APROVADA JÁ REALIZADA Se a aplicação de venda não receber uma resposta, ela pode repetir a transação utilizando o mesmo ID. O Cielo Mobile verificará se a transação já foi realizada e caso já tenha sido, não repetirá a mesma e retornará os dados da transação para a aplicação de venda. Deste modo o aplicativo pode realizar a chamada de pagamento ao Cielo Mobile múltiplas vezes sem duplicar a transação. DIAGRAMA DE SEQÜÊNCIA RE-TENTATIVA DE PAGAMENTO APROVADO 13
FLUXO DE EXCEÇÃO 2 TRANSAÇÃO NEGADA Se o pagamento for negado ou se a aplicação de venda não receber uma resposta, ela pode repetir a transação utilizando o mesmo ID. Nesse caso, o Cielo Mobile não guardará as informações dessa transação e por isso iniciará um novo fluxo de pagamento. FLUXO DE EXCEÇÃO 3 - CIELO MOBILE BLOQUEADO OU EM ESTADO DE TERMINAL INOPERANTE Quando o aplicativo está bloqueado ou em estado de terminal inoperante, o Cielo Mobile retorna à aplicação de venda informando o erro na mensagem de Resposta do Pagamento. RESPOSTA DO PAGAMENTO Quando um pagamento é finalizado, o Cielo Mobile retorna o fluxo para a aplicação de venda com o resultado do pagamento. O endereço de retorno será o informado no parâmetro urlcallback da mensagem de pagamento, e ele deverá ser capaz de receber os parâmetros abaixo. 14
URL A URL é definida na aplicação do parceiro. Exemplo: appcliente://retornopagamento PARÂMETROS Parâmetro Descrição Exemplo MENSAGEM Objeto JSON { "captura":"onl-x, codautorizacao":"133222", "codprodutomatriz":"4", "codprodutosecundario":"204", "codresposta":"000", "datarequisicao":"141114133218", "dataservidor":"141114133218", "estacquirer":"0010000244470001", "estvenda":"0000000000000003", "fluxo":"4", idaplicacao":"com.appparceiro", "idtransacao":"1", "modocaptura":"141010204080", nomeaplicacao":"app Parceiro", "nsu":"419343", "pan":"455182-9478", referencia":"venda 123", "retornoaplicacao":"r00", tipotransacao":1, "valor":"200", "versaoappfinanceira":"1.3.2", 15
email : cliente@email.com.br, nomebandeira : VISA, nomeprodutomatriz : CREDITO, nomeprodutosecundario : A VISTA } DETALHAMENTO PARÂMETRO MENSAGEM Parâmetro Descrição Exemplo pan 6 primeiros-4 últimos dígitos do cartão ou 4 últimos dígitos do cartão 498453-1214 ou ************1214 captura Tipo de captura ("ONL-?" ou "OFF-?") ONL-C codautorizacao Código de Autorização 100324 codprodutomatriz Código produto matriz 4 codprodutosecundario Código produto secundário 204 codresposta Código de resposta 000 datarequisicao Data/hora da requisição 140502100145 (yymmddhhmmss) dataservidor Data/hora servidor 140502100145 (yymmddhhmmss) estacquirer Estab. do Acquirer EC 0010000244470001 estvenda Estab. para Venda EC 0000000000000003 fluxo Fluxo do POS 04 idaplicacao Id da aplicação que enviou a transação para o Cielo Mobile com.appparceiro 16
idtransacao Id da transação 100 modocaptura Modo captura 141010204080 nomeaplicacao Nome da aplicação que enviou a transação para o Cielo Mobile App Parceiro nsu Número do documento 469603 codaid Código do Aid utilizado na transação A0000000031010 parcelas Número de parcelas 3 referencia Referência da transação Venda 123 retornoaplicacao Código de Retorno da Aplicação R00 tipotransacao Tipo da transação. Cancelamento ou Pagamento. 1 - Pagamento 2 - Cancelamento valor Valor final da transação 200 para o valor 2,00. versaoappfinanceira Versão da aplicação financeira do Cielo Mobile 1.3.2 Email E-mail para qual foi enviado o comprovante da transação. cliente@email.com.br nomebandeira Bandeira do cartão utilizado VISA nomeprodutomatriz Nome do produto matriz CREDITO nomeprodutosecundario Nome do produto secundário A VISTA MÉTODO DE RECEBIMENTO Android Parâmetro Método 17
MENSAGEM Extra IOS Parâmetro Método MENSAGEM GET CANCELAMENTO No aplicativo Cielo Mobile, acesse a tela de cancelamento que solicita a digitação do CPF ou CNPJ do estabelecimento. O cancelamento é uma nova transação no aplicativo do parceiro. A relação com o pagamento é feita no aplicativo Cielo Mobile, e por isso o cancelamento deve ter um novo identificador de transação. URL Cielomobile://cancelar PARÂMETROS Parâmetro Descrição Exemplo urlcallback Endereço de callback para a aplicação de venda. cielomobile://cancelar?urlcallback=appcliente: //retornocancelamento MENSAGEM Objeto JSON { "datatransacao":"141208120609", "codprodutomatriz":"4", "idtransacao":"321", "tipotransacao":2, "valor":"200", "nsu":"12634", "codprodutosecundario":"304", 18
"referencia":"referência", "dataservidor":"141208121212", "nomeaplicacao":"cliente", "estvenda":"00000000000004", email : cliente@email.com.br } DETALHAMENTO PARÂMETRO MENSAGEM Parâmetro Descrição Exemplo idtransacao Identificador da transação 1 codprodutomatriz Código produto matriz 4 codprodutosecundario Código produto secundário 204 dataservidor Data/hora servidor 141114133218 (yymmddhhmmss) estvenda Estabelecimento para Venda EC 0010000244470001 valor Valor da transação 200 para o valor 2,00. nomeaplicacao Nome da aplicação que enviou a transação para o Cielo Mobile Aplicação de Venda nsu NSU 469603 referencia Referência da transação Venda 123 email E-mail do portador do cartão que receberá o comprovante de cancelamento da transação. cliente@email.com.br 19
MÉTODO DE ENVIO Android Parâmetro Método urlcallback GET MENSAGEM Extra Exemplo: cielomobile://cancelar?urlcallback=appcliente://retornocancelamento IOS Parâmetro Método urlcallback GET MENSAGEM GET Exemplo: cielomobile://cancelar?urlcallback=appcliente://retornocancelamento&me nsagem=%7b%22datatransacao%22:%22141208104506%22,%22codpr odutomatriz%22:%224%22,%22idtransacao%22:%22123423%22,%22ti potransacao%22:2,%22valor%22:%222100%22,%22nsu%22:%221234 5%22,%22codProdutoSecundario%22:%22321%22,%22referencia%22: %22refer%C3%AAncia%22,%22dataServidor%22:%22141208101010%2 2,%22nomeAplicacao%22:%22app%22,%22estVenda%22:%2200000000 0000003%22%7D,%22email%22%3A%22cliente%40email.com.br%22 DIAGRAMA DE SEQÜÊNCIA CANCELAMENTO COM SUCESSO 20
FLUXO DE EXCEÇÃO CANCELAMENTO JÁ REALIZADO Se a aplicação de venda não receber uma resposta, ela pode repetir a transação utilizando o mesmo ID. O Cielo Mobile verificará se a transação já foi realizada e caso já tenha sido, não repetirá a mesma e retornará os dados da transação de cancelamento para a aplicação de venda. Deste modo o aplicativo pode realizar a chamada de cancelamento ao Cielo Mobile múltiplas vezes sem duplicar a transação. RESPOSTA DO CANCELAMENTO Quando um cancelamento é finalizado, o Cielo Mobile retorna o fluxo para a aplicação de venda com o resultado do cancelamento. O endereço de retorno será o informado no parâmetro urlcallback da mensagem de cancelamento, e ele deverá ser capaz de receber os parâmetros abaixo. URL 21
A URL é definida na aplicação do parceiro. Exemplo: appcliente://retornocancelamento PARÂMETROS Parâmetro Descrição Exemplo MENSAGEM Objeto JSON { "captura":"onl-x", "codautorizacao":"141738", "codprodutomatriz":"4", "codprodutosecundario":"204", "codresposta":"000", "datarequisicao":"141114141730", "dataservidor":"141114141730", "estacquirer":"0010000244470001", "estvenda":"0010000244470001", "fluxo":"28", idaplicacao":"com.appparceiro", "idtransacao":"2", "modocaptura":"141010204080", nomeaplicacao":"app Parceiro", "nsu":"419345", "pan":"455182-9478", referencia":"venda 123", "retornoaplicacao":"r00", "tipotransacao":2, "valor":"200", "versaoappfinanceira":"1.3.2", email : cliente@email.com.br, nomebandeira : VISA, 22
nomeprodutomatriz : CREDITO, nomeprodutosecundario : A VISTA } DETALHAMENTO PARÂMETRO MENSAGEM Parâmetro Descrição Exemplo pan 6 primeiros-4 últimos dígitos do cartão ou 4 últimos dígitos do cartão 498453-1214 ou ************1214 captura Tipo de captura ("ONL-?" ou "OFF-?") ONL-C codautorizacao Código de Autorização 100324 codprodutomatriz Código produto matriz 4 codprodutosecundario Código produto secundário 204 codresposta Código de resposta 000 datarequisicao Data/hora da requisição 140502100145 (yymmddhhmmss) dataservidor Data/hora servidor 140502100145 (yymmddhhmmss) estacquirer Estab. do Acquirer EC 0010000244470001 estvenda Estab. para Venda EC 0000000000000003 fluxo Fluxo do POS 04 idaplicacao Id da aplicação que enviou a transação para o Cielo Mobile com.appparceiro idtransacao Id da transação 1 23
modocaptura Modo captura 141010204080 nomeaplicacao Nome da aplicação que enviou a transação para o Cielo Mobile App Parceiro nsu Número do documento 469603 codaid Código do Aid utilizado na transação A0000000031010 parcelas Número de parcelas 3 referencia Referência da transação Venda 123 retornoaplicacao Código de Retorno da Aplicação R00 tipotransacao Tipo da transação. Cancelamento ou Pagamento. 1 - Pagamento 2 - Cancelamento valor Valor da transação 200 para o valor 2,00. versaoappfinanceira Versão da aplicação financeira do Cielo Mobile 1.3.2 email E-mail para qual foi enviado o comprovante de cancelamento da transação. cliente@email.com.br nomebandeira Bandeira do cartão utilizado VISA nomeprodutomatriz Nome do produto matriz CREDITO nomeprodutosecundario Nome do produto secundário A VISTA MÉTODO DE RECEBIMENTO Android Parâmetro Método MENSAGEM Extra 24
IOS Parâmetro Método MENSAGEM GET HISTÓRICO Inicia o aplicativo Cielo Mobile na tela de exibição do histórico. URL cielomobile://exibirhistorico PARÂMETROS Parâmetro Descrição urlcallback Endereço de callback para a aplicação de venda. Exemplo: cielomobile://exibirhistorico?urlcallback=appcliente://retornohistorico RETORNO HISTÓRICO Quando a exibição do histórico for finalizada, O Cielo Mobile retornará o fluxo para a aplicação de venda informando o resultado da chamada. URL A URL é definida na aplicação do parceiro. Exemplo: appcliente://retornohistorico PARÂMETROS Parâmetro Descrição Exemplo 25
MENSAGEM Objeto JSON { idaplicacao":"com.appparceiro", "retornoaplicacao":"r00", } DETALHAMENTO PARÂMETRO MENSAGEM Parâmetro Descrição Exemplo retornoaplicacao Código de Retorno da Aplicação R00 idaplicacao Id da aplicação que enviou a transação para o Cielo Mobile com.appparceiro MÉTODO DE RECEBIMENTO Android Parâmetro Método MENSAGEM Extra IOS Parâmetro Método MENSAGEM GET CONSULTAR TRANSAÇÃO Busca uma transação específica feita pela aplicação do parceiro. URL cielomobile://buscartransacao 26
PARÂMETROS Parâmetro Descrição Exemplo urlcallback Endereço de callback para a aplicação de venda. cielomobile://buscartransacao?urlcallback= appcliente://retornoconsulta MENSAGEM Objeto JSON { "idtransacao":"1" } DETALHAMENTO PARÂMETRO MENSAGEM Parâmetro Descrição Exemplo idtransacao Id da transação a ser recuperada 1 MÉTODO DE ENVIO Android Parâmetro Método urlcallback GET MENSAGEM Extra Exemplo: cielomobile://buscartransacao?urlcallback=appcliente://retornoconsulta IOS Parâmetro Método urlcallback GET 27
MENSAGEM GET Exemplo: cielomobile://buscartransacao?urlcallback=appcliente://retornoconsulta& mensagem=%7b%22idtransacao%22%3a%22123%22%7d%0a RESPOSTA DA CONSULTA Quando a consulta é realizada, o Cielo Mobile retornará o fluxo para a aplicação de venda com os dados da transação consultada. O endereço será o informado no parâmetro urlcallback na mensagem de consulta. O endereço deverá ser capaz de receber os parâmetros abaixo. URL A URL é definida na aplicação do parceiro. Exemplo: appcliente://retornoconsulta PARÂMETROS Parâmetro Descrição Exemplo MENSAGEM Objeto JSON { "captura":"onl-x", "codautorizacao":"133222", "codprodutomatriz":"4", "codprodutosecundario":"204", "codresposta":"000", "datarequisicao":"141114133218", "dataservidor":"141114133218", "estacquirer":"0010000244470001", "estvenda":"0000000000000003", "fluxo":"4", "idaplicacao":"b", "idtransacao":"1", "modocaptura":"141010204080", 28
"nomeaplicacao":"a", "nsu":"419343", "pan":"455182-9478", "referencia":"ref", "retornoaplicacao":"r00", "tipotransacao":1, "valor":"1000", "versaoappfinanceira":"1.3.2", nomebandeira : VISA, nomeprodutomatriz : CREDITO, nomeprodutosecundario : A VISTA } DETALHAMENTO PARÂMETRO MENSAGEM Parâmetro Descrição Exemplo pan 6 primeiros-4 últimos dígitos do cartão ou 4 últimos dígitos do cartão 498453-1214 ou ************1214 captura Tipo de captura ("ONL-?" ou "OFF-?") ONL-C codautorizacao Código de Autorização 100324 codprodutomatriz Código produto matriz 4 codprodutosecundario Código produto secundário 204 codresposta Código de resposta 000 datarequisicao Data/hora da requisição 140502100145 (yymmddhhmmss) 29
dataservidor Data/hora servidor 140502100145 (yymmddhhmmss) estacquirer Estab. do Acquirer EC 0010000244470001 estvenda Estab. para Venda EC 0000000000000003 fluxo Fluxo do POS 04 idaplicacao Id da aplicação que enviou a transação para o Cielo Mobile com.appparceiro idtransacao Id da transação 1 modocaptura Modo captura 141010204080 nomeaplicacao Nome da aplicação que enviou a transação para o Cielo Mobile App Parceiro nsu Número do documento 469603 codaid Código do Aid utilizado na transação A0000000031010 parcelas Número de parcelas 3 referencia Referência da transação Venda 123 retornoaplicacao Código de Retorno da Aplicação R00 tipotransacao Tipo da transação. Cancelamento ou Pagamento. 1 Pagamento 2 - Cancelamento valor Valor da transação 200 para o valor 2,00. versaoappfinanceira Versão da aplicação financeira do Cielo Mobile 1.3.2 nomebandeira Bandeira do cartão utilizado VISA nomeprodutomatriz Nome do produto matriz CREDITO 30
nomeprodutosecundario Nome do produto secundário A VISTA MÉTODO DE RECEBIMENTO Android Parâmetro Método MENSAGEM Extra IOS Parâmetro Método MENSAGEM GET EXPORTAÇÃO DE HISTÓRICO Retorna do Cielo Mobile todas as transações do cliente dentro do período informado. Essa exportação deverá ser paginada. Cada página possui no máximo 20 transações. URL cielomobile://exportarhistorico PARÂMETROS Parâmetro Descrição Exemplo urlcallback Endereço de callback para a aplicação de venda. cielomobile://exportarhistorico?urlcallback= appcliente://retornoexportacao MENSAGEM Objeto JSON { "datafim":"141114143719", "datainicio":"140802143019", "pagina": 1 } 31
DETALHAMENTO PARÂMETRO MENSAGEM Parâmetro Descrição Exemplo datainicio Data/hora inicial do período desejado 141110140000 (yymmddhhmmss) datafim Data/hora final do período desejado 141110150000 (yymmddhhmmss) pagina Número da página que deseja exportar o histórico. Na primeira requisição, deverá enviar a página 1. 1 MÉTODO DE ENVIO Android Parâmetro Método urlcallback GET MENSAGEM Extra Exemplo: cielomobile://exportarhistorico?urlcallback=appcliente://retornoexportacao IOS Parâmetro Método urlcallback GET MENSAGEM GET Exemplo: cielomobile://exportarhistorico?urlcallback=appcliente://retornoexportacao&mensagem =%7B%22dataFim%22%3A%22141208101010%22%2C%22dataInicio%22%3A%2214 1207101010%22%7D 32
RESPOSTA DA EXPORTAÇÃO DO HISTÓRICO Retorna o fluxo para a aplicação de venda com os dados resultantes da consulta. O endereço será o informado no parâmetro urlcallback na mensagem de exportação. O endereço deverá ser capaz de receber os parâmetros abaixo. URL A URL é definida na aplicação do parceiro. Exemplo: appcliente://retornoexportacao PARÂMETROS Parâmetro Descrição Exemplo MENSAGEM Objeto JSON { "idaplicacao":"b", "retornoaplicacao":"r00", "transacoes": [{"captura":"onl-x", "codautorizacao":"143848", "codprodutomatriz":"4", "codprodutosecundario":"204", "codresposta":"000", "datarequisicao":"141114143843", "dataservidor":"141114143843", "estacquirer":"0010000244470001", "estvenda":"0000000000000003", "fluxo":"4", "idaplicacao":"b", "idtransacao":"1", "modocaptura":"141010204080", "nomeaplicacao":"a", "nsu":"420697", "pan":"455182-9478", "referencia":"ref", "tipotransacao":1, "valor":"1000", "versaoappfinanceira":"1.3.2", nomebandeira : VISA, nomeprodutomatriz : CREDITO, nomeprodutosecundario : A VISTA }], "pagina": 1, "totalpaginas": 10, "totaltransacoes": 2000, 33
} DETALHAMENTO PARÂMETRO MENSAGEM Parâmetro Descrição Exemplo idaplicacao Id da aplicação que enviou a transação para o Cielo Mobile com.appparceiro retornoaplicacao Código de Retorno da Aplicação R00 transacoes Lista de objetos de Transacao que possuem a mesma estrutura do objeto retornado na consulta [{"captura":"onl-x", "codautorizacao":"143848", "codprodutomatriz":"4", "codprodutosecundario":"204", "codresposta":"000", "datarequisicao":"141114143843", "dataservidor":"141114143843", "estacquirer":"0010000244470001", "estvenda":"0000000000000003", "fluxo":"4", "idaplicacao":"b", "idtransacao":"1", "modocaptura":"141010204080", "nomeaplicacao":"a", "nsu":"420697", "pan":"455182-9478", "referencia":"ref", "tipotransacao":1, "valor":"1000", "versaoappfinanceira":"1.3.2" nomebandeira : VISA, nomeprodutomatriz : CREDITO, nomeprodutosecundario : A VISTA }] pagina Página que as transações foram exportadas. 1 totalpaginas Total de páginas de transações. 10 totaltransacoes Total de transações que estão gravadas no 2000 34
aplicativo. MÉTODO DE RECEBIMENTO Android Parâmetro Método MENSAGEM Extra IOS Parâmetro Método MENSAGEM GET EXEMPLO DE IMPLEMENTAÇÃO DE UM CLIENTE IOS Para integrarmos com o Cielo Mobile temos como exemplo o código abaixo de uma requisição de envio e outra de recebimento. A String JSON é gerada no aplicativo Cliente para comunicar com o Cielo Mobile. O request é montado pela interface URLSchemeSender, no seu método requestwithurl com parâmtro "strurl". 35
ENVIO IOS (PAGAMENTO) NSString *strjson ={ } "datatransacao":"141201112612", "valor":"200", "idtransacao":"123456", "referencia":"ref", "tipotransacao":1, "nomeaplicacao":"nome", "estvenda":"venda" NSString *strurl = [[NSString stringwithformat:@"%@&mensagem=%@", @"cielomobile://pagar?urlcallback=appcliente://retornopagamento", strjson] stringbyaddingpercentescapesusingencoding:nsutf8stringencoding]; NSString *requesturl = [NSString stringwithformat:@"%@", strurl]; if ([[UIApplication sharedapplication] canopenurl:[nsurl URLWithString:requestUrl]]){ [[UIApplication sharedapplication] openurl:[nsurl URLWithString:requestUrl]]; } else { [[UIApplication sharedapplication] openurl:[nsurl URLWithString:@"itmss://itunes.apple.com/br/app/cielo-mobile/id387244876?mt=8"]]; } 36
RECEBIMENTO IOS (PAGAMENTO) Todas as requisições de Caixa Rápido são processadas pelo método descrito abaixo. Esse método deverá ser implementado na classe AppDelegate. -(BOOL)application:(UIApplication *)application openurl:(nsurl *)url sourceapplication:(nsstring *)sourceapplication annotation:(id)annotation{ NSString *host = [url host]; NSArray *parametros = [[url query] componentsseparatedbystring:@"&"]; NSMutableDictionary *querystringdictionary = [NSMutableDictionary new]; for (NSString *keyvaluepair in parametros) { NSString *keyvaluedecoded = [keyvaluepair stringbyreplacingpercentescapesusingencoding:nsutf8stringencoding]; NSArray *paircomponents = [keyvaluedecoded componentsseparatedbystring:@"="]; NSString *key = [paircomponents objectatindex:0]; NSString *value = [paircomponents objectatindex:1]; } [querystringdictionary setobject:value forkey:key]; } NSString *strjson = [querystringdictionary objectforkey:@"mensagem"]; VALIDAÇÃO IOS A aplicação Cielo Mobile recebe os dados da requisição do Cliente, valida e processa a requisição. A aplicação parceira recebe o resultado da chamada pela URL de callback que enviou na requisição. O Cielo Mobile retorna em caso de algum parâmetro inválido na requisição R09, este retorno é pela URL de callback. PLIST CADASTRO URL CALLBACK A aplicação cliente responsável por processar o retorno vindo do Cielo Mobile deve configurar o property list do projeto. A configuração do URL Scheme deve estar de acordo com o exemplo abaixo. No URL Scheme é onde definimos o host da URL de Callback. 37
EXEMPLO DE IMPLEMENTAÇÃO DE UM CLIENTE ANDROID Segue abaixo um exemplo de envio e recebimento de chamadas com o Cielo Mobile. A String JSON que foi gerada a partir da classe de comunicação entre o aplicativo do cliente e o Cielo Mobile, deve ser enviada via Intent através do método putextra e com o nome "MENSAGEM". Conforme exemplo a seguir. ENVIO (PAGAMENTO) Uri uri = Uri.parse("cielomobile://pagar?urlCallback=appcliente://retornopagamento"); Intent intent = new Intent(Intent.ACTION_VIEW, uri); String jsonstring = "{ "valor":"200", "idtransacao":"1", "nomeaplicacao":"aplicacao de Venda", "referencia":"venda 123" }"; intent.putextra("mensagem", jsonstring); startactivityforresult(intent, PAGAMENTO_REQUEST); RECEBIMENTO (PAGAMENTO) Intent i = getintent(); Bundle extras = i.getextras(); String jsonstring = extras.getstring("mensagem"); VALIDAÇÃO 38
A aplicação Cielo Mobile valida os dados de requisição. Por isso, a Intent deverá ser iniciada com o método startactivityforresult. Esse método retorna para a aplicação parceira o resultado da chamada. Caso o resultado seja RESULT_OK, a aplicação Cielo Mobile irá continuar com o processamento. Caso seja diferente de RESULT_OK, o Cielo Mobile não irá continuar com o processamento e a aplicação de venda deverá realizar algum tratamento. Segue exemplo: @Override protected void onactivityresult(int requestcode, int resultcode, Intent data) { if (requestcode == PAGAMENTO_REQUEST) { if (resultcode == RESULT_OK) { txtactivityresult.settext("activityresult: OK"); } else if (resultcode == 3) { // URL invalida Toast.makeText(this, "URL invalida", Toast.LENGTH_SHORT).show(); } else if (resultcode == 2) { // Parametros invalidos Toast.makeText(this, "Parametro invalido", Toast.LENGTH_SHORT).show(); } } } super.onactivityresult(requestcode, resultcode, data); DADOS DE RETORNO ACTIVITYRESULT Cógido Descrição RESULT_OK A requisição foi feita com sucesso. O Cielo Mobile irá continuar com o processamento. 2 Os parâmetros enviados estão inválidos. 3 A URL de callback está inválida. 39
ANDROID MANIFEST A activity responsável por processar o retorno vindo do Cielo Mobile deve estar configurada no arquivo AndroidManifest.xml para receber a requisição. Exemplo: <activity android:name=".activity.respostas.respostapagamentoactivity" android:label="@string/title_activity_resposta_pagamento" > <intent-filter> <data android:host="retornopagamento" android:scheme="appcliente" /> <action android:name="android.intent.action.view" /> <category android:name="android.intent.category.default" /> </intent-filter> </activity> DADOS DE RETORNO FLUXO Fluxo Descrição 4 CRÉDITO À VISTA 5 CRÉDITO PARCELADO ADMINISTRATIVO 6 CRÉDITO PARCELADO LOJA 8 DÉBITO À VISTA 9 DÉBITO PRÉ-DATADO 10 DÉBITO VENDA CREDIÁRIO 11 SIMULAÇÃO DE CREDIÁRIO 13 VISA VALE 28 CANCELAMENTO 40
TIPO DE CAPTURA O tipo de captura possui o formato YYY-E, segundo especificação abaixo. YYY Descrição ONL Se a transação for Online OFF Se a transação for Offline E Descrição X Se a captura do número do Cartão foi feita por digitação do embosso D Se a captura do número do Cartão foi feita por leitura da tarja magnética C Se a captura do número do Cartão foi feita por leitura do Chip L Se a captura do número do Cartão foi feita sem contato. CÓDIGOS DE RESPOSTA Código Descrição 000 Aprovada Diferente de 000 Negada RETORNO DA APLICAÇÃO Código Descição R00 Processamento com sucesso R01 Erro interno R02 Caixa Rápido não habilitado R03 Cielo Mobile Bloqueado 41
R04 Valor Zerado R05 Transação não encontrada R06 Transação existente R07 Terminal inoperante R08 Nenhuma rede disponível R09 (plataforma IOS) Parâmetros Inválidos R10 Limite máximo de transações atingido para exportar o histórico. Deverá ser paginado. R11 Página inválida. ORIENTAÇÕES FINAIS É muito importante que após o término do desenvolvimento o cliente contate a Central de Suporte Técnico para ativar a funcionalidade e garantir que suas vendas sejam capturadas corretamente. Para isso, é necessário realizar os seguintes procedimentos: 1. Desinstalar o aplicativo utilizado no desenvolvimento (Este procedimento é realizado para garantir que será feito o download da última versão) 2. Fazer download do aplicativo 3. Realizar o desbloqueio com o número lógico de produção que será fornecido pelo analista de Suporte Técnico 4. Habilitar a funcionalidade Central de Suporte Técnico 4002 9111 Capitais e Regiões Metropolitanas 0800 570 0111 Demais Localidades Todos os dias da semana, 24 horas 42