How build a Jumpseller App
A Jumpseller App is an application that interacts with one or more online stores that use Jumpseller. The App can be loaded through an iframe insid...
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 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.
The customer places an Order on your Jumpseller store and selects your External Payment Gateway as a payment method.
The customer is redirected to your Payment method URL using a POST request with the following Request Parameters. Your gateway must verify the Signature and display the payment page.
x_url_complete
with all the required Response Parameters as query parameters, including the Signature
x_url_cancel
with all the required Response Parameters as query parameters, including the Signature
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. 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 external payment method settings with the following parameters:
Parameter key | Description | Example |
---|---|---|
x_url_complete | URL to redirect after a successful transaction (GET). | https://demostore.jumpseller.com/checkout/external_payment_complete/1001 |
x_url_callback | URL to provide notifications about transaction asynchronously (POST). | https://demostore.jumpseller.com/checkout/external_payment_notification/1001 |
x_url_cancel | URL to redirect when the customer quits or cancels the payment (GET). | https://demostore.jumpseller.com/checkout/external_payment_cancel/1001 |
x_account_id | Account identifier provided by the external payment gateway. | 223504 |
x_amount | Total value of the transaction. | 123.0 |
x_currency | ISO code of the currency. | EUR |
x_reference | Order number in your Jumpseller store. | 1001 |
x_shop_country | ISO code of the Jumpseller store country. | PT |
x_shop_name | Name of the Jumpseller store. | Demostore |
x_description | Description of the transaction (optional). | \\nProduto:\\n1 x teste: 1.000 EUR\\nImposto: 23€ |
x_signature | See “Signature” section | 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 | Only will be sent for payment methods installed after 2022/07/19 | 1111111-1 |
All responses submitted to the provided asynchronous Callback URL are required to include the following parameters:
Parameter key | Description | Example |
---|---|---|
x_account_id | Account identifier provided by the external payment gateway | 223504 |
x_amount | Total value of the transaction | 123.0 |
x_currency | ISO code of the currency | EUR |
x_reference | Order number in your Jumpseller store | 1001 |
x_result | Status update for the transaction | completed \ pending \ failed |
x_timestamp | UTC Time for when the transaction was finished | 2018-07-11T12:15:37Z (YYYY-MM-DDTHH:MM:SSZ) |
x_message | Description of the result (optional). Shown to Customer. | The credit card could not be processed. |
x_signature | See “Signature” section. | 3e3b0fa9b8e5e0309d8a4fd6ad00048548f8434873cfed2b42507ca9b580d053 |
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.
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 servers.Important notes:
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 requestsCreating a valid signature.
secret = 'external_payment_gateway_password'
hash = {
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)
=> "604be3b09fd105e68426017221437a0251c0322aa8c63b8724623ce0f590dea2"
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_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.
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.
# !/usr/bin/env php
<?php
$secretKey = "external_payment_gateway_password";
$params = array( "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";
// => 604be3b09fd105e68426017221437a0251c0322aa8c63b8724623ce0f590dea2
?>
All responses submitted to the provided Callback URL must include a x_result field with one of the following string values:
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 list your gateway publicly for all shops. If approved, your gateway will be listed in Jumpseller’s Admin Panel and on Jumpseller’s public payment gateways landing.
To request a public listing for your gateway, email team@jumpseller.com with with the following details:
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, please contact team@jumpseller.com
Q: How should the payment values be rounded?
You can use your programming language’s default Math rounding method to convert decimal values to integers as necessary if the currency you are operating with does not contain cents, like Chilean Pesos. The presentation of the value is entirely up to the Payment Integration. For example, in Ruby:
2.6.4 :002 > 10.5.round
=> 11 CLP
2.6.4 :002 > 10.4.round
=> 10 CLP
2.6.4 :003 > 10.45.round
=> 10 CLP
2.6.4 :004 > 10.455.round
=> 10 CLP
Free trial for 14 days. No credit card required.