www.f2b.com.br
Micropagamento F2b
Web Services
Web
rev 00
18/04/2006
Micropagamento F2b – Web Services/Web
18/04/2006
Controle de Revisões
Revisão
Data
00
17/04/2006
www.f2b.com.br
Descrição
Emissão inicial.
rev 00
Página 2/10
Micropagamento F2b – Web Services/Web
18/04/2006
Índice
1
Introdução .........................................................................................................4
2
Web Service ......................................................................................................5
2.1
Introdução...........................................................................................................5
2.2
Definição do Serviço...........................................................................................5
2.3
Parâmetros da Requisição .................................................................................5
2.4
Parâmetros do Retorno ......................................................................................6
2.5
Exemplo de Requisição ......................................................................................7
2.6
Exemplo de Retorno...........................................................................................7
2.7
Exemplo de Programa Cliente em Java .............................................................7
2.8
Exemplo de Programa Cliente em Microsoft ASP ..............................................7
2.9
Exemplo de Programa Cliente em PHP .............................................................7
3
Web ....................................................................................................................9
3.1
Introdução...........................................................................................................9
3.2
Parâmetros da Requisição HTTP .......................................................................9
3.3
Parâmetros de Retorno ......................................................................................10
3.4
Exemplo de Formulário em HTML......................................................................10
www.f2b.com.br
rev 00
Página 3/10
Micropagamento F2b – Web Services/Web
18/04/2006
1 Introdução
Este documento define as formas de acesso remoto aos serviços do Micropagamento F2b.
O Micropagamento F2b é um serviço, disponível para os usuários de contas no sistema F2b, que
permite a transferência de valores de uma conta F2b (consumidor) para uma outra conta F2b
(estabelecimento), além da administração do recebimento e pagamento desses pagamentos.
Este serviço está disponível no site da F2b (www.f2b.com.br) para seus usuários ao acessar as contas.
As formas de acesso interativo, através do site, são adequadas a todos os tipos de usuários com
volumes baixos e médios de pagamentos. Para o usuário ter uma integração direta entre seus sistemas
e o Micropagamento F2b, existem duas formas de acesso remoto aos serviços:
Web service: utiliza protocolo SOAP (Simple Object Access Protocol) sobre HTTP (Hypertext Transfer
Protocol), sendo adequado a todos os tipos de usuários, de baixo a alto volume, permitindo a
transferência de valores entre contas F2b (pagamentos).
Web: utiliza protocolo HTTP, métodos POST ou GET, sendo adequado a todos os tipos de usuários, de
baixo a alto volume, permitindo a transferência de valores entre contas F2b (pagamentos).
Para utilizar o pagamento através de web service ou web, o usuário deve ter uma conta ativa no
sistema F2b e seguir as instruções deste manual para implementar as alterações necessárias no seu
site ou sistema.
A F2b recomenda que todos os usuários utilizem o registro através de web service pelos seguintes
motivos:
•
A utilização de web service não restringe o usuário a apenas um envio diário nem a um volume
mínimo.
•
O web service retorna a URL (Uniform Resource Locator), permitindo ao sistema do usuário
abrir diretamente a página de pagamento para o cliente.
•
O web service, além de ser compatível com as arquiteturas de sistema mais comuns (Microsoft,
Java, etc.), é a única forma que permite evoluções sem impacto nos sistemas já implantados.
•
O web service é protegido usando SSL (Secure Sockets Layer) com criptografia de 128 bits.
A segunda forma recomendada de registro remoto é o web, que apresenta as seguintes características:
•
Não há restrições quanto a quando nem quantas vezes usar.
•
Caso haja algum erro nos dados enviados, é aberta uma tela com a mensagem de erro.
•
Pode ser implementado usando HTML, ASP, JSP, etc. O desenvolvedor deve, entretanto,
tomar cuidado para que os dados da conta F2b não fiquem visíveis para os internautas.
•
É protegido usando SSL (Secure Sockets Layer) com criptografia de 128 bits.
Independente da forma escolhida, os pagamentos efetuados podem ser consultados através do site da
F2b.
Neste documento o termo sacador se refere ao titular da conta F2b que gera pagamentos, ou seja, o
estabelecimento.
www.f2b.com.br
rev 00
Página 4/10
Micropagamento F2b – Web Services/Web
18/04/2006
2 Web Service
2.1 Introdução
Web service é um aplicativo de software identificado por uma URI (Uniform Resource Identifier) que
suporta a interação direta com outros aplicativos usando mensagens baseadas em XML (eXtensible
Markup Language) através de protocolos da Internet.
No caso específico do web service Micropagamento F2b, seu acesso é feito através da seguinte URI:
https://www.f2b.com.br/WSMicropayment
Obs: a URI acima utiliza SSL, o que é recomendado para garantir a segurança das mensagens
trocadas pela internet, entretanto, alguns sistemas podem ter dificuldades para implementar a troca
usando SSL. Nestes casos poderá ser usada a URI http://www.f2b.com.br/WSMicropayment que realiza
a mesma funcionalidade sem criptografar as mensagens.
O web service é ativado enviando, no corpo da requisição HTTP um XML no padrão SOAP. Após sua
execução o web service retorna outro XML no padrão SOAP no corpo da resposta.
2.2 Definição do Serviço
O web service Micropagamento F2b é definido pelo WSDL (Web Service Definition Language), contido
no arquivo wsmicropayment.wsdl que está junto com esse manual.
2.3 Parâmetros da Requisição
O corpo da requisição é formado pela seqüência de um elemento mensagem, um elemento sacador, e
um elemento micropagamento.
O elemento mensagem possui dois atributos: data e numero.
O elemento sacador possui dois atributos: conta e senha, e seu conteúdo é um texto contendo o
nome do sacador.
O elemento micropagamento possui um atributo: valor. Ele também possui a seguinte seqüência de
elementos: um elemento pedido, um elemento ip_autenticacao, um elemento url_retorno e um
elemento cod_verificacao:
O elemento pedido não possui atributos, seu conteúdo é um texto contendo o número do pedido.
O elemento ip_autenticacao não possui atributos, seu conteúdo é um texto contendo o número
do ip que fez a requisição para autenticação na F2b.
O elemento url_retorno não possui atributos, seu conteúdo é um texto contendo a url de retorno
a qual a F2b irá retornar com a resposta do servidor após a validação do pagamento.
O elemento cod_verificacao não possui atributos, seu conteúdo é um texto contendo um código
de verificação para o usuário fazer uma validação no retorno.
www.f2b.com.br
rev 00
Página 5/10
Micropagamento F2b – Web Services/Web
18/04/2006
A tabela abaixo fornece uma descrição de cada elemento e atributo que compõe o corpo da requisição.
NOME
TIPO
DESCRIÇÃO
mensagem
Elemento
data
Atributo
numero
Atributo
sacador
Elemento
conta
Atributo
senha
micropagamento
Atributo
Elemento
valor
Atributo
pedido
Elemento
ip_autenticacao
Elemento
url_retorno
Elemento
cod_verificacao
Elemento
Fornece informações como data de envio e
número de controle para administração do
sistema por parte do cliente.
Data de envio da mensagem pelo cliente.
Ex: “2006-04-17”
Número de controle do cliente.
Ex: “123133”
Contém o nome do sacador.
Ex: “João da Silva”.
O número do cartão da conta F2b do
sacador. Ex: “9023010001230123”
A senha da conta F2b do sacador.
Possui atributos e elementos que
descrevem o micropagamento.
O valor em Reais do micropagamento.
Ex: “10.00”
Número do pedido gerado pelo cliente.
Ex: “000001”.
O número do IP que fez a requisição para o
micropagamento.
Url de retorno após o processamento do
pagamento no sistema da F2b.
Código de verificação para uma
consistência após o retorno da F2b.
FORMATO
AAAA-MM-DD
999999999
Texto
9999999999999999
Texto
9.99
Texto
Texto
Texto
Texto
Observações:
1. Os elementos e atributos em negrito na tabela são obrigatórios.
2.4 Parâmetros do Retorno
O corpo do retorno é formado pela seqüência um elemento url_autenticacao, um elemento
cod_resultado, um elemento txt_resultado e um elemento log.
O elemento url_autenticacao não possui atributos, seu conteúdo é um texto contendo a url para
autenticação do pagamento.
O elemento cod_resultado não possui atributos, seu conteúdo é um número contendo o código do
resultado.
O elemento txt_resultado não possui atributos, seu conteúdo é um texto contendo a descrição do
resultado.
O elemento log não possui atributos, seu conteúdo é um texto contendo o log da resposta do servidor.
www.f2b.com.br
rev 00
Página 6/10
Micropagamento F2b – Web Services/Web
18/04/2006
A tabela abaixo fornece uma descrição de cada elemento e atributo que compõe o corpo do retorno.
NOME
TIPO
url_autenticacao
cod_resultado
Elemento
Elemento
txt_resultado
Elemento
log
Elemento
DESCRIÇÃO
Contém a url para a autenticação do pagamento
Contém o código do resultado.
Ex: “1”
Contém a descrição do resultado.
Ex: “Solicitado”
Contém o resultado do processamento. Pode
ser “ ” se não houve problemas no
processamento ou “ERRO ...” seguido da lista
de erros encontrados.
FORMATO
Texto
Texto
Texto
Texto
2.5 Exemplo de Requisição
Um exemplo de requisição pode ser encontrado no arquivo F2bMicroPayment.xml que está junto com
esse manual.
2.6 Exemplo de Retorno
Um exemplo de retorno pode ser encontrado no arquivo F2bMicroPaymentRetorno.xml que está junto
com esse manual.
2.7 Exemplo de Programa Cliente em Java
O arquivo WSMicroPaymentTest.java apresenta um exemplo de programa cliente em Java que gera a
requisição, envia e recebe o retorno.
2.8 Exemplo de Programa Cliente em Microsoft ASP
O arquivo WSMicroPaymentASP.asp apresenta um exemplo de programa cliente em ASP que gera a
requisição, envia e recebe o retorno.
2.9 Exemplo de Programa Cliente em PHP
O arquivo WSMicroPaymentPHP.php apresenta um exemplo de programa cliente em PHP que gera a
requisição, envia e recebe o retorno. Este exemplo utiliza as classes contidas nos arquivos
WSMicroPayment.php e XML.php.
A classe WSMicroPayment.php poderá usar a biblioteca CURL do PHP, se for compilado com essa
biblioteca será reduzido consideravelmente o tempo do processamento. Se o PHP utilizado não possuir
a biblioteca CURL será usado o método padrão que é mais lento.
www.f2b.com.br
rev 00
Página 7/10
Micropagamento F2b – Web Services/Web
18/04/2006
Esse mesmo exemplo está disponível na loja virtual osCommerce, que é totalmente free e desenvolvida
em php com mySql. Você pode instalar o Micropagamento F2b pela administração da loja com rapidez
e
facilidade.
O
módulo
de
pagamento
pode
ser
baixado
em
http://www.f2b.com.br/pt_BR/f2b/micropayment/ F2bosCommerceMP.zip
www.f2b.com.br
rev 00
Página 8/10
Micropagamento F2b – Web Services/Web
18/04/2006
3 Web
3.1 Introdução
O envio de Micropagamentos via web, apesar de não ser tão elegante, seguro e expansível quanto o
web service, é a forma mais fácil e rápida de implantar o Micropagamento F2b em um site.
Seu acesso é feito através da seguinte URI:
https://www.f2b.com.br/MPRequestWeb
Obs: a URI acima utiliza SSL, o que é recomendado para garantir a segurança das mensagens
trocadas pela internet, entretanto, alguns sites podem ter dificuldades para usar SSL. Nestes casos
poderá ser usada a URI http://www.f2b.com.br/MPRequestWeb que realiza a mesma funcionalidade
sem criptografar os dados.
O Micropagamento é requisitado enviando um requisição HTTP, com os métodos POST ou GET,
passando os parâmetros necessários. Deve-se evitar o uso do método GET pois os parâmetros
enviados ficam facilmente visíveis para o internauta.
Ao executar a requisição, o sistema responderá com uma tela HTML para o usuário, com as seguintes
possibilidades:
1. Uma tela de autenticação. Este caso ocorrerá caso todos os campos tenham sido informados
corretamente.
2. Uma tela com mensagem de erro. Caso exista algum erro nos dados enviados e o sistema não
conclua a requisição do Micropagamento.
3. Deve existir uma URL de retorno definida no momento do envio dos dados, também será feito
um POST dos parâmetros enviados para a F2b (pedido, cod_verificacao), além do código do
resultado, texto do resultado, número da transação na F2b e log (item 3.3).
3.2 Parâmetros da Requisição HTTP
NOME
conta
senha
valor
pedido
ip_autenticacao
url_retorno
cod_verificacao
DESCRIÇÃO
FORMATO
O número do cartão da conta F2b do sacador. Ex:
“9023010001230123”
A senha da conta F2b do sacador.
O valor em Reais do Micropagamento. Ex: “10.00”
Número do pedido gerado pelo cliente.
Ex: “000001”.
O número do IP que fez a requisição para o
Micropagamento.
Url de retorno após o processamento do pagamento
no sistema da F2b.
Código de verificação para uma consistência após o
retorno da F2b.
9999999999999999
Texto
9.99
Texto
Texto
Texto
Texto
Observações:
1. Os campos em negrito são obrigatórios.
www.f2b.com.br
rev 00
Página 9/10
Micropagamento F2b – Web Services/Web
18/04/2006
3.3 Parâmetros de Retorno
São enviados os seguintes parâmetros para a URL de retorno enviada na requisição:
NOME
pedido
cod_verificacao
cod_resultado
txt_resultado
transacao
log
DESCRIÇÃO
Número do pedido gerado pelo cliente.
Ex: “000001”.
Código de verificação para uma consistência após o
retorno da F2b.
Código do resultado sobre o Micropagamento no
sistema da F2b.
Texto do resultado sobre o Micropagamento no
sistema da F2b.
Número da transação da F2b sobre o
Micropagamento.
Log do processamento do Micropagamento no
sistema da F2b
FORMATO
Texto
Texto
9
Texto
9
Texto
3.4 Exemplo de Formulário em HTML
O arquivo MicroPaymentWebTest.html apresenta um formulário HTML estático para a requisição
remota do Micropagamento.
www.f2b.com.br
rev 00
Página 10/10