Centro de Suporte

Gateways de pagamento externos

Importante: Esta é uma funcionalidade avançada que lhe permite conectar qualquer método de pagamento à sua loja. Normalmente, um programador de Web externo (ou o próprio gateway de pagamento) pode efetuar esta integração.

Uma loja Jumpseller pode ser integrada com qualquer Gateway de pagamento externo (EPG) à sua escolha. Qualquer serviço de pagamento online, com a capacidade de aceitar pedidos HTTP e capacidade de processar transacções de pagamento online, pode ser integrado na sua loja Jumpseller como um método de pagamento externo.


Como funciona

  1. O cliente faz uma [Encomenda] (/support/orders/) na sua loja Jumpseller e selecciona o seu Portal de Pagamento Externo como método de pagamento.

  2. O cliente é redireccionado para o seu Método de pagamento URL utilizando um pedido POST com os seguintes Parâmetros de pedido. A sua plataforma de pagamento deve verificar a Assinatura antes de apresentar a página de pagamento.

  3. O cliente procede à transação na sua página de pagamento.
    • Se o cliente completar o fluxo de pagamento com sucesso, deve ser redireccionado (GET) para x_url_complete com todos os Response Parameters necessários como parâmetros de consulta, incluindo a Signature
    • Se o cliente cancelar ou abandonar o pagamento, deve ser redireccionado (GET) para x_url_cancel com todos os Response Parameters necessários como parâmetros de consulta, incluindo a Signature
  4. O seu gateway de pagamento deve POSTAR uma chamada de retorno de forma assíncrona para x_url_callback com os mesmos Response Parameters. Isto assegura que as encomendas podem ser concluídas mesmo nos casos em que a ligação do cliente à Jumpseller é terminada por um erro de rede.
    • O Jumpseller devolve um estado HTTP 200 numa chamada de retorno bem sucedida, caso contrário deverá efetuar pelo menos 3 tentativas.

Parâmetros do pedido

Depois de o cliente preencher os detalhes do checkout e efetuar a encomenda na sua loja, o Jumpseller fará um pedido POST para o URL das definições do EPG com os seguintes parâmetros:

Chave de parâmetro Descrição Exemplo
x_url_complete URL para redirecionar após uma transação bem sucedida (GET). https://demostore.jumpseller.com/checkout/external_payment_complete/1001
x_url_callback URL para fornecer notificações sobre a transação de forma assíncrona (POST). https://demostore.jumpseller.com/checkout/external_payment_notification/1001
x_url_cancel URL para redirecionar quando o cliente desiste ou cancela o pagamento (GET). https://demostore.jumpseller.com/checkout/external_payment_cancel/1001
x_account_id Identificador de conta fornecido pelo EPG. 223504
x_amount Valor total da transação. 123.0
x_currency Código ISO da moeda. EUR
x_reference Número de encomenda na sua loja Jumpseller. 1001
x_shop_country Código ISO do país da loja Jumpseller. PT
x_shop_name Nome da loja Jumpseller. Demostore
x_description Descrição da transação (opcional). \\nProduto:\\n1 x teste: 1.000 EUR\\nImposto: 23€
x_signature Ver secção de “Assinatura 3e3b0fa9b8e5e0309d8a4fd6ad00048548f8434873cfed2b42507ca9b580d053
x_customer_first_name   Teste
x_customer_last_name   Jumpseller
x_customer_email   teste@jumpseller.com
x_customer_phone   912345678
x_customer_shipping_first_name   Teste
x_customer_shipping_last_name   Jumpseller
x_customer_shipping_city   Porto
x_customer_shipping_address1   Rua do Almada 123
x_customer_shipping_address2    
x_customer_shipping_state   Porto
x_customer_shipping_zip   4050
x_customer_shipping_country   PT
x_customer_shipping_phone   223456789
x_customer_billing_first_name   Teste
x_customer_billing_last_name   Jumpseller
x_customer_billing_city   Porto
x_customer_billing_address1   Rua do Almada 123
x_customer_billing_address2    
x_customer_billing_state   Porto
x_customer_billing_zip   4050
x_customer_billing_country   PT
x_customer_billing_phone   223456789
x_customer_taxid Unicamente enviado para os métodos de pagamento instalados após 2022/07/19 1111111-1

Parâmetros de resposta

Todas as respostas enviadas para o Callback URL assíncrono fornecido têm de incluir os seguintes parâmetros:

