Serviço de Notificação Instantânea

O ClickBank oferece um serviço de notificação instantânea que notifica você quando ocorrem transações em sua conta dentro do sistema ClickBank. O sistema envia dados para você quase em tempo real no caso destes eventos:

  • Venda – Venda de um produto padrão ou venda inicial de um produto recorrente.
  • Cobrança recorrente – Cobrança recorrente de um produto recorrente.
  • Reembolso – Reembolso de um produto padrão ou recorrente.
  • Estorno – Estorno de um produto padrão ou recorrente.
  • Cancelamento de cobrança recorrente – O cancelamento de um produto recorrente.
  • Desfazer cancelamento de cobrança recorrente – A reversão do cancelamento de um produto recorrente por um representante do serviço ao consumidor do ClickBank.
  • Teste de transação – Teste dos tipos de transação listados acima, ou um teste do recurso de notificação instantânea que você iniciar.

O serviço tenta publicar a informação pelo método POST de HTML FORM em um URL especificado por você. Cada postagem contém um grupo de parâmetros de URL relevantes para a transação. A notificação é criptografada e, antes de ser processada, precisa ser decodificada usando sua chave secreta e o vetor de inicialização.

NOTA: este serviço deve ser usado por programadores com experiência. Se você não tiver experiência com programação, encontre um desenvolvedor que possa ajudar antes de habilitar as notificações instantâneas.

Os tópicos a seguir são abordados neste artigo:

Visão geral

Quando habilitado, o serviço de notificação instantânea é acionado sempre que uma transação é criada ou uma ação é realizada em relação a uma transação na sua conta do ClickBank. O fluxo primário envolve as seguintes etapas:

  1. Ocorre uma ação no sistema ClickBank (como uma venda ou uma cobrança recorrente).
  2. O ClickBank criptografa uma notificação usando sua chave secreta e um vetor de inicialização.
  3. O ClickBank publica os parâmetros de HTML FORM em um URL que você especifica.
    O URL deve usar os protocolos de segurança Transport Layer Security (TLS) ou Secure Socket Layer (SSL).
  4. O ClickBank usa monitoramento de código de resposta para verificar se a notificação foi recebida.
  5. Um aplicativo criado por você decodifica a mensagem (usando sua chave secreta e o vetor de inicialização) e processa os parâmetros da publicação.

A configuração do serviço na sua conta ClickBank é simples e fácil. No entanto, você também precisa criar um aplicativo que processe os parâmetros de URL da notificação instantânea, o que é uma tarefa mais técnica. Para utilizar adequadamente o serviço, seu aplicativo deve ao menos codificar a mensagem e processar os parâmetros informados na seção Parâmetros deste documento.

Se você não compreender todas essas etapas, recomendamos entrar em contato com um desenvolvedor que possa ajudar. Se as notificações instantâneas forem implementadas incorretamente, poderemos desabilitar ou remover o recurso da sua conta. 

Versão atual

A versão atual do recurso de notificação instantânea é 6.0.

Os novos recursos da versão 6.0 incluem:

  • Notificações criptografadas
  • Parâmetros que indicam o tipo de pedido incluído na compra (como um complemento do pedido ou uma venda adicional)
  • Parâmetro de quantidade
  • Parâmetros variáveis específicos de cada fornecedor

Formato das notificações

Esta seção descreve o formato das notificações instantâneas enviadas a você.

Estrutura básica

As notificações instantâneas são criadas em formato JSON. Elas são criptografadas antes do envio.

A estrutura básica de uma notificação instantânea é esta:

{"notification": "<ENCRYPTED_NOTIFICATION>", "iv": "<INITIALIZATION_VECTOR>"}

Criptografia

O ClickBank usa o algoritmo de criptografia CBC-AES-256 para garantir o carregamento seguro da notificação. Isso ajuda a impedir que as informações do cliente sejam transmitidas em forma de texto e permite que o recebedor da notificação saiba que a mensagem foi originada no ClickBank e não foi alterada durante o envio. A notificação é criptografada usando uma chave secreta de até 16 caracteres e um vetor de inicialização.

Diversos exemplos de como decodificar a notificação estão listados na seção Exemplos de códigos, mas recomendamos que você se familiarize com o algoritmo de criptografia AES-256 para entender melhor como ele funciona.

