| Inhalt |
|---|
Payrexx ist ein Schweizer Zahlungs-Gateway, das mehrere Zahlungsdienstleister (PSP: Kreditkarten, TWINT, PostFinance, PayPal) hinter einer REST-API bündelt. JAXForms legt beim Absenden eines Formulars ein Payrexx-Gateway an, leitet die Bürger:in zur Zahlung weiter, prüft die Zahlung danach über die API und belastet sie (Capture). Stand: 23.10.2026.
...
Settings Payrexx Interface
Packagename im settings.xml: com.jaxforms.payment.provider.payrexx.PayrexxService.*
| Property | Data type | Required | Default | Description |
|---|---|---|---|---|
apiBaseUrl | String | https://api.payrexx.com/v1.0/ | Basis-URL der Payrexx REST-API (inkl. Version, mit abschliessendem /). | |
instance | String | ✔ | Name der Payrexx-Instanz ({INSTANZ}.payrexx.com). Wird bei jedem API-Aufruf als Query-Parameter instance mitgegeben. | |
apiSecret | String | ✔ | API-Secret der Instanz (Payrexx: Einstellungen > API). Wird als Header X-API-KEY gesendet und nicht geloggt. | |
paymentCurrency | String | CHF | Währung für die Bezahlung. Wert kann in Formular/Workflow überschrieben werden. | |
authorizationMode | Enum (String) | RESERVATION | RESERVATION: Betrag wird reserviert und danach belastet. PRE_AUTHORIZATION: Karte wird vorautorisiert und danach belastet. | |
captureAfterAuthorizing | Boolean | true | Belastung (Capture) direkt nach erfolgreicher Autorisierung. Bei false bleibt die Zahlung reserviert und muss ausserhalb von JAXForms belastet werden. | |
paymentMethods | Liste | alle der Instanz | Kommagetrennte Liste der erlaubten Zahlungsmittel (Payrexx-Parameter pm), z.B. visa, mastercard, twint. | |
psp | Liste | alle der Instanz | Kommagetrennte Liste der erlaubten PSP-IDs (Payrexx-Parameter psp). | |
lookAndFeelProfile | String | ID eines Look-and-Feel-Profils der Payrexx-Instanz für die Checkout-Seite. | ||
validityMinutes | int | 60 | Gültigkeit des Payrexx-Gateways in Minuten. | |
modalJsUrl | String | https://media.payrexx.com/modal/v1/modal.min.js | Script für das Payrexx-Modal (nur Modus MODAL). | |
clientCallbackUrl | String | URL des Formulars | Rückkehr-URL nach der Zahlung (success, failed, cancel). Ohne Angabe wird die URL des aufrufenden Formulars verwendet. JAXForms hängt das Token serverAccessToken an. | |
retryTimeout | int | 30 | Maximale Wartezeit in Sekunden für die Prüfung der Zahlung. | |
retryInterval | int | 1 | Abstand in Sekunden zwischen den Abfragen bei Payrexx, mindestens 1. |
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
<?jaxfront version=3.26.1;time=2019-04-11 16:39:07.663;xui=property.xui;xsd=property.xsd?>
<properties xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="property.xsd">
<property mutable="true">
<key>com.jaxforms.payment.provider.payrexx.PayrexxService.apiBaseUrl</key>
<value>https://api.payrexx.com/v1.16/</value>
</property>
<property mutable="true">
<key>com.jaxforms.payment.provider.payrexx.PayrexxService.instance</key>
<value>{INSTANZ}</value>
</property>
<property mutable="true">
<key>com.jaxforms.payment.provider.payrexx.PayrexxService.apiSecret</key>
<value>{API_SECRET}</value>
</property>
<property mutable="true">
<key>com.jaxforms.payment.provider.payrexx.PayrexxService.paymentCurrencyValue</key>
<value>CHF</value>
</property>
<property mutable="true">
<key>com.jaxforms.payment.provider.payrexx.PayrexxService.authorizationMode</key>
<value>RESERVATION</value>
</property>
<property mutable="true">
<key>com.jaxforms.payment.provider.payrexx.PayrexxService.captureAfterAuthorizing</key>
<value>true</value>
</property>
<property mutable="true">
<key>com.jaxforms.payment.provider.payrexx.PayrexxService.paymentMethods</key>
<value>visa, mastercard, twint</value>
</property>
<property mutable="true">
<key>com.jaxforms.payment.provider.payrexx.PayrexxService.validityMinutes</key>
<value>60</value>
</property>
</properties> |
...
Mapping
Beim Absenden legt JAXForms ein Payrexx-Gateway an (POST Gateway/). Die Felder werden so befüllt:
| Payrexx Gateway | Default | JAXForms Variablen | Beschreibung |
|---|---|---|---|
amount | paymentAmount | Betrag in Rappen (Betrag × 100, gerundet). | |
currency | CHF | paymentCurrency | |
purpose | InstanceID (Form) | paymentOrderDescription | Zahlungszweck, auf der Checkout-Seite sichtbar. |
referenceId | RandomUUID | paymentOrderId | Referenz der Zahlung bei Payrexx. |
language | FormInstance.language | Fixer Wert, kann nicht überschrieben werden. | |
successRedirectUrl | clientCallbackUrl + Token | Fixer Wert, kann nicht überschrieben werden. | |
failedRedirectUrl, cancelRedirectUrl | clientCallbackUrl + Token | Fixer Wert, kann nicht überschrieben werden. Abbruch und Fehler führen auf dieselbe URL. | |
reservation, preAuthorization | reservation=true | Abgeleitet aus authorizationMode. | |
skipResultPage | true | Fixer Wert, kann nicht überschrieben werden. | |
validity | 60 | Aus validityMinutes. | |
pm, psp | nicht gesetzt | Aus paymentMethods bzw. psp, nur wenn konfiguriert. | |
lookAndFeelProfile | nicht gesetzt | Nur wenn konfiguriert. |
Anmerkung: paymentOrderData (Default «JAXForms») wird nur in JAXForms gespeichert und nicht an Payrexx übermittelt.
Zahlungsmittel
Das Zahlungsmittel der Transaktion (payment.brand) wird über payrexx-converters.xml (Converter paymentConfig) in die Spalte PAYMENT_METHOD übersetzt. Mandanten können die Datei unter resources/{MANDANT}/payrexx-converters.xml überschreiben; sonst gilt die Version aus resources/SYSTEM/PAYMENT/.
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
<transform>
<converter id="paymentConfig" default="na">
<entry from="visa" to="visa"/>
<entry from="mastercard" to="mastercard"/>
<entry from="twint" to="twint"/>
<entry from="postfinance" to="postcard"/>
<entry from="paypal" to="paypal"/>
<entry from="amex" to="amex"/>
</converter>
</transform> |
...
Workflow Action
Das E-Payment-Plugin ist als Workflow-Aktion in ein Formular eingebunden. Für Payrexx gibt es eine Aktion für beide Modi; der Modus wird über die Workflow-Property integrationMode gewählt.
Aktion: com.jaxforms.payment.workflow.SaveFormPayrexxAction
| integrationMode | Beschreibung | Status |
|---|---|---|
FORWARD (Default) | Weiterleitung auf die Payrexx-Checkout-Seite. Sobald die Transaktion abgeschlossen ist, kehrt man auf das Formular zurück. | Unterstützt |
MODAL | Die Transaktion wird in einem Payrexx-Fenster innerhalb des Formulars abgehandelt. | Unterstützt |
Ablauf
- Die Bürger:in klickt auf den Zahlungs-Button. JAXForms legt ein Gateway an und speichert die Zahlung mit Status INITIALIZED.
- Die Bürger:in bezahlt auf der Payrexx-Seite und kehrt mit dem
serverAccessTokenauf das Formular zurück. - JAXForms fragt den Status des Gateways bei Payrexx ab (bis 30 Sekunden) und speichert Transaktion, Status und Zahlungsmittel.
- Ist die Zahlung reserviert bzw. autorisiert und
captureAfterAuthorizing=true, wird sie belastet. Ist sie bereits belastet (CONFIRMED, z.B. bei PSP ohne Reservation), entfällt der Capture. - Erst danach wird das Formular eingereicht.
| Info | ||
|---|---|---|
| ||
Schlägt die Zahlung fehl oder wird sie abgebrochen, wird sie bei Payrexx storniert bzw. als FAILED markiert, und das Formular bleibt offen. Schlägt der Capture fehl, wird die Zahlung auf ERROR gesetzt und das Formular nicht eingereicht. Die Reservation wird dabei bewusst nicht storniert: Ein Timeout kann bei Payrexx trotzdem erfolgreich gewesen sein. Solche Zahlungen im Payrexx-Backoffice prüfen. |
Statuswerte
| Status | Bedeutung | Statusspalte (ColumnStatus) |
|---|---|---|
INITIALIZED | Gateway angelegt, noch keine Zahlung. | NA |
RESERVED, AUTHORIZED | Betrag reserviert bzw. vorautorisiert, noch nicht belastet. | RESERVED |
CONFIRMED | Betrag belastet. | PAY_SUCCESSFUL |
CANCELLED, DECLINED, FAILED | Storniert, abgelehnt oder fehlgeschlagen. | CANCELED |
ERROR | Technischer Fehler, Details in TRANSACTION_DATA. | ERROR |