Chave do parâmetro Descrição Exemplo  
x_account_id Identificador da conta fornecido pelo GEP 223504  
x_amount Valor total da transação 123.0  
x_currency Código ISO da moeda EUR  
x_reference Número da encomenda na sua loja Jumpseller 1001  
x_result Atualização do estado da transação completed \ pending \ failed  
x_timestamp Hora UTC para quando a transação foi concluída 2018-07-11T12:15:37Z (AAAA-MM-DDTHH:MM:SSZ)  
x_message (opcional) Descrição textual do resultado. Mostrado ao cliente. “O cartão de crédito não pôde ser processado.”  
x_signature Ver a secção “Assinatura”. 3e3b0fa9b8e5e0309d8a4fd6ad00048548f8434873cfed2b42507ca9b580d053  

ID da conta

Todos os pedidos e respostas devem incluir um campo para validação da conta, x_account_id, que deve corresponder ao campo Payment Method Key nas suas definições de pagamento. Este é o identificador de conta que deve ser fornecido pela sua conta do gateway de pagamento.


Assinatura

Todos os pedidos e respostas têm de incluir um campo assinado, x_signature, para testar a integridade dos pedidos que é obtida utilizando HMAC-SHA256.

Num ambiente Ruby, o seguinte código obteria uma assinatura válida:

OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), secret, result)

  • secret - o campo Payment Method secret nas suas definições de pagamento, este é um valor que deve ser fornecido pela sua conta de Gateway de pagamento e partilhado com a Jumpseller.
  • result - o hash do pedido/resposta reunido numa única cadeia de todos os pares de valores chave que começam com o prefixo x_, ordenados alfabeticamente e concatenados sem separadores. Por favor, certifique-se de excluir o campo x_signature deste cálculo ao verificar qualquer pedido recebido dos servidores do Jumpseller.

Notas importantes:

  • Por favor, certifique-se de que está a utilizar a codificação UTF-8.
  • x_message (& x_description) - quaisquer caracteres de nova linha (‘\n’) devem ser corretamente escapados como (‘\\n’) antes de calcular a assinatura.
  • x_amount - os valores são fornecidos como Strings com decimais, mesmo para totais arredondados (e.g. 12345.0), para que não sejam convertidos inesperadamente.
  • x_signature - o parâmetro deve ser excluído da verificação dos pedidos do Jumpseller

Exemplos

Ruby

Criando uma assinatura válida.

require 'openssl'

secret = 'external_payment_gateway_password'

hash = {
  x_shop_name: 'Manchester Plant ', x_account_id: '223504', x_amount: '123.0', x_currency: 'EUR',
  x_reference: '1001', x_result: "completed",  x_timestamp: '2014-03-24T12:15:41Z',
  x_message: "\\nProducto:\\n1 x Energise EDT 125 ML: 29.500 EUR\\nImpuesto: €6.785,00"
}

result = hash.sort.join

x_signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), secret, result)

=> "d5dbffd999d4cbf70de494b4eec410d68deb540de13ebf5cfc03903c78bbd496"

Efetuar um pedido GET ao external_payment_complete.

require "uri"
require "net/http"

url = URI("https://demostore.jumpseller.com/checkout/external_payment_complete/1026?x_signature=c6296d5a1b67c691e209a2023bee341f60d11b479f864b2016a8005a21888c64&x_shop_name=Manchester Plant &x_account_id=129785&x_amount=300.0&x_currency=CLP&x_reference=1026&x_result=completed&x_timestamp=2020-06-12T18:17:15.898Z&x_message=\\nProducto:\\n1 x Prueba de pago: $300")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
response = https.request(request)

Se mostrar o response.read_body verá o html da página que foi redirecionada.

Fazer uma requisição POST para external_payment_notification.

require "uri"
require "net/http"

url = URI("https://demostore.jumpseller.com/checkout/external_payment_complete/1026?x_signature=c6296d5a1b67c691e209a2023bee341f60d11b479f864b2016a8005a21888c64&x_shop_name=Manchester Plant &x_account_id=129785&x_amount=300.0&x_currency=CLP&x_reference=1026&x_result=completed&x_timestamp=2020-06-12T18:17:15.898Z&x_message=\\nProducto:\\n1 x Prueba de pago: $300")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
response = https.request(request)
=> #<Net::HTTPOK 200 OK readbody=true>

NodeJs

Criar uma assinatura válida.

var crypto = require('crypto');

