Software development kit (SDK)

At the moment there is only one SDK available:

PHP SDK

The corresponding examples you can find in the Github Repository as well:
github.com/payrexx/payrexx-php/tree/master/examples

🚧
Troubles integrating our API in your programming language?
No problem. Please contact our support team at support.payrexx.com

Request

The payload data has to be one of the following formats:

JSON (recommended)
RFC 3986 (http://www.ietf.org/rfc/rfc3986.txt) url encoded and spaces will be percent encoded "%20"

The basic URL to our API is: https://api.payrexx.com/v1.0/:object/:id?instance=:instance

Parameter	Value
object	AuthToken \| Invoice \| Page \| Subscription
id	Only used for request types GET, PUT and DELETE where only one entity gets modified.
instance	The Payrexx instance name. If you access your Payrexx payment page with example.payrexx.com, the name would be example

For POST requests all query parameters except the instance have to be in the body.

Authentication - X-API-KEY (recommended)

📘
Is this important for you?
This part of the documentation is only important if you are not using an SDK.

You can authenticate by simply passing your API Secret via the HTTP header X-API-KEY: YOUR_API_SECRET. This is the easiest and most straightforward method.

Authentication - API signature

📘
Is this important for you?
This part of the documentation is only important if you are not using an SDK.

The API signature is a HMAC (RFC 2104).

For security reasons we want you to pass an API signature calculated with the API Secret of your instance.
The parameter name of this API signature should be ApiSignature. You can calculate the signature using all params except the param instance.

Build url encoded query string (e.g. model=Page&id=17)
Calculate binary hmac hash using your instance's API Secret as key
Encode it with base64

base64_encode(hash_hmac('sha256', http_build_query($params, null, '&'), $apiSecret, true));

echo -n "HTTP-QUERY-STRING" | openssl dgst -sha256 -hmac "API-SECRET" -binary | openssl enc -base64

import urllib.request
import hmac
import hashlib
import base64

post_data = {}

# http query string for signature calculation
httpQueryString = urllib.parse.urlencode(post_data).encode('UTF-8')
apiSignature = hmac.new(b'API-SECRET', msg=httpQueryString, digestmod=hashlib.sha256).digest()

# http query string for payload
payload = urllib.parse.urlencode(post_data, quote_via=urllib.parse.quote, safe='[|]').encode('UTF-8')

// imports
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.util.Base64;
import java.util.HashMap;
import java.util.concurrent.atomic.AtomicReference;

public static void main(String[] args) {
  // method content
  String key = "API-SECRET";

  // set up api data
  HashMap<String, String> data = new HashMap<>();
  data.put("title", "Test");
  data.put("description", "Test");
  data.put("referenceId", "12345678");
  data.put("purpose", "Test");
  data.put("amount", "200");
  data.put("currency", "EUR");

  String payload = getPayload(data);
  String hash = getApiSignature(payload, key);

  // append calculated ApiSignature to form data
  try {
    payload += "&ApiSignature=" + URLEncoder.encode(hash, "UTF-8");
  } catch (Exception e) {}

  payload = payload.replace("+", "%20");

  System.out.println("ApiSignature: " + hash);
  System.out.println("Payload: " + payload);
}

private static String getApiSignature(String encodedData, String apiKey) {
  try {
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key = new SecretKeySpec(apiKey.getBytes("UTF-8"), "HmacSHA256");
    sha256_HMAC.init(secret_key);
    return Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(encodedData.getBytes("UTF-8")));
  } catch (Exception e) {}
  return "";
}

private static String getPayload(HashMap<String, String> postData) {
  AtomicReference<String> urlEncoded = new AtomicReference<>("");
  postData.forEach((s, s2) -> {
    try {
      String concat = urlEncoded.get().isEmpty() ? "" : "&";
      urlEncoded.set(urlEncoded.get() + concat + s + "=" + URLEncoder.encode(s2, "UTF-8"));
    } catch (UnsupportedEncodingException e) {
    }
  });

  return urlEncoded.get();
}

# head
using System.Text;
using System.Security.Cryptography;

# function
string key = "API-SECRET";
string message = "";

byte[] keyByte = new UTF8Encoding().GetBytes(key);
byte[] messageBytes = new UTF8Encoding().GetBytes(message);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);

var signature = Convert.ToBase64String(hashmessage);

const qs = require('qs')
const Base64 = require('crypto-js/enc-base64')
const hmacSHA256 = require('crypto-js/hmac-sha256')

buildSignature(data, secret) {
  let queryStr = '';
  if (data) {
    queryStr = qs.stringify(data, {format: 'RFC1738'});
    queryStr = queryStr.replace(/[!'()*~]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
  }
  return Base64.stringify(hmacSHA256(queryStr, secret))
}

let queryParams = Object.assign({}, params)
queryParams.ApiSignature = buildSignature(queryParams, 'secret')

require 'openssl'
require 'base64'

query_string = "HTTP-QUERY-STRING"
api_secret = "API-SECRET"

digest = OpenSSL::Digest.new('sha256')
hmac = OpenSSL::HMAC.digest(digest, api_secret, query_string)
base64_encoded = Base64.encode64(hmac).chomp

🚧
Encoding of HTTP-Query String
The query string has to be RFC 1738 encoded, that means you have to replace spaces by "+".
You can probably use: http://linux.die.net/man/1/urlencode

API Rate Limit Information

Important
To ensure fair use of resources and maintain service quality, Payrexx enforces an API rate limit on all requests:

600 requests per 5 minutes
Enforced by AWS WAF

If the rate limit is exceeded, you will first encounter a 405 Method Not Allowed error, followed by a 403 Forbidden error. This is part of AWS WAF's security measures.

Best Practices to Handle Rate Limits:

Retry with Exponential Backoff: If your application hits the rate limit or encounters a 405 or 403 error, retry the request after a short delay, increasing the delay with each subsequent failure.
Batch Requests: Where possible, group multiple requests into a single API call to reduce the number of individual requests.