A mensagem inicial em JSON contém uma representação da string de notificação criptografada e o vetor de inicialização que pode ser usado em paralelo com a chave secreta do ClickBank para decodificar a notificação.

Parâmetros

Esta seção descreve os parâmetros usados em uma notificação.

Uma notificação enviada inclui todos os parâmetros. Se um parâmetro não tiver valor, a string da notificação instantânea incluirá a tag do parâmetro sem valor. É por isso que o número de caracteres de alguns parâmetros inclui um valor zero, já que esses parâmetros podem não conter valor.

Parâmetros de cabeçalho

Parâmetro

Descrição

Caracteres / Formato

Destinatário

transactionTime

Horário da transação em formato RFC-3339

25

Todos

receipt

ID de recibo do ClickBank

8-21

Todos

transactionType

O tipo de transação.

4-15 – Ver Tipos de transação

Todos

vendor

Apelido do fornecedor

5-10

Todos

affiliate

Apelido do afiliado

5-10

Todos

role

Sua função na transação

6-9 – VENDOR, AFFILIATE, or JV_VENDOR

Todos

totalAccountAmount

Total que você recebeu na transação em USD

Numérico com duas casas decimais

Todos

paymentMethod

Método de pagamento usado pelo cliente.

3-4 – Ver Métodos de pagamento

Todos

totalOrderAmount

Total cobrado do cliente

Numérico com duas casas decimais

Todos

totalTaxAmount

Total de impostos pagos pelo cliente

Numérico com duas casas decimais

Fornecedor

totalShippingAmount 

Total do frete pago pelo cliente

Numérico com duas casas decimais

Fornecedor

currency

Moeda em que o usuário pagou

3

Fornecedor

orderLanguage

Idioma usado no formulário do pedido

2 – DE, EN, ES, FR, IT, or PT

Fornecedor

trackingCodes

Códigos de rastreamento transmitidos para o formulário do pedido.

0-24 cada

Fornecedor, afiliado

Parâmetros do produto

Parâmetro

Descrição

Caracteres / Formato

Destinatário

itemNo

SKU do produto encomendado

1-10

Todos

productTitle

Título do produto

0-255

Todos

shippable

Se o produto era um bem físico

4-5 – true ou false

Todos

recurring

Se o produto era fornecido por meio de assinatura

4-5 – true ou false

Todos

accountAmount

Valor que você recebeu neste item de linha

Numérico com duas casas decimais 

Todos

quantity

Quantidade do item comprado

Numérico

Todos

downloadUrl

URL de download do produto para o cliente

0-255

Fornecedor

lineItemType

Tipo de pedido do qual o item de linha fazia parte

4-8 – ORIGINAL, CART, BUMP, TOKEN, or UPSELL

Todos

Parâmetros de envio do cliente

Parâmetro

Descrição

Caracteres

Destinatário

firstName

Nome do cliente

0-255

Fornecedor

lastName

Sobrenome do cliente

0-255

Fornecedor

fullName

Nome e sobrenome do cliente

0-255

Fornecedor

phoneNumber

Telefone do cliente

0-255

Fornecedor

email

Endereço de e-mail do cliente

0-255

Fornecedor

address1

Endereço de correspondência do cliente (linha 1)

0-255

Fornecedor

address2

Endereço de correspondência do cliente (linha 2)

0-255

Fornecedor

city

Cidade do cliente

0-255

Fornecedor

county

Condado do cliente

0-255

Fornecedor

state

Estado do cliente

0-255

Fornecedor

postalCode

CEP do cliente

0-255

Fornecedor

country

País do cliente

0-255

Fornecedor

Parâmetros de faturamento do cliente

Parâmetro

Descrição

Caracteres

Destinatário

firstName

Nome do cliente

0-255

Fornecedor

lastName

Sobrenome do cliente

0-255

Fornecedor

fullName

Nome e sobrenome do cliente

0-255

Fornecedor

phoneNumber

Telefone do cliente

0-255

Fornecedor

email

Endereço de e-mail do cliente

0-255

Fornecedor

state

Estado do cliente

0-255

Todos

postalCode

CEP do cliente

0-255

Todos

country

País do cliente

0-255

Todos

Parâmetros de venda adicional

