Sie benötigen ein Benutzerkonto mit der Rolle "Webservices JWT", um das Token zu erstellen.
Wenn dieses Benutzerkonto noch nicht vorhanden ist, fordern Sie es bitte bei unserem Support-Team für Ihre Website(s) an.
Die jwt Das in das Formular eingegebene Feld muss in Form eines JSON Web Token (JWT) vorliegen, das aus verschlüsselten Daten besteht.
JSON-Web-Token sind eine offene, dem Industriestandard RFC 7519 entsprechende Methode zur sicheren Übertragung von Daten zwischen zwei Parteien.
Wir empfehlen die Verwendung der Bibliotheken, die Sie unter https://jwt.io finden, um das JWT zu generieren.
Die JWT-Erstellung muss auf Ihrem Backend-Server erfolgen, um zu vermeiden, dass sensible Details (z. B. das JWT-Signierungsgeheimnis) offengelegt werden.
In seiner kompakten Form besteht JWT aus drei Teilen, die durch Punkte (".") getrennt sind, nämlich:
<header>.<payload>.<signature>
Generierung der header
Die header besteht aus zwei Teilen:
- alg - Der verwendete Signieralgorithmus (wir unterstützen "HS256", "HS384" und "HS512").
- typ - Der Typ des Tokens, d. h. "JWT".
Diese müssen mit Base64URL kodiert sein, um den ersten Teil des JWT zu bilden. Beispiel:
- Header – {“alg”:”HS256″,”typ”:”JWT”}
- Encoded - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Wichtig: Die übermittelten Daten müssen mit Base64Url kodiert sein, nicht mit dem Standard Base64.
Generierung der payload
Bei der Übermittlung von Feldern in der payloadbefolgen Sie bitte die nachstehenden Empfehlungen:
- Die payload sollte enthalten alle Felder die Sie dem Kunden nicht erlauben wollen zu ändern (z.B. den Transaktionsbetrag).
- Die payload sollte nicht alle Felder enthalten, die der Kunde während der Kaufabwicklung ändern darf (z. B. seine Adresse oder Kontaktdaten).
Diese Felder werden dann mit Base64URL kodiert und bilden den zweiten Teil des JWT. Beispiel:
{
"iss": "jwt.user",
"iat": 1730900533,
"payload": {
"currencyiso3a": "GBP",
"orderreference": "MyOrder123",
"sitereference": "test_12345",
"accounttypedescription": "ECOM",
"requesttypedescriptions": ["THREEDQUERY","AUTH"],
"baseamount": "1050"
}
}
eyJpc3MiOiJqd3QudXNlciIsImlhdCI6MTczMDkwMDUzMywicGF5bG9hZCI6eyJjdXJyZW5jeWlzbzNhIjoiR0JQIiwib3JkZXJyZWZlcmVuY2UiOiJNeU9yZGVyMTIzIiwic2l0ZXJlZmVyZW5jZSI6InRlc3RfMTIzNDUiLCJhY2NvdW50dHlwZWRlc2NyaXB0aW9uIjoiRUNPTSIsInJlcXVlc3R0eXBlZGVzY3JpcHRpb25zIjpbIlRIUkVFRFFVRVJZIiwiQVVUSCJdLCJiYXNlYW1vdW50IjoiMTA1MCJ9fQ
Die baseamount Feld in der Tabelle payload Das obige Beispiel enthält einen Wert, der in Basiseinheiten angegeben wurde. Das bedeutet, dass der Wert ohne Dezimalpunkt angegeben wird, d.h. £10,50 würden als "1050" angegeben werden.
Wir ermöglichen Ihnen stattdessen die Übermittlung der mainamount hier, falls gewünscht. In diesem Fall wird der Wert in Haupteinheiten angegeben (£10,50 würde als "10.50" angegeben - beachten Sie das Dezimalkomma).
Überlegungen zum telefonischen Versandhandel (MOTO) Payloads
- "accounttypedescription = MOTO" eingereicht werden muss.
- Anders als bei ECOM-Transaktionen ist 3-D Secure für MOTO nicht anwendbar, daher können Sie bei der Erstellung Ihrer JWT-Nutzdaten “THREEDQUERY“ aus dem Feld requesttypedescriptions ausschließen.
Generierung der signature
Der letzte Teil des Tokens ist die signature. Die signature wird verwendet, um sicherzustellen, dass das Token nicht vom Kunden geändert wurde, bevor das abgeschickte Formular Trust Payments erreicht.
Die signature wird erstellt, indem die verschlüsselte header, die verschlüsselte payload, a “secret” und dem Algorithmus, der in der header, und sie dann zu unterschreiben.
Die “secret” ist eine geheime Passphrase (im String-Format), die Sie beim Signieren des JWT angeben müssen. Dies muss sein mit unserem Support-Team vereinbart vor der Bearbeitung von Anfragen an unser System.
Beim Speichern des Wertes der “secret” auf Ihrem System, müssen Sie sicherstellen, dass Sie dies auf sichere Weise tun.
Der Wert der “secret” darf nicht im Klartext gespeichert werden.
Beispiel - Wenn Sie den HMAC SHA256-Algorithmus verwenden möchten, muss die signature würde auf folgende Weise erstellt werden:
HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
secret)
Der letzte Schritt ist die Sicherstellung der signature ist Base64URL-kodiert.
Das Signieren von Token mit einem privaten Schlüssel wird nicht unterstützt.
Vollständiges JWT-Beispiel
Das Ergebnis sind drei durch Punkte (".") getrennte Base64URL-Strings:
Wenn wir die header, die payload und die signature aus den obigen Beispielen würden Sie folgende JWT erhalten:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJqd3QudXNlciIsImlhdCI6MTczMDkwMDUzMywicGF5bG9hZCI6eyJjdXJyZW5jeWlzbzNhIjoiR0JQIiwib3JkZXJyZWZlcmVuY2UiOiJNeU9yZGVyMTIzIiwic2l0ZXJlZmVyZW5jZSI6InRlc3RfMTIzNDUiLCJhY2NvdW50dHlwZWRlc2NyaXB0aW9uIjoiRUNPTSIsInJlcXVlc3R0eXBlZGVzY3JpcHRpb25zIjpbIlRIUkVFRFFVRVJZIiwiQVVUSCJdLCJiYXNlYW1vdW50IjoiMTA1MCJ9fQ.yFKDJyWUK7vTBMP9KjiKVzsplSBddrGi_yPeeCJgEgU
Das vollständige Token kann dann bei der Initialisierung der Bibliothek wie folgt eingefügt werden:
<html>
<head>
</head>
<body>
<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com" method="POST">
<div id="st-card-number"></div>
<div id="st-expiration-date"></div>
<div id="st-security-code"></div>
<button type="submit">Pay securely</button>
</form>
<script src="<CDN_DOMAIN>"></script>
<script>
(function() {
var st = SecureTrading({
jwt : 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJqd3QudXNlciIsImlhdCI6MTczMDkwMDUzMywicGF5bG9hZCI6eyJjdXJyZW5jeWlzbzNhIjoiR0JQIiwib3JkZXJyZWZlcmVuY2UiOiJNeU9yZGVyMTIzIiwic2l0ZXJlZmVyZW5jZSI6InRlc3RfMTIzNDUiLCJhY2NvdW50dHlwZWRlc2NyaXB0aW9uIjoiRUNPTSIsInJlcXVlc3R0eXBlZGVzY3JpcHRpb25zIjpbIlRIUkVFRFFVRVJZIiwiQVVUSCJdLCJiYXNlYW1vdW50IjoiMTA1MCJ9fQ.yFKDJyWUK7vTBMP9KjiKVzsplSBddrGi_yPeeCJgEgU'
});
st.Components();
})();
</script>
</body>
</html>
Ersetzen Sie <CDN_DOMAIN> mit einer unterstützten Domäne. Klicken Sie hier für eine vollständige Liste.
Aktualisierung des JWT während der Zahlungssitzung
Es kann vorkommen, dass Sie Ihr System so konfigurieren möchten, dass der JWT nach der ersten Anfrage, aber vor Abschluss der Zahlung aktualisiert wird.
Zum Beispiel, wenn der Kunde eine Spende tätigt und aufgefordert wird, einen individuellen Betrag zu wählen. Da der Betrag in der JWT enthalten sein muss, um zu verhindern, dass Dritte unbefugte Änderungen vornehmen, müssen Sie die JWT während der Zahlungssitzung aktualisieren, sobald der endgültige Betrag festgelegt wurde.
Klicken Sie hier, um Anweisungen zur Konfiguration zu erhalten.
JWT-Feld-Spezifikation
| Feld | Format | Beschreibung | ||
| JWT Payload |
|
|||
| iat | Numerisch (17) |
Zeit in Sekunden seit Unix epoch (generiert mit UTC). Klicken Sie hier für weitere Informationen. Der JWT ist für 1 Stunde ab dem Zeitpunkt der Übermittlung im iat. Sobald die JavaScript Library mit diesem JWT initialisiert wurde, hat der Kunde 15 Minuten Zeit, die Transaktion abzuschließen. |
||
| iss | Alphanumerisch (255) | Ihr JWT-Benutzername. | ||
| Payload Objekt | ||||
| accounttypedescription | Alphanumerisch (20) |
Für E-Commerce (ECOM) Lösungen, geben Sie "ECOM" in dieses Feld ein. Für MOTO Lösungen geben Sie bitte "MOTO" in dieses Feld ein. Abhängig von den Anforderungen. Wenden Sie sich für Hilfe an den Support. |
||
| authmethod | Alphanumerisch (5) |
Die folgenden Werte werden unterstützt: Der Inhalt von authmethod haben keinen Einfluss auf den Abrechnung Status der Transaktion. Abrechnung Status kann über settlestatus und settleduedate. Klicken Sie hier, um mehr über den Prozess Abrechnung zu erfahren. |
||
| billingprefixname | Alphanumerisch (25) | Das Präfix des Rechnungsnamens, aus der folgenden Liste: Herr, Frau, Dr., Prof., Hochwürden, Sir, Lord, Lady, Dame & Mx. | ||
| billingfirstname | Alphanumerisch (127) |
Die Rechnungsvorname. Erforderlich für Visa Secure Data Field Mandate. Erforderlich für Glücksspielanbieter. |
||
| billingmiddlename | Alphanumerisch (127) | Der mittlere Name der Rechnung. | ||
| billinglastname | Alphanumerisch (127) |
Die Rechnungsnachname. Erforderlich für Visa Secure Data Field Mandate. Erforderlich für Glücksspielanbieter. |
||
| billingsuffixname | Alphanumerisch (25) | Der Name des Rechnungssuffixes. | ||
| billingpremise | Alphanumerisch (25) |
Die Hausnummer oder die erste Zeile der Rechnungsadresse. |
||
| billingstreet | Alphanumerisch (127) |
Die Hausnummer oder die erste Zeile der Rechnungsadresse. |
||
| billingtown | Alphanumerisch (127) |
Die für die Rechnungsadresse eingegebene Stadt. |
||
| billingcounty | Alphanumerisch (127) |
Abrechnungsbezirk. Hinweis: Falls eingereicht, billingcountryiso2a erforderlich ist. |
||
| billingpostcode | Alphanumerisch (25) |
Die Rechnungspostleitzahl oder die Postleitzahl muss für den billingcountryiso2a vorgelegt. |
||
| billingcountryiso2a | iso2a |
Rechnungsland im iso2a-Format.
Erforderlich wenn billingcounty vorgelegt wird. Andernfalls ist dies fakultativ. |
||
| billingemail | E-Mail (255) |
Rechnungs-E-Mail Adresse. Erforderlich für Visa Secure Data Field Mandate, wenn billingtelephone nicht angegeben ist. |
||
| billingtelephone |
Alphanumerisch einschließlich Symbole (20) |
Telefonnummer für die Rechnungsstellung. Gültige Zeichen:
Erforderlich für Visa Secure Data Field Mandate, wenn billingemail nicht angegeben ist. |
||
| billingtelephonetype | Saibling (1) |
Typ der Telefonnummer für die Rechnungsstellung:
|
||
| credentialsonfile | Numerisch (1) |
Die folgenden Werte können übermittelt werden:
Dies ist erforderlich für Visa und Mastercard Transaktionen, bei denen der Händler die Funktion CoF nutzt. Wenn die Transaktion nicht für CoF in Frage kommt oder Sie die Anmeldeinformationen nicht für zukünftige Transaktionen verwenden möchten, können Sie dieses Feld auslassen. Visa und Mastercard haben vorgeschrieben, dass Sie die Zustimmung des Karteninhabers einholen müssen, bevor Sie Kartendaten für die zukünftige Verwendung speichern.
|
||
| customerprefixname | Alphanumerisch (25) | Name der Lieferung. | ||
| customerfirstname | Alphanumerisch (127) | |||
| customermiddlename | Alphanumerisch (127) | |||
| customerlastname | Alphanumerisch (127) | |||
| customersuffixname | Alphanumerisch (25) | |||
| customerpremise | Alphanumerisch (25) |
Lieferadresse. Die Zustellpostleitzahl oder der ZIP-Code muss für den Empfänger gültig sein. customercountryiso2a vorgelegt. |
||
| customerstreet | Alphanumerisch (127) | |||
| customertown | Alphanumerisch (127) | |||
| customercounty | Alphanumerisch (127) | |||
| customercountryiso2a | iso2a | |||
| customerpostcode | Alphanumerisch (25) | |||
| customeremail | E-Mail (255) | Liefer-E-Mail-Adresse. | ||
| customertelephone |
Alphanumerisch einschließlich Symbole (20) |
Telefonnummer für die Zustellung. Gültige Zeichen:
|
||
| customertelephonetype | Saibling (1) |
Art der Telefonnummer für die Lieferung:
|
||
| customfield1 | Alphanumerisch (100) |
Diese Felder ermöglichen die Übermittlung und Speicherung von benutzerdefinierten Daten in Trust Payments' Datensätzen. Diese Daten können später durch eine CSV Transaktionsdownload abgerufen werden .
Beispiel für einen Anwendungsfall: Für die Abstimmung kann es nützlich sein, den Sales Amount Verkaufsbetrag) und das Trinkgeld getrennt in zwei dieser benutzerdefinierten Felder zu erfassen, da baseamount/mainamount sind die Summe beider Felder. |
||
| customfield2 | ||||
| customfield3 | ||||
| customfield4 | ||||
| customfield5 | ||||
| currencyiso3a | iso3a |
Die Währung, in der die Transaktion verarbeitet wurde. |
||
| baseamount | Numerisch (13) |
Entweder baseamount oder mainamount muss enthalten sein (nicht beides).
Der Betrag der Transaktion in Basiseinheiten (ohne ohne Dezimalstellen). z.B. €10,50 würde als "1050" übermittelt werden |
||
| mainamount | Numerisch (14) |
Entweder baseamount oder mainamount muss enthalten sein (nicht beides).
Der Betrag der Transaktion in Haupteinheiten. |
||
| initiationreason | Saibling (1) |
Dies ist erforderlich, wenn Sie eine vom Händler initiierte Transaktion verarbeiten (MIT). Ermöglicht es Ihnen, einen Grund für die Transaktion anzugeben. Nicht einreichen, wenn eine kundeninitiierte Transaktion verarbeitet wird (CIT). Die zulässigen Werte für dieses Feld sind "A", "C", "D", "S" und "X".
Weitere Informationen entnehmen Sie bitte der Dokumentation von Visa. |
||
| locale | Unbestimmt |
Standardmäßig werden das Kassenformular und alle angezeigten Fehlermeldungen in britischem Englisch wiedergegeben. Dieses Verhalten kann jedoch durch die folgende Eingabe außer Kraft gesetzt werden locale Werte in der payload:
|
||
| operatorname | Alphanumerisch (255) | Der Wert dieses Feldes enthält den Namen des Benutzers, der die Anfrage bearbeitet hat. Dies ist optional. Wird es weggelassen, wird stattdessen der Wert des Alias aufgezeichnet, der je nach Ihrer Konfiguration entweder Ihr Website-Referenz oder Ihr Web Services-Benutzername ist. | ||
| orderreference |
Alphanumerisch (25) Siehe Beschreibung rechts für weitere Details |
Ihre eindeutige Auftragsnummer, die im System Trust Payments gespeichert werden kann. Wir empfehlen Ihnen dringend, eine orderreference für jede Transaktion. Empfohlene Länge 25 Zeichen oder weniger (genaue Länge abhängig von der erwerbenden Bank). Die Nichteinhaltung dieser Anforderung kann dazu führen, dass der Text in der Transaktion abgeschnitten wird. |
||
| parenttransactionreference | Alphanumerisch einschließlich Bindestriche (25) | Ermöglicht Ihnen die Angabe der transactionreference einer früheren Anfrage. Die wichtigsten Details werden von diesem Antrag übernommen. | ||
| requesttypedescriptions | Liste |
Die zu bearbeitenden Anfragetypen. Wichtig! Bei E-Commerce-Transaktionen (ECOM) müssen Sie sicherstellen, dass “THREEDQUERY” wird bei der Durchführung von Transaktionen in dieser Liste angegeben, um sicherzustellen, dass 3-D Secure verarbeitet wird. Dies ist erforderlich für die PSD2 Mandat. Um mehr über die unterstützten Antragsarten zu erfahren, klicken Sie hier. |
||
| scaexemptionindicator | Numerisch (1) |
Wird verwendet, um die Art der 3-D Secure -Authentifizierung in Szenarien zu beeinflussen, in denen dies zulässig ist. Hinweis: Wird nur von bestimmten Acquiring-Banken unterstützt. Kontaktieren Sie das Support-Team für weitere Informationen. Geben Sie einen der folgenden Werte an, wenn Sie die Transaktion von der Authentifizierung ausnehmen:
Wenden Sie sich bitte an Ihren Anwerber, um zu prüfen, ob Sie Ausnahmen beantragen dürfen, bevor Sie dies tun. Alternativ können Sie auch einen der folgenden Werte eingeben, um eine Authentifizierung nach oben (Challenge) anzufordern:
|
||
| settleduedate | Datum JJJJ-MM-TT |
Hier können Sie den Tag in der Zukunft angeben, an dem Ihre Transaktion abgerechnet werden soll. Die Angabe muss im Format erfolgen: JJJJ-MM-TT. |
||
| settlestatus | Numerisch (3) |
Ein numerischer Wert, der zur Definition der Anweisung Abrechnung verwendet wird.
|
||
| sitereference | Alphanumerisch (50) | Eindeutige Referenz, die Ihre Website Trust Payments identifiziert. | ||
| subscriptionbegindate | Datum JJJJ-MM-TT |
Optional bei der Terminierung von Abonnements. Dieses Feld bezieht sich auf das Datum, an dem die erste automatisiert Die Zahlung wird bearbeitet. Von da an verwenden wir die Daten, die im Formular subscriptionunit und subscriptionfrequency Felder, um die Abonnementzahlungen in regelmäßigen Abständen automatisch zu verarbeiten. Wenn z. B. ein Zeichnungsantrag am 5. Januar 2018 eingereicht wird das Intervall ist 1 MONTH (subscriptionfrequency = 1 and subscriptionunit = MONTH) und subscriptionbegindate ist 2018-01-08, die erste automatische Zahlung wird am 8. Januar 2018 verarbeitet, alle weiteren Zahlungen werden am 8. eines jeden Monats verarbeitet. Wenn Sie den Antrag nicht einreichen subscriptionbegindate, werden wir die subscriptionunit und subscriptionfrequency um automatisch die erste automatische Zahlung zu planen. |
||
| subscriptionfinalnumber | Numerisch (5) |
Erforderlich bei der Terminierung von Abonnements. Hier wird die Anzahl der Zahlungen festgelegt, die während der Laufzeit des Abonnements verarbeitet werden sollen:
Anmerkung: Wenn der Wert "0" ist, plant die Abonnementmodul Zahlungen auf unbestimmte Zeit, bis der Benutzer das Abonnement manuell auf inaktiv setzt. |
||
| subscriptionfrequency | Numerisch (11) |
Erforderlich bei der Terminierung von Abonnements. Kombiniert mit subscriptionunit, die Häufigkeit legt fest, wie häufig Zahlungen verarbeitet werden, z.B. für eine Zahlung alle 7 Tage: subscriptionfrequency = 7 und subscriptionunit = DAY z.B. für eine Zahlung alle 2 Monate: subscriptionfrequency = 2 und subscriptionunit = MONTH |
||
| subscriptionnumber | Numerisch (5) |
Optional bei der Terminierung von Abonnements. Wenn nicht anders angegeben, beginnen die Abonnements mit subscriptionnumber = 1 standardmäßig. Die Website subscriptionnumber wird bei jeder weiteren Abonnementzahlung automatisch erhöht, bis er den Wert des subscriptionfinalnumber Feld, wenn keine weiteren Zahlungen mehr versucht werden. Ein abgeschlossenes Abonnement wird durch ein subscriptionnumber der höher ist als der entsprechende subscriptionfinalnumber. |
||
| subscriptiontype | Alpha (11) |
Erforderlich bei der Terminierung von Abonnements. Dieses Feld gibt die Art des zu bearbeitenden Abonnements an. Ihr System kann diese beiden Werte übermitteln:
*INSTALLMENT wird von Händlern mit einem Trust Payments Acquiring-Konto unterstützt. Wenn Sie eine andere Acquiring-Bank verwenden, müssen Sie Kontakt zu unserem Support-Team um zu prüfen, ob diese Funktion unterstützt wird, bevor Sie fortfahren. |
||
| subscriptionunit | Alpha (5) |
Erforderlich bei der Terminierung von Abonnements. Dieses Feld gibt die Zeiteinheit zwischen den einzelnen Abonnements an. Dies kann entweder sein “DAY” oder “MONTH”. Anmerkung: Dieses Feld muss unbedingt in GROSSBUCHSTABEN an das Gateway übermittelt werden (“DAY” oder “MONTH”). |
||
|
threedbypasspaymenttypes
|
Liste | Um die Anforderungen von PSD2 zu erfüllen, müssen Sie bei allen unterstützten kartenbasierten E-Commerce-Transaktionen eine 3-D Secure Authentifizierung durchführen. Dies wird erreicht, indem Sie sicherstellen THREEDQUERY ist enthalten in der requesttypedescriptions Liste im JWT payload. Es kann jedoch vorkommen, dass 3-D Secure von Ihrer Bank nicht verlangt oder unterstützt wird. Durch die Angabe von Zahlungsarten in der threedbypasspaymenttypes Liste, wird die Authentifizierung 3-D Secure für die oben genannten Zahlungsarten nicht durchgeführt. | ||
| transactionactive | Numerisch (1) |
Optional bei der Terminierung von Abonnements. Der Status des Abonnements. "0" - Inaktiv: Setzt zukünftige Zahlungen aus, bis sie manuell überschrieben werden. "1" - Aktiv: Plant Abonnementzahlungen sofort und umgeht Betrug und doppelte Prüfungen (falls aktiviert). "2" - Ausstehend (Standard): plant Abonnementzahlungen, nachdem die AUTH abgerechnet wurde (settlestatus "100"). |
||
Ihr Fortschritt
Nachdem Sie nun Ihr Zahlungsformular erstellt, JavaScript Library konfiguriert und Ihr JWT eingebunden haben, empfehlen wir Ihnen, Webhooks zu konfigurieren, um sicherzustellen, dass Sie über Transaktionen auf Ihrem Konto benachrichtigt werden.
