Wir möchten einen API-Aufruf erstellen zur Zahlung von 12,34 EUR über die Hosted Payment Page, welche in englischer Sprache dargestellt werden und weitere Bestelldetails anzeigen soll. Für Kreditkartenzahlungen (z.B. Mastercard, VISA, American Express) soll 3-D Secure 2.x verwendet werden. Es stehen aber auch abhängig von Ihrer MerchantId-Konfiguration weitere Zahlarten wie PayPal, Lastschrift, Sofort, ... zur Verfügung. |
Dazu gehen wir wie folgt vor:
Der MAC-Wert wird stets wie folgt berechnet HmacSHA256("PayId*TransID*MerchantID*Amount*Currency", "YourHmacPassword")
mit:
Key | Wert | Kommentar |
---|---|---|
PayId | Referenzierte PayId | Ist bei initialen Zahlungsrequest leer und wird bei nachfolgenden Aufrufen wie "Buchung", "Gutschrift", "Storno", ... verwendet. |
TransId | Ihre eindeutige TransactionId in Ihrem System | Ihre TransactionId/Referenz, um Ihren Aufruf in Ihrem System eindeutig referenzieren bzw. identifizieren zu können |
MerchantId | Ihre MerchantId für diesen Aufruf | Die MerchantId, welche Ihnen von zugewiesen wurde |
Amount | Betrag in der kleinsten Währungseinheit, z.B. 123=1,23 (EUR) | Betrag für diesen Aufruf; kann leer sein z.B. für Status-Abfragen (Status Inquiries). |
Currency | Währung dieses Zahlungsvorganges gemäß ISO 4217, z.B. EUR, USD, GBP | Währung für diesen Aufruf; kann leer sein z.B. für Status-Abfragen (Status Inquiries). |
YourHmacPasswort | Ihr HMAC-Passwort für diese MerchantId | Ihr HMAC-Passwort welches Ihnen für diese Merchant Id zugewiesen wurde. Wenn Sie mehrere MerchantIds haben, so haben Sie auch mehrere HMAC Passwörter. |
Notizen:
HmacSHA256("*TID-4453732122167114558*yourMerchantId*1234*EUR", "mySecret")
HmacSHA256("**yourMerchantId*1234*EUR", "mySecret")
HmacSHA256("fe3f002e19814eea8aa733ec4fdacafe*TID-4453732122167114558*yourMerchantId**", "mySecret")
hier finden Sie weitere Details zur HMAC-Berechnung
für Requests/Anfragen: HMAC-Authentisierung (Anfrage)
Die Roh-Parameter definieren die Basis-Einstellungen für diesen Zahlungsvorgang, z.B. Ihre MerchantId, Betrag, Währung, IhreReferenz und die URLs für erfolgreich ("success"), Fehler ("failure") sowie Abbruch ("back") und Benachrichtigung ("notify"):
Key-Value | Kommentar |
---|---|
MerchantID=IhreMerchantId | Ihre MerchantId auf dem |
MsgVer=2.0 | Legt fest, dass 3-D Secure 2.x verwendet werden soll; Im Zusammenhang mit 3-D Secure 2.x ist es möglich und sinnvoll, weitere zusätzliche Daten (wie Rechnungs- und Lieferadresse) zu übermitteln, um die manuelle Authentifizierung ("challenge") des Käufers zu vermeiden und eine reibungslose Autorisierung ("frictionless") zu erreichen. Diese zusätzlichen Daten werden in einer JSON-Struktur übermittelt. |
TransID=TID-18724420542167170812 | Ihre TransactionId, um den Aufruf in Ihrem System zu identifizieren |
RefNr=RG123-2021 | Ihre Referenz auf diesen Zahlungsvorgang, z.B. Rechnungsnummer |
Amount=1234 | Der Betrag in kleinster Währungseinheit, z.B. 1234 + EUR → 12,34 EUR |
Currency=EUR | und Währung |
URLSuccess, URLFailure, URLBack | URLs zur Weiterleitung des Käufers für erfolgreich ("success"), Fehler ("failure") sowie Abbruch ("back") |
URLNotify | URL zum Empfang von Benachrichtigungen ("notify") des |
Response=encrypt | soll die Antwortdaten per Blowfish verschlüsseln |
Language=en | Der Käufer wünscht Anzeige in englischer Sprache |
MerchantID=yourMerchantId&MsgVer=2.0&TransID=TID-18724420542167170812&RefNr=RG123-2021&Amount=1234&Currency=EUR&URLSuccess=https://www.yourshop.info/success.php&URLFailure=https://www.yourshop.info/failure.php&URLNotify=https://www.yourshop.info/notify.php&Response=encrypt&MAC=ca3c75eaf2120dfd15de77af2398b1561d8473f647b72aa7270fde94df7756d6&Language=en |
Da die Zeichen "=" und "&" für das Bilden der Key-Value-Paare verwendet werden, dürfen diese Werte nicht Bestandteil der Werte selbst sein. Senden Sie keine leeren Werte, sondern Key-Value-Paare für die entsprechende Zahlart bzw. Zahlungsvorgang, die auch wirklich Werte enthalten. Für die Kreditkartenverarbeitung mit 3-D Secure 2.x (EMV 3DS) müssen Sie den Parameter "MsgVers=2.0" hinzufügen. Die gehostete Zahlungsseite funktioniert wie ein Proxy für die anderen Zahlungsformen (z. B. Kreditkartenformular (PaySSL), Lastschriftformular (PaySDD), zahlartenspezifische Formulare (z. B. PayPal)):
|
Die Rohparameter werden mittels Blowfish ECB verschlüsselt und dann hex-kodiert. Für den schnellen Einstieg stellen wir Ihnen in unseren Toolkits vordefinierte Funktionen zur Verfügung. Die oben gezeigten und unverschlüsselten Daten werden verschlüsselt in:
Len=342& Data=550a705ffb8fb2d59f72a116a55b26ef97d92d6ebec45ea10efe79b05d93f6fd6a69e8f810509d7e754899153e459f05cfd2c9bd9e71f92acda33e453f329a641328b32411b5c08ded80711c13d64e01d2cbae26a884f8c8781db17f31434fe34032ec5ef961dfb53006add8abc7f9cfa39d582962f3a70af105eb1f2240376e358d7cf8a7dadfef6afeac3bf0f043f578f5040995a7b29ca23fbcc0f84f5e416fe1ef60c3ff58028b3aa017b2fb50715fc3ef42b3947cc89f2639f61f6dbd8fea1f0b17716115676b2762ea14f0ca8d6fe1ef60c3ff58028b3aa017b2fb50715fc3ef42b3947cc86f80ef28614f1f739345550e4a0fc83bc7ca605f8477fcb5fa93da00daa0bddf9faace1829eeea32c8ffd87cffaf85930479d79b121d2662172cd81022e35232777bedb997aeb1deba02dc2fc4af5297802ace7338757a9058e220fd1c0abb8b2f3d8309b9d7375cae9897dc2aeda201 |
Notizen:
Um Ihre Integration zu erleichtern, bieten wir vordefinierte Funktionen, die Ihnen mit Blowfish ECB helfen:
Ihre Programmiersprache | Wo Sie die Funktionen finden |
---|---|
ASP | txmsCrypto.dll // txmsCrypto.BlowFish |
ASP.NET | CompuTop.Core.Crypto.dll // CompuTop.Core.Crypto.BlowFish |
Java | Blowfish.java |
PHP | function.inc.php ctHMAC ctEncrypt ctDecrypt |
Der Wert für "Len" ist die Länge des unverschlüsselten Parameterstrings, der im vorherigen Schritt erstellt wurde.
Bei Server-2-Server-Aufrufen wird der Aufruf mit einer direkten Antwort beantwortet, die Folgendes enthält
Im Falle einer Weiterleitungszahlung (Redirect) wird eine asynchrone Benachrichtigung (Notification) an Ihr System (URLNotify) gesendet.
Die Antwort kann entweder verschlüsselt oder im Klartext erfolgen – wir empfehlen eine verschlüsselte Antwort.
Bitte prüfen Sie:
|
Hier können Sie einige Testdaten finden: Test Handbuch. Einige Zahlungsvorgänge verursachen Fehler, um Missbrauch zu unterbinden.
Klicken und versuchen | Beschreibung | Notizen |
---|---|---|
Klicken und versuchen | Link zur Hosted Payment Page ohne spezifische Vorlagendaten, um einen Zahlungsvorgang für 12,34 EUR zu starten | Keine Template-Daten definiert |
Klicken und versuchen | Dieselben Daten (Len + Data) können mit der Hosted Payment Page verwendet werden, indem andere Templates für die Hosted Payment Page verwendet werden. Die Templates werden sowohl für die Hosted Payment Page (Startseite) als auch für Kartenzahlungen bzw. Lastschriften angegeben. | Da wir die "Hosted Payment Page" als Startseite verwenden, können wir zusätzlich andere Templates für Karten- und Lastschriftzahlungen angeben: Template=PaymentPageDropDown_v1&Language=en&CCTemplate=Cards_v1&SDDTemplate=DirectDebit_v1 Wir können bei diesen Templates auch einige "CustomFields" angeben, um Informationen für den Endkunden darzustellen. Ändern Sie einfach "CustomField3", um ein eigenes Logo anzeigen zu lassen. ( Die "CustomFields" müssen speziell vom Template unterstützt werden.) |
Klicken und versuchen | Dieselben Daten (Len + Data) können auch für Kreditkartenzahlungen (PaySSL) verwendet werden. | Da wir hier direkt "PaySSL" als Endpunkt aufrufen, wird hier das Template "Cards_v1" verwendet: Template=Cards_v1&Language=en Ändern Sie einfach "CustomField3", um ein eigenes Logo anzeigen zu lassen. ( Die "CustomFields" müssen speziell vom Template unterstützt werden.) |