Parâmetro

Descrição

Caracteres

Destinatário

upsellOriginalReceipt

Número do recibo que iniciou o fluxo de vendas adicionais

8-21

Todos

upsellFlowId

ID do fluxo de vendas adicionais

Número inteiro

Fornecedor

upsellSession

ID da sessão de venda adicional

0-16

Fornecedor

upsellPath

Caminho da venda adicional

0-12

Fornecedor

Parâmetros de Pytch

NOTA – O recurso Pytch foi removido, mas os parâmetros foram mantidos para fins de compatibilidade com versões anteriores.

Parâmetro

Descrição

Caracteres / Formato

Destinatário

hopfeedClickId

Nome do ID de clique em hopfeed 

String 

Todos

hopfeedApplicationId

ID do aplicativo

Numérico 

Todos

hopfeedCreativeId

ID da peça criativa 

Numérico 

Todos

hopfeedApplicationPayout

Valor pago pelo aplicativo 

Numérico com duas casas decimais 

Todos

hopfeedVendorPayout

Valor pago ao fornecedor 

Numérico com duas casas decimais 

Todos

Parâmetros técnicos

Parâmetro

Descrição

Formato

Destinatário

version

A versão da notificação instantânea.

Numérico duplo

Todos

attemptCount

O número de vezes que o ClickBank tentou enviar essa notificação antes de receber uma resposta de sucesso ou falha por excesso de tentativas

Número inteiro

Todos

Parâmetros do fornecedor

Se o fornecedor tiver oferecido outras variáveis no link de pagamento, elas também serão oferecidas na notificação como parâmetros (chamados de v1, v2 e assim por diante).

Tipos de transação

Diversos valores podem ser exibidos no parâmetro transactionType. Esses valores estão listados abaixo com uma breve descrição de cada um.

NOTA – As notificações dos testes de transação são enviadas apenas ao fornecedor.

Tipo

Descrição

SALE

Compra de um produto padrão ou a compra inicial de um produto recorrente.

BILL

Cobrança recorrente de um produto de cobrança recorrente.

RFND

Reembolso de um produto padrão ou de cobrança recorrente. Os produtos de cobrança recorrente que são reembolsados também geram uma transação do tipo “CANCEL-REBILL”.

CGBK

Estorno de um produto padrão ou recorrente.

INSF

Estorno por cheque eletrônico de um produto padrão ou recorrente.

CANCEL-REBILL

Cancelamento de um produto de cobrança recorrente. Os produtos de cobrança recorrente que são cancelados não geram outras ações.

UNCANCEL-REBILL

Reversão do cancelamento de um produto de cobrança recorrente.

TEST

Teste de transação acionado durante a configuração.

TEST_BILL

Teste de cobrança recorrente para um produto de cobrança recorrente.

TEST_RFND

Teste de reembolso de um produto padrão ou de cobrança recorrente.

TEST_SALE

Teste de compra de um produto padrão ou de cobrança recorrente.

CANCEL-TEST-REBILL

Teste de cancelamento de um produto recorrente.

UNCANCEL-TEST-REBILL

Teste de reversão do cancelamento de um produto recorrente.

Métodos de pagamento

Diversos valores podem ser exibidos no parâmetro paymentMethod. Esses valores estão listados abaixo.

Parâmetro de método de pagamento

Método de pagamento

PYPL

PayPal

VISA

Visa

MSTR

MasterCard

DISC

Discover

AMEX

American Express

SOLO

Solo

JCBC

JCB

DNRS

Diners Club

MAES

Maestro

ELV

European Direct Debit

TEST

Teste de pagamento

Exemplo de notificação