let body = {
  "x_account_id": "1234",
  "x_amount": "1000.0",
  "x_currency": "EUR",
  "x_reference": "1033",
  "x_result": "completed",  
  "x_timestamp": "2020-06-12T18:17:15.898Z",
  "x_message": "\\nProducto:\\n1 x Prueba de pago: $300"
}

let keys = Object.keys(body);

keys = keys.sort();

let toSign = '';
let query = '';
keys.forEach((key) => {
  toSign += key + body[key];
  query += encodeURIComponent(key) + '=' + encodeURIComponent(body[key]) + '&';
});

const secretKey = 'external_payment_gateway_password';
var signer = crypto.createHmac('sha256', secretKey);
var result = signer.update(toSign, 'utf8').digest('hex');

query += encodeURIComponent('x_signature')+"="+encodeURIComponent(result);

Efetuar um pedido GET a external_payment_complete.

var request = require('request');

var options = {
  'method': 'GET',
  'url': 'https://demostore.jumpseller.com/checkout/external_payment_complete/3120?x_signature=be8d4df696d4e2c770b1890e67351b1f9be9f98cd94f421dfc7787c39f0e23c7&x_account_id=1988063&x_amount=1000.0&x_currency=EUR&x_reference=3120&x_result=completed&x_timestamp=2020-06-12T18:17:15.898Z&x_message=\\nProducto:\\n1 x Prueba de pago: $300'
};

request(options, function(error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Se mostrar o response.body verá o html da página que foi redirecionada.

PHP

# !/usr/bin/env php
<?php

$secretKey = "external_payment_gateway_password";

$params = array( "x_shop_name" => "Manchester Plant ", "x_account_id" => "223504", "x_amount" => "123.0", "x_currency" => "EUR", "x_reference" => "1001", "x_result" => "completed",  "x_timestamp" => '2014-03-24T12:15:41Z', "x_message" => "\\nProducto:\\n1 x Energise EDT 125 ML: 29.500 EUR\\nImpuesto: €6.785,00" );

$keys = array_keys($params);
sort($keys);

$toSign = "";
foreach ($keys as $key) { $toSign .= $key . $params[$key]; }

$sign = hash_hmac('sha256', $toSign, $secretKey);
echo $sign . "\xA";

// => d5dbffd999d4cbf70de494b4eec410d68deb540de13ebf5cfc03903c78bbd496
?>

Fluxogramas

Nesta secção são apresentados os fluxogramas dos processos de gateway de pagamento externo para oferecer uma representação mais precisa da forma como o Jumpseller define os diferentes processos de método de pagamento externo

Notificação de pagamento externo

Cancelamento de pagamento externo

Pagamento externo concluído


Resultado do Estado

Todas as respostas enviadas para o Callback URL fornecido devem incluir um campo x_result com um dos seguintes valores de cadeia:

  • pending - O equivalente a Pending Payment no seu Painel de Administração Jumpseller, esta ação irá adicionar uma mensagem ao Histórico da Encomenda sem alterar o estado da Encomenda.
  • failed - O equivalente a Cancelado no seu Painel de Administração Jumpseller, esta ação irá cancelar a encomenda e alterar o seu estado.
  • completed - O equivalente a Paid no seu Painel de Administração Jumpseller, esta ação irá alterar o estado da encomenda.

Como publicar

Assim que houver pelo menos 2 lojas Jumpseller a utilizar a sua Gateway que tenham processado pelo menos 150 transacções bem sucedidas cada, pode solicitar que a Jumpseller liste a sua Gateway publicamente para todos os comerciantes. Se for aprovado, a sua Gateway será listada no Painel de Administração do Jumpseller e na página pública gateways de pagamento da Jumpseller.

Para solicitar uma listagem pública para a sua Gateway, envie um e-mail para team@jumpseller.com com os seguintes detalhes:

  • Nome do pagamento externo.
  • Documentação sobre: como contratar, como configurar, como utilizar, secção FAQ (opcional).
  • Lista de comerciantes Jumpseller que utilizam a sua gateway e o número total de transacções processadas por loja.
  • Screencasts do processo de checkout para tentativas de pagamento bem sucedidas e falhadas.
  • Logótipo: Admin 110x66px / Checkout 280x35px / Todos em PNG transparente.

Será publicado no painel de administração, juntamente com outras soluções de pagamento, com o seu próprio logótipo. Como mostra a imagem abaixo:

sampleexternalpayments

Para mais anúncios em boletins informativos, redes sociais e outras actividades de marketing, contacte partners@jumpseller.com

Comece a vender connosco!

Experimente grátis durante 14 dias. Não é necessário cartão de crédito.