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:

Parâmetros de resposta

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

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:

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