Este é um exemplo de notificação não criptografada em JSON que mostra a estrutura dos pares de chave-valor da versão 6.0 da Notificação instantânea. 

 {
    "transactionTime": "2016-06-05T13:47:51-06:00",
    "receipt": "CWOGBZLN",
    "transactionType": "SALE",
    "vendor": "testacct",
    "affiliate": "affiliate1",
    "role": "VENDOR",
    "totalAccountAmount": 0.00,
    "paymentMethod": "VISA",
    "totalOrderAmount": 0.00,
    "totalTaxAmount": 0.00,
    "totalShippingAmount": 0.00,
    "currency": "USD",
    "orderLanguage": "EN",
    "trackingCodes": [
        "tracking_code"
    ],
    "lineItems": [
        {
            "itemNo": "1",
           "productTitle": "Product Title",
            "shippable": false,
            "recurring": false,
            "accountAmount": 5.00,
            "quantity": 1,
            "downloadUrl": "<download_url>"
            "lineItemType": "CART"
      }         {
            "itemNo": "2",
           "productTitle": "Second Product",
            "shippable": false,
            "recurring": true,
            "accountAmount": 2.99,
            "quantity": 1,
            "downloadUrl": "<download_url>"
            "lineItemType": "CART"
      }
   ],
    "customer": {
        "shipping": {
            "firstName": "TEST",
            "lastName": "GUY",
            "fullName": "Test Guy",
            "phoneNumber": "",
            "email": "test@example.net",
            "address": {
                "address1": "12 Test Lane",
                "address2": "Suite 100",
                "city": "LAS VEGAS",
                "county": "LAS VEGAS",
                "state": "NV",
                "postalCode": "89101",
                "country": "US"
            }
        },
        "billing": {
            "firstName": "TEST",
            "lastName": "GUY",
            "fullName": "Test Guy",
            "phoneNumber": "",
            "email": "test@example.net",
            "address": {
                "state": "NV",
                "postalCode": "89101",
                "country": "US"
            }
        }
    },
    "upsell": {
        "upsellOriginalReceipt": "XXXXXXXX",
        "upsellFlowId": 55,
        "upsellSession": "VVVVVVVVVV",
        "upsellPath": "upsell_path"
    },
    "hopfeed": {
        "hopfeedClickId": "hopfeed_click",
        "hopfeedApplicationId": 0000,
        "hopfeedCreativeId": 0000,
        "hopfeedApplicationPayout": 0.00,
        "hopfeedVendorPayout": 0.00
    },
    "version": 6.0,
    "attemptCount": 1,
    "vendorVariables": {
       "v1": "variable1", 
       "v2": "variable2" 
    }
}

Implementação

Depois de entender corretamente o conteúdo da seção anterior deste documento, você poderá solicitar acesso ao recurso Notificação instantânea, testar seu URL e habilitar as notificações instantâneas.

Depois de configurar um URL para as notificações instantâneas, você pode adicionar outro usando estes procedimentos com o campo “Notificação instantânea 2”.

Solicitação de acesso às notificações instantâneas

O recurso Notificação instantânea não é habilitado automaticamente. Para solicitar acesso:

  1. Faça login em sua conta.
  2. Clique na guia Configurações.
  3. Clique em Meu site.
  4. Localize a seção Ferramentas avançadas e clique em Editar.
  5. Clique no link Solicitar acesso ao lado do campo de URL da notificação instantânea.
  6. Preencha o formulário, revise cuidadosamente os termos de uso e reconheça que você leu e concordou com os termos de uso.
  7. Clique no botão Salvar as alterações e solicitar acesso à API na parte inferior do formulário.
  8. Clique no botão Salvar as alterações.

Configuração do URL

Depois de receber acesso ao recurso Notificação instantânea, você deve criar um URL de destino e um programa para processar as notificações que serão enviadas ao URL. É possível usar as portas 80 ou 443.

Transport Layer Security (TLS) e Secure Socket Layer (SSL)

É altamente recomendável que você use esse recurso com o protocolo de segurança Transport Layer Security (TLS) ou Secure Socket Layer (SSL) habilitado. O uso do recurso sem habilitar TLS ou SSL pode expor seus dados de venda a ladrões. No entanto, como as informações bancárias e de cartão de crédito não são transmitidas pelo serviço de notificação instantânea, não exigimos o uso de TLS ou SSL para criptografar as transmissões de notificações instantâneas.

NOTA – Não é possível usar um certificado SSL com assinatura própria. É preciso usar um certificado válido.

Teste de conectividade e processamento

