O Instant Update tem como finalidade, atualizar o frete no momento do Checkout, na página de Review do lado PayPal.

Funciona através de chamadas de AJAX em comunicação entre o servidor do Merchant e o servidor PayPal. O servidor PayPal durante o checkout envia uma chamada de POST para o servidor do Merchant com as informações de entrega, tais como endereço completo (rua, número, complemento, bairro, cidade, estado e cep). Após o recebimento de tais informações é necessário que o cálculo do frete seja executado do lado do Merchant e seja retornado como resposta a requisição da PayPal no formato adequado.

Funcionamento

1. Quando o comprador faz login em sua conta PayPal, o servidor da PayPal faz uma chamada para o servidor da sua aplicação, enviando o endereço de entrega padrão do cliente, que foi cadastrado na PayPal;
2. Assim que a aplicação recebe a chamada da PayPal, ela deverá responder com as opções de entrega disponíveis para aquele endereço, assim como opções de seguro, taxas, etc, que serão utilizadas para atualizar os valores da transação;
3. A PayPal irá exibir a informação recebia, na página de revisão de pagamento, assim o comprador poderá escolher entre as opções de entrega;
4. A escolha do comprador será enviada de volta para a loja, através da resposta da operação GetExpressCheckoutDetails.

A imagem abaixo ilustra o fluxo de funcionamento:

Premissas:

• Servidor com capacidade robusta de resposta em até três segundos com as novas informações de frete, e para concorrência de acesso múltiplo de compradores;
• Capacidade de cálculo de frete dinâmico e padrão.

Configurando o Callback

Callback, para o Instant Update, é a parte na sua aplicação que receberá as chamadas da PayPal, solicitando as informações sobre opções de entrega. O primeiro passo para configurá-lo corretamente, é estabelecer uma conexão com PayPal, informando a URL do callback, para onde a PayPal enviará as requisições para seu servidor.

Para começar, você precisa ter um servidor operando de forma segura (SSL), ser confiável e capaz de responder rapidamente à chamada da PayPal, calculando dinamicamente os valores de frete, seguro e taxas, de acordo com suas regras de negócio.

