Front End

19 dez, 2013

Guia de integração PayPal usando HTML

Publicidade

Tabela de conteúdo

  1. Introdução
  2. Website Payments Standard e seu formulário HTML
    1. Atributos do formulário
    2. Campos do formulário
    3. Definindo o tipo de botão
    4. Solicitando a quantidade de itens
    5. Variáveis de acompanhamento
    6. Definindo a URL de retorno
    7. Configurando a localização e internacionalização
  3. Criando um botão Comprar Agora
  4. Tela de redirecionamento e a experiência do usuário

Introdução

Este artigo descreve o funcionamento do Website Payments Standard e como sua loja pode utilizá-lo no processo de integração. O Website Payments Standard consiste em um formulário HTML que é adicionado em sua loja, onde através de alguns campos, o botão é configurado para que seu cliente possa efetuar suas compras.

Todos os recursos do Website Payments Standard são variações desse fluxo. Por exemplo, botões ‘comprar agora’, ‘assinatura’ ou ‘adicionar ao carrinho’, todos derivam desse fluxo básico e podem facilmente ser implementados através do formulário de exemplo encontrado neste guia.

Website Payments Standard e seu formulário HTML

A interface de seu cliente com o Website Payments Standard é feita através de um formulário HTML com alguns campos hidden, que definem e configuram o botão de pagamento. Ao clicar no botão, o formulário é submetido para o ambiente seguro da PayPal, onde através das variáveis definidas nos campos do formulário, a página de checkout é montada.

Existe uma variedade muito grande de possibilidades para a criação do formulário e existem ferramentas diversas para isso. Esse vai ilustrar a criação básica do formulário e a adição dos campos para configurar alguns tipos de botões de pagamento, como o botão ‘comprar agora’ ou ‘adicionar ao carrinho’.

Atributos do formulário

A tag FORM para criação do botão de pagamento possui dois atributos requeridos: method e action. O primeiro atributo define o método de submissão do formulário para a PayPal e o segundo define o local para onde os campos deverão ser enviados.

Abaixo, um formulário com os atributos definidos para o ambiente de produção:

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
</form>

O atributo action pode ter dois possíveis valores. Um para definir o ambiente de produção e outro para definir o ambiente de testes Sandbox. Abaixo, os dois possíveis valores:

Ambiente Valor do atributo
Produção https://www.paypal.com/cgi-bin/webscr
Sandbox https://www.sandbox.paypal.com/cgi-bin/webscr

Atenção! O atributo method não deve ser modificado. Seu valor deve sempre ser post.

Campos do formulário

A definição e configuração dos botões acontece através de alguns campos do tipo hidden, dentro do formulário. Cada variável possui um significado, que será visto adiante neste guia. Mas a estrutura básica para adição de um novo campo segue o formato abaixo:

<input type="hidden" name="NomeDaVariável" value="ValorDaVariável" />

Como podemos ver no código acima, a tag input possui três atributos. O atributo type possui o valor hidden e não deve ser alterado. Já os atributos name e value definem o nome e o valor da variável.

Definindo o tipo de botão

A variável cmd é requerida dentro de um formulário, pois é essa variável que define qual o tipo de botão será utilizado na integração com Website Payments Standard.

Tipo do botão Valor da variável
Comprar Agora ou Doação _xclick
Adicionar ao Carrinho _cart

Um formulário com o campo que especifica o botão Comprar Agora se parecerá com o seguinte:

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_xclick" />
</form>

Um formulário com o campo que especifica o botão Adicionar ao Carrinho se parecerá com o seguinte:

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_cart" />
</form>

Solicitando a quantidade de itens

Quando estiver utilizando o botão Comprar Agora, é possível que seja necessário perguntar ao cliente a quantidade de itens que ele está comprando. Para isso, podemos utilizar a variável undefined_quantity. Por exemplo:

<input type="hidden" name="undefined_quantity" value="1" />

Variáveis de acompanhamento

Algumas variáveis são exclusivas para nosso uso, por exemplo, para acompanhamento de pedidos. Essas variáveis não são usadas pela PayPal, mas podem ser enviadas para, quando uma notificação de pagamento IPN for enviada, saibamos sobre qual transação ou pedido se trata.

Abaixo, as variáveis que podem ser utilizadas para acompanhamento:

Nome da variável Significado
custom É um campo livre, pode ser adicionado qualquer informação.
item_number ou item_number_1item_number_n Identifica o item que está sendo comprado.
invoice Identifica a ordem de compra do cliente.