Antes de habilitar as notificações instantâneas, você deve testar a conectividade e o correto processamento dos parâmetros de URL entre o ClickBank e seu servidor. Para realizar esse teste:

  1. Faça login em sua conta.
  2. Clique na guia Configurações.
  3. Clique em Meu site.
  4. Localize a seção Ferramentas avançadas e clique em Editar.
  5. Digite seu URL no campo URL de notificação instantânea.
    NOTA – Não clique em Salvar as alterações.
  6. Clique em Testar à direita do URL.
    Uma notificação de teste é enviada com um recibo de ******* e uma transação de tipo TEST.
  7. Leia a resposta na janela pop-up para verificar se o teste foi realizado corretamente.

Se não tiver sido, remova o URL do campo Notificação instantânea e resolva os possíveis problemas de conectividade ou do aplicativo.

NOTA – Preencha o campo Notificação instantânea apenas quando conseguir realizar corretamente um teste. Caso contrário, seu acesso ao recurso poderá ser desabilitado.

Habilitação das notificações instantâneas

Depois de garantir o acesso ao recurso e realizar corretamente um teste, você poderá habilitar as notificações instantâneas para começar a recebê-las. Para habilitar as notificações instantâneas:

  1. Faça login em sua conta.
  2. Clique na guia Configurações.
  3. Clique em Meu site.
  4. Localize a seção Ferramentas avançadas e clique em Editar.
  5. Digite sua chave secreta no campo Chave secreta. Sua chave secreta pode ter até 16 caracteres e deve ser digitada inteiramente em caracteres maiúsculos. Consulte a seção Criptografia para saber mais detalhes.
  6. Digite seu URL no campo URL de notificação instantânea.
  7. Clique em Testar à direita do URL.
    Uma notificação de teste é enviada com um recibo de ******* e uma transação de tipo TEST.
  8. Leia a resposta na janela pop-up para verificar se o teste foi realizado corretamente.
  9. Clique em Salvar as alterações.

As transmissões de notificações instantâneas começarão imediatamente após a conclusão da configuração.

Como desabilitar as notificações instantâneas

É possível desabilitar o recurso para impedir que as notificações sejam enviadas. Para isso, basta remover o URL. Você poderá habilitar o recurso de novo futuramente.

  1. Faça login em sua conta.
  2. Clique na guia Configurações.
  3. Clique em Meu site.
  4. Localize a seção Ferramentas avançadas e clique em Editar.
  5. Remova o URL do campo URL de notificação instantânea.
  6. Clique em Salvar as alterações.

Monitoramento de código de resposta

Ao enviarmos uma notificação instantânea, sempre monitoramos o código de resposta do seu URL. Se o código de resposta estiver na faixa 200, a entrega da notificação é considerada bem-sucedida.

Se o código de resposta não estiver na faixa 200, tentaremos reenviar a notificação a cada hora nas próximas 72 horas. Depois de 72 tentativas fracassadas, desabilitaremos seu URL. Assim que você diagnosticar a causa das falhas, poderá reabilitar o URL e começar a receber novamente as notificações instantâneas.

Exemplos de códigos

Os dados enviados pelo serviço de notificação instantânea estão na forma de parâmetros de URL de HTML FORM pelo método POST. Os programas criados dentro da arquitetura do seu aplicativo devem processar esses pares. Programas de gerenciamento de pedidos, atividades de banco de dados e outros serviços podem ser criados, mas estão fora do escopo deste guia.

Os exemplos de código a seguir tratam da decodificação da notificação.

NOTA – Os exemplos de código a seguir devem ser aninhados em um programa. Além disso, estes exemplos exibirão falha se o seu conjunto de caracteres incluir caracteres dos idiomas alemão, grego, do leste europeu ou asiáticos. Você deve realizar sua própria codificação antes de decodificar as notificações instantâneas. Se você não souber como fazer isso, encontre um desenvolvedor que possa ajudar.

Java

