ESPECIFICAÇÃO TÉCNICA CIELO MOBILE – CHAMADA EXTERNA

Transcrição

ESPECIFICAÇÃO TÉCNICA
CIELO MOBILE – CHAMADA EXTERNA
Maio 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
2
Fluxo de exceção 3 – Cielo Mobile bloqueado ou em estado de
Terminal Inoperante .................................................................................12
RESPOSTA DO PAGAMENTO ....................................................... 13
URL ........................................................................................................13
Parâmetros ...............................................................................................13
Método de recebimento ............................................................................15
Android .....................................................................................................15
IOS
........................................................................................................15
CANCELAMENTO .......................................................................... 16
URL ........................................................................................................16
Parâmetros ...............................................................................................16
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
Android .....................................................................................................21
3
IOS
........................................................................................................22
HISTÓRICO ..................................................................................... 22
URL ........................................................................................................22
Parâmetros ...............................................................................................22
RETORNO HISTÓRICO .................................................................. 22
URL ........................................................................................................22
Parâmetros ...............................................................................................22
Android .....................................................................................................23
IOS
........................................................................................................23
CONSULTAR TRANSAÇÃO ........................................................... 23
URL ........................................................................................................23
Parâmetros ...............................................................................................24
Método de envio .......................................................................................24
Android .....................................................................................................24
IOS
........................................................................................................24
RESPOSTA DA CONSULTA .......................................................... 25
URL ........................................................................................................25
Parâmetros ...............................................................................................25
Android .....................................................................................................27
4
IOS
........................................................................................................28
EXPORTAÇÃO DE HISTÓRICO ..................................................... 28
URL ........................................................................................................28
Parâmetros ...............................................................................................28
Método de envio .......................................................................................28
Android .....................................................................................................28
IOS
........................................................................................................29
RESPOSTA DA EXPORTAÇÃO DO HISTÓRICO .......................... 29
URL ........................................................................................................29
Parâmetros ...............................................................................................29
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
5
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
6
VERSÃO DO DOCUMENTO
Essa é a versão 1.9 do manual de integração, de maio de 2015.
INTRODUÇÃO
Para iniciar o desenvolvimento de integração ao Cielo Mobile, favor enviar e-mail para
[email protected] 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 [email protected], 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
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.
7
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 chamada externa 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).
8
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
urlCallback=appcliente://retornopagamento
Endereço de callback para a
aplicação de venda.
MENSAGEM Objeto JSON
{
"idTransacao":"1",
"valor":"200",
“estVenda":"0010000244470001",
“nomeAplicacao":"Aplicação de
Venda",
“referencia":"Venda 123"
“tipoProdutoAdministrativo":"false",
“email”:”[email protected]”
}
9
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
[email protected]
E-mail do portador do cartão que
receberá o comprovante da transação.
MÉTODO DE ENVIO
Android
Parâmetro
Método
urlCallback
GET
MENSAGEM
Extra
Exemplo:
cielomobile://pagar?urlCallback=appcliente://retornopagamento
IOS
Parâmetro
Método
10
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
11
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
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
12
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.
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",
13
"nsu":"419343",
"pan":"455182-9478",
“referencia":"Venda 123",
"retornoAplicacao":"R00",
“tipoTransacao":1,
"valor":"200",
"versaoAppFinanceira":"1.3.2",
}
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
14
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
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
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.
[email protected]
2 - Cancelamento
MÉTODO DE RECEBIMENTO
Android
Parâmetro
Método
MENSAGEM
Extra
15
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
urlCallback
Exemplo
Endereço de callback para cielomobile://cancelar?urlCallback=appcliente:
a aplicação de venda.
//retornocancelamento
{
"dataTransacao":"141208120609",
"idTransacao":"321",
"tipoTransacao":2,
"valor":"200",
"nsu":"12634",
"referencia":"referência",
16
"nomeAplicacao":"cliente",
"estVenda":"00000000000004",
}
Parâmetro
Descrição
Exemplo
idTransacao
Identificador da transação
1
codProdutoMatriz
4
204
dataServidor
141114133218
Data/hora servidor
(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
Venda 123
email
E-mail do portador do cartão que receberá o
comprovante de cancelamento da transação.
[email protected]
MÉTODO DE ENVIO
17
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
18
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
19
appcliente://retornocancelamento
PARÂMETROS
Parâmetro
Descrição
Exemplo
MENSAGEM
Objeto JSON
{
"captura":"ONL-X",
"codAutorizacao":"141738",
"estAcquirer":"0010000244470001",
"estVenda":"0010000244470001",
"fluxo":"28",
"idTransacao":"2",
"modoCaptura":"141010204080",
“nomeAplicacao":"App Parceiro",
"nsu":"419345",
"pan":"455182-9478",
“referencia":"Venda 123",
"tipoTransacao":2,
"valor":"200",
"versaoAppFinanceira":"1.3.2",
}
20
Parâmetro
Descrição
Exemplo
pan
498453-1214
ou
************1214
captura
ONL-C
codAutorizacao
100324
codProdutoMatriz
4
204
codResposta
Código de resposta
000
dataRequisicao
140502100145
(yyMMddHHmmss)
dataServidor
Data/hora servidor
140502100145
(yyMMddHHmmss)
estAcquirer
0010000244470001
estVenda
0000000000000003
fluxo
Fluxo do POS
04
idAplicacao
para o Cielo Mobile
com.appParceiro
idTransacao
Id da transação
1
modoCaptura
Modo captura
141010204080
nomeAplicacao
App Parceiro
21
nsu
469603
codAid
A0000000031010
parcelas
Número de parcelas
3
referencia
Venda 123
retornoAplicacao
R00
tipoTransacao
Pagamento.
1 - Pagamento
valor
versaoAppFinanceira
Mobile
1.3.2
email
E-mail para qual foi enviado o
comprovante de cancelamento da
transação.
[email protected]
2 - Cancelamento
Android
Parâmetro
Método
MENSAGEM
Extra
IOS
Parâmetro
Método
MENSAGEM
GET
HISTÓRICO
Inicia o aplicativo Cielo Mobile na tela de exibição do histórico.
22
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
appcliente://retornohistorico
PARÂMETROS
Parâmetro
Descrição
Exemplo
MENSAGEM
Objeto JSON
{
}
Parâmetro
Descrição
retornoAplicacao Código de Retorno da Aplicação
Exemplo
R00
23
idAplicacao
Id da aplicação que enviou a transação para o Cielo
Mobile
com.appParceiro
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
PARÂMETROS
Exemplo
urlCallback
cielomobile://buscartransacao?urlCallback=
appcliente://retornoconsulta
{
"idTransacao":"1"
}
24
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
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
25
appcliente://retornoconsulta
PARÂMETROS
Parâmetro
Descrição
Exemplo
MENSAGEM
Objeto JSON
{
"captura":"ONL-X",
"codAutorizacao":"133222",
"estAcquirer":"0010000244470001",
"estVenda":"0000000000000003",
"fluxo":"4",
"idAplicacao":"b",
"idTransacao":"1",
"modoCaptura":"141010204080",
"nomeAplicacao":"a",
"nsu":"419343",
"pan":"455182-9478",
"referencia":"ref",
"tipoTransacao":1,
"valor":"1000",
"versaoAppFinanceira":"1.3.2"
}
26
Parâmetro
Descrição
Exemplo
pan
498453-1214
ou
************1214
captura
ONL-C
codAutorizacao
100324
codProdutoMatriz
4
204
codResposta
Código de resposta
000
dataRequisicao
140502100145
(yyMMddHHmmss)
dataServidor
Data/hora servidor
140502100145
(yyMMddHHmmss)
estAcquirer
0010000244470001
estVenda
0000000000000003
fluxo
Fluxo do POS
04
idAplicacao
para o Cielo Mobile
com.appParceiro
idTransacao
Id da transação
1
modoCaptura
Modo captura
141010204080
nomeAplicacao
App Parceiro
nsu
469603
27
codAid
A0000000031010
parcelas
Número de parcelas
3
referencia
Venda 123
retornoAplicacao
R00
tipoTransacao
Pagamento.
1 - Pagamento
valor
versaoAppFinanceira
Mobile
1.3.2
2 - Cancelamento
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.
Se o Cielo Mobile tiver mais de 100 transações salvas no histórico, essa exportação
deverá ser paginada. Cada página possui no máximo 20 transações.
URL
cielomobile://exportarhistorico
28
PARÂMETROS
Exemplo
urlCallback
cielomobile://exportarhistorico?urlCallback=
appcliente://retornoexportacao
{
"dataFim":"141114143719",
"dataInicio":"140802143019",
"pagina": 1
}
Exemplo
dataInicio
141110140000
Data/hora inicial do período desejado
(yyMMddHHmmss)
dataFim
Data/hora final do período desejado
141110150000
(yyMMddHHmmss)
pagina
Número da página que deseja exportar o histórico. A
paginação não é obrigatória caso o Cielo Mobile tenha
menos de 100 registros.
1
MÉTODO DE ENVIO
Android
Parâmetro
Método
urlCallback
GET
MENSAGEM
Extra
Exemplo:
cielomobile://exportarhistorico?urlCallback=appcliente://retornoexportacao
29
IOS
Parâmetro
Método
urlCallback
GET
MENSAGEM
GET
Exemplo:
cielomobile%3A%2F%2Fexportarhistorico%3FurlCallback%3Dappcliente%3A%2F%2Fr
etornoexportacao%26mensagem%3D%7B%22dataFim%22%3A%22141208101010%2
2%2C%22dataInicio%22%3A%22141207101010%22%2C%22pagina%22%3A1%7D
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
appcliente://retornoexportacao
PARÂMETROS
Parâmetro Descrição Exemplo
MENSAGEM Objeto
JSON
{
"idAplicacao":"b",
"transacoes":
[{"captura":"ONL-X", "codAutorizacao":"143848",
"codProdutoMatriz":"4", "codProdutoSecundario":"204",
"codResposta":"000", "dataRequisicao":"141114143843",
"estAcquirer":"0010000244470001",
"estVenda":"0000000000000003", "fluxo":"4",
"idAplicacao":"b", "idTransacao":"1",
30
"modoCaptura":"141010204080", "nomeAplicacao":"a",
"nsu":"420697", "pan":"455182-9478", "referencia":"ref",
"tipoTransacao":1, "valor":"1000",
"versaoAppFinanceira":"1.3.2"
}],
"pagina": 1,
"totalPaginas": 10,
"totalTransacoes": 2000,
}
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",
"codProdutoSecundario":"204", "codResposta":"000",
"estAcquirer":"0010000244470001",
"estVenda":"0000000000000003", "fluxo":"4",
"idAplicacao":"b", "idTransacao":"1",
"modoCaptura":"141010204080",
"nomeAplicacao":"a", "nsu":"420697", "pan":"4551829478", "referencia":"ref", "tipoTransacao":1,
"valor":"1000", "versaoAppFinanceira":"1.3.2"}]
pagina
Se a exportação
foi paginada,
será retornada a
página que as
transações foram
1
31
exportadas.
totalPaginas
Se a exportação
foi paginada,
será retornado o
total de páginas
de transações.
10
totalTransacoes
Se a exportação
foi paginada,
será retornado o
total de
transações que
estão gravadas
no aplicativo.
2000
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".
32
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"]];
}
33
RECEBIMENTO IOS (PAGAMENTO)
Todas as requisições da chamada externa 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.
34
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
35
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.
36
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
37
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
Chamada externa não habilitada
R03
Cielo Mobile Bloqueado
38
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
39

ESPECIFICAÇÃO TÉCNICA CIELO MOBILE – CHAMADA EXTERNA

Transcrição

Documentos relacionados

Novo estilo de vida: mobile life

ESPECIFICAÇÃO TÉCNICA CIELO MOBILE – CAIXA RÁPIDO

Apresentação do PowerPoint

Tendências Internacionais Fipp World Congress

1. mcel - AICEP

GMIC SÃO PAULO REÚNE GIGANTES DA AMÉRICA LATINA EM

Glispa finaliza compra da brasileira MOBILS, empresa de

Windows Mobile 5.0 for

CIELO – Desenho Organizacional: Uma Abordagem por Processos

Procedimentos para inscrição de RP

1 MOBILE FIRST: O RESULTADO DA INTERAÇÃO ENTRE

48889_2 cieloinfor630x275.indd