Definindo a URL de retorno

Com o retorno automático ativado em sua conta PayPal, é possível definir a URL para onde o cliente será redirecionado após o pagamento, em cada transação individual. Por exemplo, você pode querer que o cliente que comprou um determinado produto em sua loja, seja redirecionado para uma página específica daquele produto, melhorando assim a experiência de compra. Para definir a URL de retorno, basta especificar o campo return com a URL que a PayPal deverá redirecionar seu cliente, por exemplo:

<input type="hidden" name="return" value="http://sualoja.com.br/retorno" />

Atenção! Para poder definir a URL de retorno é preciso ativar o retorno automático em sua conta PayPal.

Configurando a localização e internacionalização

A PayPal está presente em diversos países. Muitos países possuem variações na escrita, moeda, etc. Por exemplo, no Brasil utilizamos caracteres acentuados, cedilha, etc, que não são utilizados no inglês. Para permitir a internacionalização e se adequar às características de cada localização, existem alguns campos específicos para definir o conjunto de caracteres, idioma da página de pagamento, moeda utilizada na transação, etc. Abaixo, a lista dessas variáveis:

Nome da variável Significado
charset Conjunto de caracteres. Para o Brasil, podemos utilizar valor UTF-8
lc Locale code, ou código da localização. Para o Brasil, devemos utilizar BR
currency_code Código de câmbio, ou a moeda que será utilizada. Para o Brasil, devemos utilizar BRL

Criando um botão Comprar Agora

O código abaixo ilustra a criação de um botão Comprar Agora com seus campos já definidos.

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<!--Tipo do botão-->
<input type="hidden" name="cmd" value="_xclick" />
<!--Vendedor e URL de retorno, cancelamento e notificação-->
<input type="hidden" name="business" value="vendedor@loja.com.br" />
<input type="hidden" name="return" value="http://loja.com.br/retorno" />
<input type="hidden" name="cancel" value="http://loja.com.br/cancelamento" />
<input type="hidden" name="notify_url" value="http://loja.com.br/notificacao" />
<!--Internacionalização e localização da página de pagamento-->
<input type="hidden" name="charset" value="utf-8" />
<input type="hidden" name="lc" value="BR" />
<input type="hidden" name="country_code" value="BR" />
<input type="hidden" name="currency_code" value="BRL" />
<!--Informações sobre o produto e seu valor-->
<input type="hidden" name="amount" value="172.00" />
<input type="hidden" name="item_name" value="Servico" />
<input type="hidden" name="quantity" value="1" />
<!--Botão para submissão do formulário-->
<input type="image" src="https://www.paypalobjects.com/pt_BR/BR/i/btn/btn_buynowCC_LG.gif" border="0" />
</form>

No exemplo acima, encontraremos diversas variáveis que configuram o botão. Abaixo, a descrição de cada uma delas:

Nome da variável Significado
cmd Especifica o tipo do botão. No exemplo foi especificado o botão Comprar Agora.
business Especifica o vendedor. Esse campo deve ser populado com o email da conta PayPal do vendedor.
return, cancel e notify_url Especifica as URLs de retorno, cancelamento e notificação. A URL de retorno é utilizada quando o cliente faz o pagamento. A URL de cancelamento é utilizada quando o cliente desiste da compra. A URL de notificação é utilizada quando uma transação muda de estado, por exemplo, de pendente para autorizada.
charset Especifica o conjunto de caracteres. Para o Brasil, por padrão, podemos definir como UTF-8.
lc Especifica o código de localização. Para o Brasil, definimos como BR.
country_code Especifica o código do país. Para o Brasil, definimos como BR.
currency_code Especifica o código da moeda. Para o Brasil, definimos como BRL.
amount Especifica o valor do produto.
item_name Especifica o nome do produto.
quantity Especifica a quantidade de itens que o cliente está comprando.

Tela de redirecionamento e a experiência do usuário

Ao clicar no botão de pagamento, o cliente será redirecionado ao ambiente seguro da PayPal, que garante maior segurança no momento do pagamento. Muitas vezes, o cliente não sabe o que está acontecendo e, por isso, exibir a mensagem de redirecionamento, avisando-o sobre o que ocorrerá em seguida, garante maior conversão de vendas (numero de visitantes x numero de compradores).