O exemplo de código a seguir usa Java para decodificar a notificação.

 public void processNotification(final HttpServletRequest theRequest,
                              final HttpServletResponse theResponse)
   throws IOException {
  try {
     final StringBuilder buffer = new StringBuilder();
    final String secretKey = "YOUR SECRET KEY";

     try {
       String line;
        final BufferedReader reader = theRequest.getReader();
         while(null != (line = reader.readLine())) {
          buffer.append(line);
         }
      } catch(final Exception ex) {
          ex.printStackTrace();
       }

       final JSONParser parser = new JSONParser();
       final JSONObject obj = (JSONObject) parser.parse(buffer.toString()); 

      final String initializationVector = (String) obj.get("iv");
       final String encryptedNotification = (String) obj.get("notification"); 
      final MessageDigest digest = MessageDigest.getInstance("SHA-1");
      digest.reset();
       digest.update(secretKey.getBytes("UTF-8"));
      final String key = new String(Hex.encodeHex(digest.digest())).substring(0, 32);

final IvParameterSpec iv =
          new IvParameterSpec(DatatypeConverter.parseBase64Binary(initializationVector));
       final SecretKeySpec keySpec = new SecretKeySpec(key.getBytes(), "AES");
      final Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
       cipher.init(Cipher.DECRYPT_MODE, keySpec, iv);

      final JSONObject notification = (JSONObject) parser.parse(
      new String(cipher.doFinal(DatatypeConverter.parseBase64Binary(encryptedNotification)),
                     "ISO-8859-1"));

       //
       // Make use of the notification here...
      // 

   } catch(final NoSuchPaddingException
      | ParseException
       | NoSuchAlgorithmException
      | InvalidAlgorithmParameterException
       | BadPaddingException
      | IllegalBlockSizeException
       | UnsupportedEncodingException
      | InvalidKeyException ex) {
       ex.printStackTrace();
      theResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED,
                             "Could not decrypt instant notification");
  }
    theResponse.setStatus(HttpServletResponse.SC_NO_CONTENT);
}

PHP

O exemplo de código a seguir usa PHP para decodificar a notificação.

<?php
// NOTA: as bibliotecas de mcrypt precisam ser instaladas e listadas como uma
// extensão disponível no seu phpinfo() para permitir o uso deste
// método de decodificação.
 
$secretKey = "YOUR SECRET KEY"; // secret key from your ClickBank account
 
// get JSON from raw body...
$message = json_decode(file_get_contents('php://input'));
 
// Pull out the encrypted notification and the initialization vector for
// AES/CBC/PKCS5Padding decryption
$encrypted = $message->{'notification'};
$iv = $message->{'iv'};
error_log("IV: $iv");
 
// decrypt the body...
$decrypted = trim(mcrypt_decrypt(MCRYPT_RIJNDAEL_128,
 substr(sha1($secretKey), 0, 32),
 base64_decode($encrypted),
 MCRYPT_MODE_CBC,
 base64_decode($iv)), "\0..\32");
error_log("Decrypted: $decrypted");
 
////UTF8 Encoding, remove escape back slashes, and convert the decrypted string to a JSON object...
$sanitizedData = utf8_encode(stripslashes($decrypted));
$order = json_decode($decrypted);
 
// Pronto para executar - Se a codificação da string em JSON não estiver
// correta, você poderá presumir que a notificação não foi criptografada
// com sua chave secreta.
 
?>

Python

O exemplo de código a seguir usa Python para decodificar a notificação.

import hashlib
import json
from Crypto.Cipher import AES
##
# Parse ClickBank Notification
# @param message: A string representing the raw HTTP POST body
# @return: A JSON object representing the decrypted notification
def process_clickbank_notification(message):
    j = json.loads(message)
    iv = j['iv']
    encrypted_str = j['notification']
    sha1 = hashlib.sha1()
    sha1.update("YOUR SECRET KEY")
    cipher = AES.new(sha1.hexdigest()[:32], AES.MODE_CBC, iv.decode('base64'))
    return cipher.decrypt(encrypted_str.decode('base64')).strip()

Ruby

O exemplo de código a seguir usa Ruby para decodificar a notificação.

require "base64"
require "digest/sha1"
require "json"
require "openssl"
 # Decode the IPN post into a JSON object.
# The message param is the raw HTTP POST
 # body of the notification
def decrypt_clickbank_notification(message)
  parsed = JSON.parse(message);
  aes = OpenSSL::Cipher::Cipher.new("AES-256-CBC")
  aes.iv = Base64.decode64(parsed["iv"])
  aes.decrypt
  aes.key = Digest::SHA1.hexdigest("YOUR SECRET KEY").slice(0, 32)
  aes.update(Base64.decode64(parsed["notification"])) + aes.final
end
Tem mais dúvidas? Envie uma solicitação

0 Comentários

Por favor, entre para comentar.
Powered by Zendesk