External Payment Gateways

Important: This is an advanced feature that allows you to connect any payment method with your store. Typically, an external web developer (or the payment gateway themselves) can do this integration.

A Jumpseller store can be integrated with any External Payment Gateway (EPG) of your choice. Any online payment service, with the ability to accept HTTP requests and capability to process online payment transactions, can be integrated with your Jumpseller store as an offsite payments method.

How It Works

1. The customer places an Order on your Jumpseller store and selects your External Payment Gateway as a payment method.

2. The customer is redirected to your Payment method URL using a POST request with the following Request Parameters. Your Payment Gateway must verify the Signature before displaying the payment page.

3. The customer proceeds with the transaction on your payment page.
   • If the customer completes the payment flow successfully, he should be redirected (GET) back to x_url_complete with all the required Response Parameters as query parameters, including the Signature
   • If the customer cancels or exits the payment, he should be redirected (GET) back to x_url_cancel with all the required Response Parameters as query parameters, including the Signature
4. Your Payment Gateway must POST a callback asynchronously to x_url_callback with the same Response Parameters. This ensures that orders can be completed even in cases where the customer’s connection to Jumpseller is terminated by a network error.
   • Jumpseller returns an HTTP 200 status on a successful callback, otherwise you should perform at least 3 retries.
   • Always send the customer and the callback to the x_url_complete, x_url_cancel and x_url_callback URLs received in the request, instead of building them yourself.

Request Parameters

After the customer fills the checkout details and places the order in your store, Jumpseller will make a POST request to the URL from your EPG settings with the following parameters:

Response Parameters

All responses submitted to the provided asynchronous Callback URL are required to include the following parameters:

Account ID

All requests and responses must include a field for account validation, x_account_id, which must match the Payment Method Key field in your payment settings. This is the account identifier that must be provided by your Payment Gateway account.

Both the Payment Method Key and the Payment Method Secret are required. A payment method missing either of them can’t be enabled, and Jumpseller refuses the responses for its orders. Keep the secret private: only your servers and Jumpseller should know it, so never send it to the customer’s browser.

Signature

All requests and responses must include a signed field, x_signature, to test the integrity of the requests which is obtained using HMAC-SHA256.

In a Ruby environment, the following would get you a valid signature:

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

• secret - the Payment Method secret field in your payment settings, this is a value which must be provided by your Payment Gateway account, and shared with Jumpseller.
• result - the request/response hash amassed in a single string of all key-value pairs that start with x_ prefix, sorted alphabetically, and concatenated without separators. Please make sure to exclude the field x_signature from this calculation when verifying any incoming request from the Jumpseller’s servers.

Important notes:

• Please make sure you use the UTF-8 encoding.
• x_message (& x_description) - any newline characters (‘\n’) must be properly escaped as (‘\\n’) before calculating the signature.
• x_amount - values are provided as Strings with decimals, even for rounded totals (e.g. 12345.0), so they are not converted unexpectedly.
• x_signature - the parameter should be excluded from the verification for Jumpseller requests

Signature calculator

Paste the parameters of a request or response and your Payment Method Secret to check the signature your integration calculates.

Examples

Ruby

Creating a valid signature.

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"

Making a GET request to 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)

If you show the response.read_body you will see the html from page that was redirected.

Making a POST request to external_payment_notification.

require "uri"
require "net/http"

url = URI("https://demostore.jumpseller.com/checkout/external_payment_notification/1026")

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

request = Net::HTTP::Post.new(url)
request.set_form_data(
  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'
)
response = https.request(request)
=> #<Net::HTTPOK 200 OK readbody=true>

NodeJs

Creating a valid signature.

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);

Making a GET request to 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);
});

If you show the response.body you will see the html from page that was redirected.

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
?>

Flowcharts

In this section the flowcharts of the external payment gateway processes are presented to offer a more accurate representation of how the Jumpseller defines the different external payment method processes

External Payment Notification

External Payment Cancel

External Payment Complete

Status Result

Every response must include an x_result field with one of the following values. What Jumpseller does depends on the URL the response is sent to:

• pending doesn’t change an order that is already Canceled or Abandoned, it only adds a message to its Order History.
• Once an order is Paid, the responses sent for it afterwards are ignored.
• A value that isn’t accepted on that URL is refused.

How to Publish

Once there are at least 2 Jumpseller stores using your Gateway that have processed at least 150 successful transactions each, you can request that Jumpseller lists your Gateway publicly for all merchants. If approved, your Gateway will be listed in Jumpseller’s Admin Panel and on Jumpseller’s public payment gateways page.

To request a public listing for your Gateway, email team@jumpseller.com with the following details:

• Name of the External Payment.
• Documentation about: how to contract, how to setup, how to use, FAQ section (optional).
• List of Jumpseller merchants using your gateway and the number of total transactions processed per store.
• Screencasts of checkout process for both successful and failed payment attempts.
• Logo: Admin 110x66px / Checkout 280x35px / All in PNG transparent.

You will be published in the Admin Panel along other payment solutions, with your own logo. As shown in the image below:

For further announcements in newsletters and social media and other marketing activities please contact partners@jumpseller.com