Notifications (Webhooks)

Changelog Version 2025-04-29

Transaction

ISO 8601 (RFC 3339-compliant) format for the time attribute: 2025-05-01T16:16:29+02:00

Changelog Version 2025-04-08

Transaction

New value for the payment attribute: cardholderName. This is only set for pre-authorized transactions or subscription payments.

Changelog Version 2025-03-03

Transaction

Added "type" with the following values (E-Commerce, POS)
Added "posSerialNumber" with the serial number of the pos terminal
Added "posTerminalName" with the name of the pos terminal

Changelog Version 2024-12-10

Invoice

Added "description"

Changelog Version 2024-11-12

Transaction

Added "cardCountry" within "payment" information

Changelog Version 2024-08-16

Transaction

Added "instanceName" and "instanceUuid"

Changelog Version 2024-06-01

Transaction

Added "purchaseOnInvoiceInformation" within "payment" information.

Changelog Version 2023-11-14

Payout

The attribute "mode" is now available.

Changelog Version 2023-10-20

Transaction

The attribute "payoutUuid" is now available (GET).

Changelog Version 2022-11-29

Transaction

Added "wallet" within "payment" information.

Changelog Version 2022-10-04

Transaction

The attributes refundable and partiallyRefundable are now available

Changelog Version 2022-08-09

From now on it is possible to activate/deactivate webhooks for events like transaction, subscription or payout.

Process Update 2022-02-21

From now on it is possible to activate automatic retries for webhooks. Read more about retries down below.

Changelog Version 2022-01-18

Transaction:

The attribute payrexx_fee has been renamed to payrexxFee

Changelog Version 2021-10-12

Transaction

The attribute metadata has now a consistent type. It is always an object, even if it is empty. In older versions, it was an array when it was empty.

Invoice

Removed attribute amount
Added new attributes originalAmount and refundedAmount. Original amount is the amount of the payment where refunded amount is the total amount refunded at the time of the webhook.

Changelog Version 2020-06-10

Transaction

new attribute amount in smallest unit of the transaction currency. This amount will include the refunded amount for refund-webhooks

Changelog Version 2019-12-19

Transaction:

new status uncaptured (only with PSP Clearhaus Acquiring)

Changelog Version 2019-10-15

Transaction:

new attribute preAuthorizationId which contains the ID of the origin pre-authorized transaction (which had the status "authorized").
new values for the payment attribute: cardNumber, expiry. This is only set for pre-authorized transactions or subscription payments.

General:

Correct handling of zero-decimal currencies. All amounts are in the smallest unit of the currency. (e.g. 2 JPY => 2, 2 EUR => 200), before it would have been 200 for all currencies.

Changelog Version 2019-07-16

New transaction status:

a new status refund_pending for transactions for which the refund has been initialized but not yet confirmed by the bank.

Changelog Version 2019-02-13

Transaction statuses renamed:

chargeback dispute to chargeback
Technical error to error
Partially refunded to partially-refunded

New Subscription status:

a new status in_notice for subscriptions which will not renew at the end of the period. In previous version it will appear as cancelled subscription.

Invoice gets new attributes:

sku: stock keeping unit (string)
vatRate: the vat rate in percentage (float)

Events

Payrexx webhooks will be fired on the following events.

Transaction

Order placed (status: waiting)
Successful payment processed (status: confirmed)
Payment aborted by customer (status: cancelled)
Payment declined (status: declined)
Pre-authorization successful (status: authorized)
Payment (partial-) refunded by merchant (status: refunded / partially-refunded), see changelog
Refund pending (status: refund_pending), see changelog
Chargeback by card holder (status: chargeback), see changelog
Technical error (status: error), see changelog

Subscription

On successful payment of a subscription payment
On failed payment of a subscription payment
On cancelled subscription
On noticed subscription (new by 2019-02-13, see changelog)

Payout (new since 2022-08-09)

On sent payout
On failed payout

Configuration

The configuration for the webhooks can be found at Settings > API.
There must be an accessible URL / IP address where the data should be sent to.
You can choose which content type you want to use. "Normal (PHP-Post) means application/x-www-form-urlencoded and is best used for PHP-applications. "JSON" means application/json and is best used for all different applications.

How to use

For an integration into a web shop you will create a Payrexx Gateway. After the transaction has been performed, you will get a notification request to your server. You can identify the transaction by paymentLinkId or referenceId in Invoice object.

Data

The data will be either sent in JSON format or as HTTP POST form-data.

Depending on the information you want to track in your system, please go to the object specification:

Examples

Currently, we only have an example written in PHP.

Download full PHP example with a corresponding MySQL database: click here to download

<?php

/**
 * The data of the POST request
 * @var array $transaction
 */
$transaction = !empty($_POST['transaction']) ? $_POST['transaction'] : array();

if (!empty($transaction)) {
		$invoice = $transaction['invoice'];
 	  $customFields = $invoice['custom_fields'];
 	  $contact = $transaction['contact'];
}

Retries

When activated for a webhook, the platform will try to resend the webhook based on the following policy:

immediately (max. 1 - 1.5 minutes after first synchronous attempt)
15 minutes after last attempt
1 hour after last attempt
2 hours after last attempt
4 hours after last attempt
24 hours after last attempt
24 hours after last attempt
24 hours after last attempt
24 hours after last attempt
24 hours after last attempt

Please note that those attempts will be asynchronously triggered.

Timeout

The server needs to send a response within 20 seconds. Otherwise, the request times out. The log shows HTTP status 0 and response body "Operation timed out after 20000 milliseconds with 0 bytes received".