Getting started
At the moment there is only one SDK available:
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
The payload data has to be 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
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
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 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 -base64import urllib.request
import hmac
import hashlib
import base64
post_data = {}
httpQueryString = urllib.parse.urlencode(post_data).encode('UTF-8')
apiSignature = hmac.new(b'API-SECRET', msg=httpQueryString, digestmod=hashlib.sha256).digest()// 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);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
Check your signature
This endpoint can be used to verify the INSTANCE_API_SECRET to be correct. In case it is not correct, you get an error status.
Errors
200
OK
Everything worked successfully!
403
Forbidden
The API Signature is wrong
404
Not Found
The requested endpoint does not exist
All errors will return a JSON in the following format:
{
status: "error",
message: "An error occurred: Human readable message goes here"
}Retrieve a payment link
Secure payment process using this endpoint
You could use this endpoint, for example, to verify a webhook you have received.
You get a webhook for a successful payment and you would like to check whether this Invoice has actually been paid.
Create a payment link
Use Invoice with Modal Box
To connect the created Invoice with the payment (Transaction), you must use the link provided in the response from POST as href of your modal box markup or build it yourself from the also provided hash.
Using the referenceId for that purpose will not work as expected, even when the demo results suggest that in some vague way.
Connecting your application with our Payrexx payment
If you have set up a webshop and would like to integrate Payrexx as your payment solution then it is necessary for you to create an invoice in the Payrexx system which you can then display as a payment form to the customer.
The response generates an Invoice ID which you can use to identify the successful payment. (see the chapter "Webhooks" for more information)
Retrieve a Payrexx Gateway
Integration manual
For more information about the usage of Payrexx Gateway, please visit Payrexx Gateway section.
Secure payment process using this endpoint
You could use this endpoint, for example, to verify a webhook you have received.
You get a webhook for a successful payment and you would like to check whether this gateway payment has actually been paid.
Create a Payrexx Gateway
Using the PHP client library
If you are using our PHP client library, there are setter and getter methods to access the PHP object properties.
Integration manual
For more information about the usage of Payrexx Gateway, please visit Payrexx Gateway section.
Delete a Payrexx Gateway
Integration manual
For more information about the usage of Payrexx Gateway, please visit Payrexx Gateway section.
Log in a subscription customer
If you configured recurring payments (subscriptions), Payrexx will automatically create user accounts for your customers. So your users can administrate the subscriptions and cancel them on Payrexx' site.
Often they don't know where to cancel the subscription. You can provide a link which will directly log them in to your Payrexx page where they can cancel subscriptions, change payment information and more.
The userId for this endpoint will be included in the subscription's webhook.
First your application requests a new authentication link. This means you get a link based on a contact id (param: userId) which you received through a Payrexx Webhook.
You can display the link to your user, or automatically redirect your user. After a click on the link the user will be automatically logged in. This means the customer can then see all fired payments and all subscriptions.
Create a new subscription
Experimental documentation state
This functionality is already in productional use, but the documentation might contain some errors. Please contact us if you are interested in handling Subscriptions through your own application.
Update a subscription
Experimental documentation state
This functionality is already in productional use, but the documentation might contain some errors. Please contact us if you are interested in handling Subscriptions through your own application.
Remove a subscription
Experimental documentation state
This functionality is already in productional use, but the documentation might contain some errors. Please contact us if you are interested in handling Subscriptions through your own application.