Atenção! No ambiente de produção, é requerido que o callback esteja operando em SSL (HTTPS.

Primeiros passos

Na operação SetExpressCheckout, você precisa seguir os passos 1 até 3. Os passos 4 e 5 são opcionais.

• 1. Defina os detalhes de cada produto que o cliente estiver comprando.
• 2. Defina a URL para seu callback, o qual a PayPal validará.
• 3. Defina os valores de frete para as opções de entrega. Para cada opção de entrega (PAC, Sedex, etc), você deverá especificar:4. Se necessário, ajuste o valor das taxas através do PAYMENTREQUEST_n_TAXAMT
  • Nome da opção de entrega L_SHIPPINGOPTIONNAMEn
  • Valor do frete para a opção de entrega L_SHIPPINGOPTIONAMOUNTn
  • A opção de entrega deverá aparecer como padrão? L_SHIPPINGOPTIONISDEFAULTn.
    Nota: Defina o campo L_SHIPPINGOPTIONISDEFAULTn como true em apenas uma das opções de entrega. Todas as outras opções deverão ser definidas como false.
• 5. Se necessário, ajuste o valor do seguro através do PAYMENTREQUEST_n_INSURANCEAMT
• 6. Se necessário, ajuste o tempo de resposta do callback (o padrão é de 3 segundos). Defina um valor entre 1 segundo e 6 segundos, através do CALLBACKTIMEOUT
• 7. Se necessário, defina os detalhes da opção de entrega, através dos campos:
  • Peso do pacote: L_PAYMENTREQUEST_n_ITEMWEIGHTVALUEm
  • Unidade de medida do peso: L_PAYMENTREQUEST_n_ITEMWEITHTUNITm
  • Altura do pacote: L_PAYMENTREQUEST_n_ITEMHEIGHTVALUEm
  • Unidade de medida da altura: L_PAYMENTREQUEST_n_ITEMHEIGHTUNITm
  • Comprimento do pacote: L_PAYMENTREQUEST_n_ITEMLENGTHVALUEm
  • Unidade de medida do comprimento: L_PAYMENTREQUEST_n_ITEMLENGTHUNITm
  • Largura do pacote: L_PAYMENTREQUEST_n_ITEMWIDTHVALUEm
  • Unidade de medida da largura: L_PAYMENTREQUEST_n_ITEMWIDTHUNITm

GetExpressCheckoutDetails e DoExpressCheckoutPayment

Quando você faz a integração com Express Checkout, você precisa fazer chamadas ao GetExpressCheckoutDetails e DoExpressCheckoutPayment. Para suportar a API do Instant Update, as operações GetExpressCheckoutDetails e DoExpressCheckoutPayment incluem novos campos.

Por padrão, a operação GetExpressCheckoutDetails retorna os dados do cliente. Agora, a operação também retorna a opção de entrega selecionada pelo cliente.

Como a informação do carrinho, passada na operação SetExpressCheckout é relevante apenas para exibição na página de revisão de pagamento, você precisa chamar a operaçãoDoExpressCheckoutPayment com o valor atualizado do frete, seguro, taxas, etc.

Timeout

Se o callback não responder dentro do tempo apropriado, a PayPal irá exibir o valor fixo para o frete na página de revisão de pagamento. Esse valor é especificado durante a chamada aoSetExpressCheckout.

Número de opções de entrega

Você pode especificar até 10 opções de entrega na chamada SetExpressCheckout e no detalhamento das opções, baseadas no endereço do cliente, na resposta do callback. Você precisa especificar pelo menos 1 opção de entrega.

Endereço não entregável

É possível que, por algum motivo, não seja possível entregar o produto no endereço especificado pelo cliente. Nesses casos, envie na resposta do callback o campo NO_SHIPPING_OPTION_DETAILSdefinido como 1.

Nota: O valor do campo CALLBACKVERSION deve ser definido como 61.0 ou maior na operaçãoSetExpressCheckout. Abaixo, um exemplo de resposta para casos onde não é possível entregar no endereço informado pelo cliente:

METHOD=CallbackResponse&
NO_SHIPPING_OPTION_DETAILS=1&
CALLBACKVERSION=61.0

Quando o callback envia a resposta acima, a página de revisão de pagamento mostrará:

• Uma mensagem no topo da página indicando que não é possível entregar no endereço especificado.
• A seção onde os valores de entrega e manipulação fica esmaecida, mostrando que está desabilitada.
• O comprador pode indicar um outro endereço de entrega.
• Uma nova chamada ao callback é feita, assim que o comprador modificar o endereço de entrega.

Implementando o Instant Update

Para implementar o callback, você precisará, antes, adicionar alguns campos na operaçãoSetExpressCheckout, fornecendo a URL para onde a PayPal enviará as requisições ao callback. Além disso, todas as respostas do callback deverão utilizar o formato NVP (par nome=valor).

SetExpressCheckout

Na operação SetExpressCheckout, defina os seguintes campos:

• Defina o campo CALLBACK com a URL para onde a PayPal enviará as chamadas. A PayPal enviará requisições ao callback, via HTTPS, sempre que algum dos eventos ocorrer:
  • O comprador modificar o endereço de entrega.
  • O comprador informar um novo endereço de entrega.
• Defina os valores para os seguintes campos:
  • Defina os detalhes para cada um dos itens, como L_PAYMENTREQUEST_n_NAMEm,L_PAYMENTREQUEST_n_NUMBERm, L_PAYMENTREQUEST_n_DESCm,L_PAYMENTREQUEST_n_AMTm e L_PAYMENTREQUEST_n_QTYm.
  • Defina o valor padrão do frete, que será utilizado em caso de falhas:L_SHIPPINGOPTIONISDEFAULTn, L_SHIPPINGOPTIONNAMEn e L_SHIPPINGOPTIONAMOUNTn.
  • Defina o campo PAYMENTREQUEST_n_SHIPPINGAMT com o valor total do frete para a opção padrão. Se, por exemplo, L_SHIPPINGOPTIONISDEFAULT0=true eL_SHIPPINGOPTIONAMOUNT0=8.00, então o campo PAYMENTREQUEST_0_SHIPPINGAMTdeverá ser informado com o valor 8.00.
  • Defina o campo MAXAMT com o valor total esperado.Nota:A PayPal recomenda que o valor máximo total seja um pouco maior que a soma dos itens, taxas e o valor total da maior opção de entrega.
• Opcionalmente, informe os seguintes campos:
  • Defina o campo PAYMENTREQUEST_n_INSURANCEOPTIONOFFERED como true para informar à PayPal que você está oferecendo opção de seguro. Do contrário, informe o campoPAYMENTREQUEST_n_INSURANCEOPTIONSOFFERED como false.
  • Defina detalhes das dimensões dos produtos, como o campoL_PAYMENTREQUEST_n_ITEMWEIGHTUNIT0 e L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE0.
  • Defina o campo CALLBACKTIMEOUT com o tempo em segundos necessário para processar a requisição. Por padrão, o timeout é de 3 segundos, mas você pode definir esse valor entre 1 e 6 segundos.

Abaixo, um exemplo de requisição ao SetExpressCheckout:

PAYMENTREQUEST_0_PAYMENTACTION=Sale&
MAXAMT=400.00&
PAYMENTREQUEST_0_AMT=120.00&
PAYMENTREQUEST_0_CURRENCYCODE=BRL&
PAYMENTREQUEST_0_ITEMAMT=100.00&
L_PAYMENTREQUEST_0_NAME0=Notebook Acer&
L_PAYMENTREQUEST_0_NUMBER0=765&
L_PAYMENTREQUEST_0_DESC0=O mais estavel&
L_PAYMENTREQUEST_0_AMT0=50.00&
L_PAYMENTREQUEST_0_QTY0=1&
L_PAYMENTREQUEST_0_NAME1=Notebook Dell&
L_PAYMENTREQUEST_0_NUMBER1=987&
L_PAYMENTREQUEST_0_DESC1=O mais bonito&
L_PAYMENTREQUEST_0_AMT1=50.00&
L_PAYMENTREQUEST_0_QTY1=1&
PAYMENTREQUEST_0_SHIPPINGAMT=20.00&
CALLBACKTIMEOUT=500&
CALLBACKVERSION=61&
CALLBACK=http://....&
BRANDNAME=PP - TESTE&
L_SHIPPINGOPTIONNAME0=PAC&
L_SHIPPINGOPTIONAMOUNT0=20.00&
L_SHIPPINGOPTIONISDEFAULT0=true&
L_SHIPPINGOPTIONNAME1=Sedex&
L_SHIPPINGOPTIONAMOUNT1=15.00&
L_SHIPPINGOPTIONISDEFAULT1=false&
L_SHIPPINGOPTIONNAME2=e-Sedex&
L_SHIPPINGOPTIONAMOUNT2=10.00&
L_SHIPPINGOPTIONISDEFAULT2=false&

Callback

A PayPal enviará alguns parâmetros na requisição do callback, para a URL especificada para seu callback. Essa requisição incluirá:

• Detalhes dos itens que foram enviados na operação SetExpressCheckout. A PayPal também enviará qualquer detalhe sobre as dimensões do produto, que você tenha enviado anteriormente, como L_ITEMWEIGHTUNIT1 e L_ITEMWEIGHTVALUE1. O envio dessas informações, facilitará seu trabalho de cálculo de frete, eliminando, por exemplo, a necessidade de uma consulta em uma base de dados, em busca das dimensões do produto.
• Endereço de entrega do comprador.

Com as informações que a PayPal enviará para seu callback, calcule o frete segundo suas regras de negócio e, então, devolta os valores do frete, seguro e taxas na resposta do callback.

Abaixo, um exemplo de requisição que a PayPal enviará para seu callback:

METHOD=CallbackRequest
&CALLBACKVERSION=61.0
&TOKEN=EC-F98ASDF0987AS
&CURRENCYCODE=BRL
&LOCALECODE=pt_BR
&L_NAME0=Notebook+Acer
&L_NUMBER0=765
&L_DESC0=O+mais+estavel
&L_AMT0=50.00
&L_QTY0=1
&L_NAME1=Notebook+Dell
&L_NUMBER1=987
&L_DESC1=O+mais+bonito
&L_AMT1=50.00
&L_QTY1=1
&L_ITEMWEIGHTUNIT1=lbs
&L_ITEMWEIGHTVALUE1=0.5
&SHIPTOSTREET=Rua do cliente
&SHIPTOCITY=Cidade do cliente
&SHIPTOSTATE=SP
&SHIPTOCOUNTRY=BR
&SHIPTOZIP=14400000

Com essa requisição, sua aplicação deverá calcular o valor do frete e responder como no exemplo abaixo:

METHOD=CallbackResponse
&OFFERINSURANCEOPTION=true
&L_SHIPPINGOPTIONNAME0=Sedex
&L_SHIPPINGOPTIONAMOUNT0=20.00
&L_TAXAMT0=2.20
&L_INSURANCEAMOUNT0=1.51
&L_SHIPPINGOPTIONISDEFAULT0=false
&L_SHIPPINGOPTIONNAME1=PAC
&L_SHIPPINGOPTIONAMOUNT1=10.00
&L_TAXAMT1=2.00
&L_INSURANCEAMOUNT1=1.35
&L_SHIPPINGOPTIONISDEFAULT1=true
&L_SHIPPINGOPTIONNAME2=Sedex-10
&L_SHIPPINGOPTIONAMOUNT2=9.99
&L_TAXAMT2=1.99
&L_INSURANCEAMOUNT2=1.28
&L_SHIPPINGOPTIONISDEFAULT2=false

Atenção: as mensagens enviadas pela PayPal, utilizam o conjunto de caracteres Win-2512. Se sua aplicação utilizar outro conjunto de caracteres, como UTF-8, veja o seguinte passo a passo para atualização: Configurando o conjunto de caracteres para troca de mensagens.