About

Payment Gateway is the system, which mediates and manages all payment requests, that are used to perform different functionalities and operations. To get started, please make sure that you already have an account registered with us and head to Quick Start page.

Quick Start

To jump right into implementation, please head to Authentication Section and later over to API Reference for details of API endpoints.

We also suggest to read Payment Methods section in case you would like information on specific payment methods and their integration. API Reference does not get into very details of each payment method.

You can also refer to Transaction Statuses, Errors as well as Receiving transaction notifications through Postbacks.

Test Data can be found over Appendix.

Authentication

There are two ways of authenticating with our API. We strongly suggest to use BASIC AUTH authentication to speed up the development time. Checksum authentication is considered legacy.

For developers who still use the legacy way of authenticating using checksums, we still provide the documentation below.

Prior to authenticating, make sure to have your API and OUTGOING keys at hand. If you already have an account with us, please navigate to My Company section in your dashboard to view and manage authentication keys.

BASIC AUTH

Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password. For example, to authorize as demo / p@55w0rd the client would send following HTTP HEADER:

Authorization: Basic ZGVtbzpwQDU1dzByZA==

Simply include your API key as your username and OUTGOING key as your password in your basic auth encoding string.

Content-Type Headers

When using BASIC AUTH, you should set your Content-Type HTTP header value to application/json and post a JSON body in your request payloads.

Checksum - (legacy)

To prevent tampering with payment data, the parameters may be signed with a checksum. The outgoing requests are signed with the OUTGOING key. The API applies the following checksum calculation algorithm to verify the authenticity of the posted data.

The merchant is identified and authenticated with API key and a checksum calculated with request parameters and the OUTGOING key. The API, OUTGOING and INCOMING keys should be treated carefully and not revealed to outsiders.

How to calculate checksum?

query_string="api_key=aab1fbbca555e0e70c27&currency=EUR&merchant_reference=123&order_id=123&payment_type=cc&shipping_costs=3.50&amount=17.50"
outgoing_key="4d422da6fb8e3bb2749a"

# MacOS
echo -n $query_string$outgoing_key | shasum | awk '{print $1}'

# Linux
echo -n $query_string$outgoing_key | sha1sum | awk '{print $1}'

# Please replace the outgoing_key with your own, which is located under the section My Company on your dashboard.

def calculate_checksum(params, outgoing_key)
  params_in = {}

  params.each do |k, v|
    params_in[k] = v || ''
  end

  Digest::SHA1.hexdigest(URI.encode_www_form(params_in) + outgoing_key)
end

params = [["api_key", "aab1fbbca555e0e70c27"],
          ["currency", "EUR"],
          ["merchant_reference", "123"],
          ["order_id", "123"],
          ["payment_type", "cc"],
          ["shipping_costs", "3.50"],
          ["amount", "17.50"]]

outgoing_key = "4d422da6fb8e3bb2749a"
puts calculate_checksum(params, outgoing_key)

# @returns 9b6b075854fc3473c09700e20e19af3fbc3ff543

# Please replace the outgoing_key with your own, which is located under the section My Company on your dashboard.

function sign_request($params, $outgoing_key){
  $query = http_build_query($params, NULL, "&", PHP_QUERY_RFC1738);
  $checksum = sha1($query . $outgoing_key);
  return $checksum;
}

$params = array(
  "api_key" => "aab1fbbca555e0e70c27",
  "currency" => "EUR",
  "merchant_reference" => "123",
  "order_id" => "123",
  "payment_type" => "cc",
  "shipping_costs" => "3.50",
  "amount" => "17.50");
$outgoing_key = "4d422da6fb8e3bb2749a";

printf(sign_request($params, $outgoing_key));

// Return value is 9b6b075854fc3473c09700e20e19af3fbc3ff543

// Please, replace the outgoing_key with your own, which is located under the section My Company on your dashboard.

Please, follow the steps below:

• Make a key/value list of all used parameters (except the checksum itself), in the same order they are posted to the API request
• Convert parameters into a query string using the application/x-www-form-urlencoded format (RFC 1738). See below for more information on how to do the conversion.
• Append the outgoing key to the query string
• Calculate the SHA1 digest of the resulting string
• Set the value of the checksum parameter to the SHA1 digest

We provided checksum calculation code in various programming languages in the sidebar.

Please, keep the following in mind:

• That the order of parameters passed in the request MUST match the order that you have calculated the checksum
• That you have verified your API and Outgoing key
• That you are sending request in correct environment. E.g test vs production.

How to convert parameters into query string?

Spaces are encoded as plus (+) characters and special characters are encoded with a percentage sign followed by two hexadecimal digits. For more details about how to encode a query string see RFC 1738. If the company parameter's key has the value “John & Sons”, {"company": "John & Sons"}, the resulting string will be: company=John+%26+Sons

Where to find credentials?

Credentials such as API, Outgoing and Incoming keys can be found in your Dashboard once you have registered an account with us.

Idempotency

Our API supports idempotency to ensure safe retries of requests without unintended side effects. To utilize this feature, include a unique UUID in one of the following headers when making POST, PUT, or PATCH requests:

• X-Idempotency-Key
• Idempotency-Key

When a request is received with an idempotency key, the response is cached for 1 hour. Subsequent requests with the same idempotency key within this timeframe will return the cached response, preventing duplicate operations.

Best Practice: We recommend using RFC 4122 compliant UUIDs (version 4) for idempotency keys.

Example: 9d8f5715-2e7c-4e64-8e34-35f510c12e66

API Reference

Below you will see list of all public API endpoints made available in our Payment Gateway. For each endpoint, we provide example body and response.

Payment API

Payment API is used to create new payments in the Payment Gateway.

Example POST rest/payment payload - Fill in your own API key and return URLs

{
    "api_key": "70abd594084787a392e8",
    "payment_type": "cc",
    "order_id": "122",
    "amount": "15.9",
    "currency": "EUR",    
    "address": "WonderStr 8",
    "city": "Berlin",
    "postal_code": "666",
    "country": "DE",
    "first_name": "Chuck",
    "last_name": "Norris",
    "email": "email@email.email",
    "postback_url": "https://postback.url.com",
    "success_url": "https://success.url.com",
    "error_url": "https://error.url.com",
}

Example POST rest/payment response

{
  "transaction_id": "5e02903b-0fbf-4266-affd-dc58f2749cd1",
  "order_id": "123000",
  "error_code": 0,
  "status_code": 1,
  "status": "started",
  "client_action": "redirect",
  "action_data": { 
    "url": "https://some-target-url"
  }
}

Payment API Parameters

Payment request parameters are divided into following blocks. Depending on your payment method type, they will differ.

X means that parameter block is accepted for the given payment method and is mandatory.

(X) means that parameter block is accepted for the given payment method and is optional.