External Payment Gateways

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.


Contents

  1. How It Works
  2. Request Parameters
  3. Response Parameters
  4. Account ID
  5. Signature
  6. Status Result

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 gateway must verify the Signature and display 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
  4. It is best practice for your payment gateway to also 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 we recommend to perform at least 3 retries.

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 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 Detail 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 Portugal
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 Portugal
x_customer_billing_phone 223456789


Response Parameters

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 Detail description of the transaction updates (optional) The credit card could not be processed.
x_signature See "Signature" section 3e3b0fa9b8e5e0309d8a4fd6ad00048548f8434873cfed2b42507ca9b580d053


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.


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.

Important notes:

  • 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.

Example (Ruby):

2.5.0 :001 > secret = 'external_payment_gateway_password'
 => "external_payment_gateway_password"
2.5.0 :002 > 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_description: "\\nProducto:\\n1 x Energise EDT 125 ML: 29.500 EUR\\nImpuesto: €6.785,00" }
 => {: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_description=>"\\nProducto:\\n1 x Energise EDT 125 ML: 29.500 EUR\\nImpuesto: €6.785,00"}
2.5.0 :003 > result = hash.sort.join
 => "x_account_id223504x_amount123.0x_currencyEURx_description\\nProducto:\\n1 x Energise EDT 125 ML: 29.500 EUR\\nImpuesto: €6.785,00x_reference1001x_resultcompletedx_timestamp2014-03-24T12:15:41Z"
2.5.0 :004 > x_signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), secret, result)
 => "c9713d3f6bfbefd8ad2ce56d97c447d4dad862f3beba02af49ffd10f3e26faff"

Example (PHP):

#!/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_description" => "\\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";

// => c9713d3f6bfbefd8ad2ce56d97c447d4dad862f3beba02af49ffd10f3e26faff
?>

Status Result

All responses submitted to the provided Callback URL must include a x_result field with one of the following string values:

  • pending - The equivalent to Pending Payment in your Jumpseller Admin Panel, this action will add a message to the Order History without changing Order's status.
  • failed - The equivalent to Canceled in your Jumpseller Admin Panel, this action will cancel the order and change its status.
  • completed - The equivalent to Paid in your Jumpseller Admin Panel, this action will change the order status.

Login to your Store

Forgot your Password?

Forgot your Password?

Return to Login