Por padrão, ao clicar em um botão de formulário, causará a submissão do formulário. Para exibir a mensagem de redirecionamento, precisaremos interceptar o clique no botão, exibir a mensagem e, então, submeter o formulário. Abaixo, um código completo de uma página HTML contendo o mesmo botão ilustrado no exemplo acima, mas agora com a mensagem de redirecionamento.

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<title>Código de exemplo do botão Comprar Agora</title>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script type="text/javascript">
jQuery(document).ready(function(){
//Pegamos o formulário do botão
var wpsBn = jQuery('#wps-bn');
//Interceptamos o clique no botão
wpsBn.click(function(e){
//Evitamos o comportamento padrão, de submeter o formulário
e.preventDefault();
//Mostramos a mensagem de redirecionamento
jQuery('<div class="sa_payPal_overlay" style="visibility:visible;position:fixed; width:100%; height:100%; filter:progid:DXImageTransform.Microsoft.Gradient(GradientType=1, StartColorStr=\'#88ffffff\', EndColorStr=\'#88ffffff\'); background: rgba(255,255,255,0.8); top:0; left:0; z-index: 999999;"><div style=" background: #FFF; background-image: linear-gradient(top, #FFFFFF 45%, #E9ECEF 80%);background-image: -o-linear-gradient(top, #FFFFFF 45%, #E9ECEF 80%);background-image: -moz-linear-gradient(top, #FFFFFF 45%, #E9ECEF 80%);background-image: -webkit-linear-gradient(top, #FFFFFF 45%, #E9ECEF 80%);background-image: -ms-linear-gradient(top, #FFFFFF 45%, #E9ECEF 80%);background-image: -webkit-gradient(linear, left top,left bottom,color-stop(0.45, #FFFFFF),color-stop(0.8, #E9ECEF));display: block;margin: auto;position: fixed; margin-left:-220px; left:45%;top: 40%;text-align: center;color: #2F6395;font-family: Arial;padding: 15px;font-size: 15px;font-weight: bold;width: 530px;-webkit-box-shadow: 3px 2px 13px rgba(50, 50, 49, 0.25);box-shadow: rgba(0, 0, 0, 0.2) 0px 0px 0px 5px;border: 1px solid #CFCFCF;border-radius: 6px;"><img style="display:block;margin:0 auto 10px" src="https://www.paypalobjects.com/en_US/i/icon/icon_animated_prog_dkgy_42wx42h.gif"><h2>Aguarde alguns segundos.</h2> <p style="font-size:13px; color: #003171; font-weight:400">Você está sendo redirecionado para um ambiente seguro do PayPal<br /> para finalizar seu pagamento.</p><div style="margin:30px auto 0;"><img src="https://www.paypal-brasil.com.br/logocenter/util/img/logo_paypal.png"/></div></div></div>').appendTo('body');
//Submetemos o formulário após a exibição da mensagem
wpsBn.submit();
});
});
</script>
</head>
<body>
<form id="wps-bn" action="https://www.sandbox.paypal.com/cgi-bin/webscr" method="post">
<!--Tipo do botão-->
<input type="hidden" name="cmd" value="_xclick" />
<!--Vendedor e URL de retorno, cancelamento e notificação-->
<input type="hidden" name="business" value="teste@empresa.com.br" />
<input type="hidden" name="return" value="http://loja.com.br/retorno" />
<input type="hidden" name="cancel" value="http://loja.com.br/cancelamento" />
<input type="hidden" name="notify_url" value="http://loja.com.br/notificacao" />
<!--Internacionalização e localização da página de pagamento-->
<input type="hidden" name="charset" value="utf-8" />
<input type="hidden" name="lc" value="BR" />
<input type="hidden" name="country_code" value="BR" />
<input type="hidden" name="currency_code" value="BRL" />
<!--Informações sobre o produto e seu valor-->
<input type="hidden" name="amount" value="172.00" />
<input type="hidden" name="item_name" value="Servico" />
<input type="hidden" name="quantity" value="1" />
<!--Botão para submissão do formulário-->
<input type="image" src="https://www.paypalobjects.com/pt_BR/BR/i/btn/btn_buynowCC_LG.gif" border="0" />
</form>
</body>
</html>

Com isso, ao clicar no botão, o cliente verá uma mensagem com a abaixo:

Para mais informações sobre a mensagem de redirecionamento, veja o seguinte artigo: Mensagem de redirecionamento para a tela de pagamento.