Einen einfachen API Aufruf erzeugen
Ein API-Aufruf an das Computop Paygate erfolgt immer nach demselben Ablauf:
Libraries für HMAC und Blowfish
Hier finden Sie einige vorgefertigte Libraries, welche Sie bei der HMAC-Berechnung und er Blowfish-Verschlüsselung unterstützen: Implementierungsbeispiele
(Libraries für die AES-Verschlüsselung sind in Arbeit und sind bald verfügbar)
Merchant Zugangsdaten
Sie erhalten die Zugangsdaten nach Vertragsabschluss. Die Zugangsdaten bestehen aus:
- MerchantId: HändlerID als Zugang zum Computop Paygate
- HMAC-Passwort: Ein Passwort, mit dem der MAC-Wert berechnet wird, um spezifische Werte im Request/Anfrage (z.B. amount, currency) bzw. Response/Antwort (z.B. status, code) vor Manipulation zu schützen.
- Blowfish/AES-Passwort: Ein Passwort mit dem der gesamte Request/Anfrage zum Computop Paygate verschlüsselt wird bzw. dessen Response/Antwort.
Sie erhalten ggf. mehrere MerchantIds/HändlerIDs für unterschiedliche Konfigurationen (z.B. Zahlarten, Währungen, Services). Jeder Satz besteht dann aus einer eigenen MechantId und jeweils unterschiedlichen Passwörtern.
Beispiel
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:
- HMAC Berechnung, um die Werte von amount und currency besonders zu schützen
- stellen alle API Parameters zusammen - zunächst unverschlüsselt
- verschlüsseln alle relevanten API Parameter → und erhalten so "Data" + "Len" für den API Aufruf
- anschließend fügen wir weitere API-Parameter hinzu, um die Hosted Payment Page anzupassen, indem wir ein spezielles Template verwenden und die angezeigte Sprache vordefinieren
- senden den API Aufruf an den entsprechenden Endpunkt.
HMAC Berechnung
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 Computop 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:
- falls ein Wert nicht vorhanden ist einfach leer lassen, z.B.:
- mit Betrag/Währung, ohne PayId, um eine neue Zahlung auszulösen - wie in diesem Beispiel:
HmacSHA256("*TID-4453732122167114558*yourMerchantId*1234*EUR", "mySecret") - mit Betrag/Währung, ohne PayId, ohne TransId:
HmacSHA256("**yourMerchantId*1234*EUR", "mySecret") - mit PayId, ohne amount/currency:
HmacSHA256("fe3f002e19814eea8aa733ec4fdacafe*TID-4453732122167114558*yourMerchantId**", "mySecret")
- mit Betrag/Währung, ohne PayId, um eine neue Zahlung auszulösen - wie in diesem Beispiel:
hier finden Sie weitere Details zur HMAC-Berechnung
für Requests/Anfragen: HMAC-Authentisierung (Anfrage)
- für Response/Benachrichtigungen/Notifies: HMAC Authentication (NHMAC-Authentisierung (Notify)otify)
- Sie können hier eine Anwendung zur Verifizierung Ihrer HMAC-Berechnung und Blowfish-Verschlüsselung finden: https://computop.com/de/developer/paygate-test
Parameter vor der Verschlüsselung mittels Blowfish
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 Computop Paygate |
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 Computop Paygate |
| Response=encrypt | Computop Paygate soll die Antwortdaten 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)):
- Sie müssen also "MsgVers=2.0" hinzufügen, um 3-D Secure 2.x für Kreditkartenformular (PaySSL) zu aktivieren.
- Sie können andere Key-Value-Paare für andere Zahlarten angeben (z. B. PayPal)
Verschlüsseln der Parameter mittels Blowfish, um Data/Len zu erhalten
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.
Notizen
- Der Wert für "Len" ist die Länge des unverschlüsselten Parameterstrings, der im vorherigen Schritt erstellt wurde.
- Blowfish ist die Standard-Verschlüsselung für Computop Paygate
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 |
Beispiel
| Element | Wert |
|---|---|
| MerchantID | yourMerchantId |
| Password | TestTestTestTest |
| Unencrypted request | MerchantID=yourMerchantId&MsgVer=2.0&TransID=TID-18724420542167170812&RefNr=RG123-2023&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 |
| Len | 354 |
| Data | 397fb1b3eadb19c4c4610422e3426cecbc9e5f3c83ff04be4d78a63827839703847465e7118da27f8e186b7053923d5189c321d6bb04dbe1f147561184fc3c4c999861c69b79a94a1a44494219adaec1688765fa72282e04eca73b5725996acddfb874a615610df41c4eb8ae12bc62eece8c44dc50726afcf4d249d8a4d5af7ee93f9ea95839bf6ffcaa94eaa70e46f002b5954c3bbe9ae2a69ee1b451cf8d96387c09c4c7300ab95e5850df082d778a31f84e7c3722760d5f71927869a1ab3139154673d908a96ab2f5be4493b10112a4fa825b257310b79834027703224aa831f84e7c3722760d5f71927869a1ab314f78b3f489b9b6e165163bbdbb086ca49072acdfbb9fa317d847056fc38d6e0ec7a19685cfc7eaf733c965596e2a2df611686b5078cbf4f3f73338a8769334d88b674fa0ef1a03ffa518668a6f12e6fd0a4ab5fdfb093354f551c52de3a75c0a113dd8837ba810ae8926051ed6edbfcc3c1aef6417699fb6 |
- Sie können hier eine Anwendung zur Verifizierung Ihrer HMAC-Berechnung und Blowfish-Verschlüsselung finden: https://computop.com/de/developer/paygate-test
- Wählen Sie dort bitte Blowfish/ECB aus
Verschlüsseln der Parameter mittels AES, um Data/Len zu erhalten
Die Rohparameter werden mittels AES/CBC/PKCS7 verschlüsselt und dann hex-kodiert.
Notizen
- AES 128 / AES 192 / AES 256 werden unterstützt und sind abhängig von der Passwort-Länge mit 16, 24 or 32 Byte
- AES kann auf Anfrage vom Computop Helpdesk für Sie aktiviert werden.
- Libraries für AES Verschlüsselung sind in Arbeit; unten finden Sie einige Links zu Implementierungshilfen.
- AES benötigt eigentlich keinen LEN-Parameter, wird aber aus Kompatibilität weiterhin benötigt.
- AES wird mit einem Initialization Vector (IV) mit 16 Bytes verwendet. Der IV ist Bin2Hex-encoded und unverschlüsselt als Teil des Data geschickt: Data=
concat(Bin2Hex(IV), "-", Bin2Hex(encryptedData)) - Der Initialization Vector (IV) wird bei jeder Verschlüsselung erneut und zufällig generiert und unverschlüsselt (Bin2Hex-encoded) mitgeschickt und zur Entschlüsselung verwendet.
Um Ihre Integration zu erleichtern, finden Sie hier einige Links zur AES CBC Verschlüsselung:
Beispiel
| Element | Wert |
|---|---|
| MerchantID | yourMerchantId |
| Password | TestTestTestTest |
| Unencrypted request | MerchantID=yourMerchantId&MsgVer=2.0&TransID=TID-18724420542167170812&RefNr=RG123-2023&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 |
| Len | 354 |
| Data | 5b447021b775137d2a4249f271200071-634f5b121cf01f3bcc060f00827fb55affe364be050a36a9e97e9571ea1c2c150731300051cb2618f4e6809f72ecdf284e81ef465e0db2b808f5104f79d92cb4055dd60a5227cc82b82d240d502e51a60606c82c69bed317e117cdbb110cdd2cc8a7712a18c398990cc47a532cdf8caef6a32f048b51576de4d2575c9cf61ce08c3f6a441ea8e553028b6b7f908ebe0c34e3ed064b17b32f0a2afc7873ec16d10eaa7780ec89c1c6b1a0d68508cf9dbb916e27adcb08aeb774880c61001e66a10c841f0742fca82882260c511ab2a9ee9252ac88c6833b265fb70bb0f99af65b15434d052106dee38d2262ab72973aa28940da8c99c35f57f6fe5c065005b1c1e726b60eaeaba8fd3ed32edfdcbae52af9c92c0ba7c1a7edf88888a1f9af9055a105803beacbf5627d1d4a95b6aceebeb4f27b1fab6b47bfc8a2542b527b12514e80c959d038c177473363095b0aeff333962c4d5054bc293fea6402fac1fda8fab81b6d3c8127a709e3bbe1dfed19ae |
| Notiz | 5b447021b775137d2a4249f271200071 ist der Initialization Vector (IV) 16 Bytes, welcher bei der AES Verschlüsselung gebildet und unverschlüsselt ins Data eingefügt wird. |
- Sie können hier eine Anwendung zur Verifizierung Ihrer HMAC-Berechnung und Blowfish-Verschlüsselung finden: https://computop.com/de/developer/paygate-test
- Wählen Sie dort bitte AES/CBC (IV part of DATA) aus
Nun fügen wir alles zusammen - der API Request/Aufruf
Der API Request/Aufruf wird dann wie folgt zusammengestellt:
| Wert | Kommentar / Beschreibung |
|---|---|
| Basis Parameter | |
| z.B. paymentPage.aspx | Gewünschter Endpunkt von Computop Paygate |
| MerchantID=yourMerchantId | Ihre MerchantId zur Identifizierung Ihres Aufrufes im Computop Paygate (zusätzlich unverschlüsselt anzugeben) |
| Len=<Len>&Data=<Data> | Länge des unverschlüsselten Parameterstrings vor der Verschlüsselung |
| Template Parameter (unverschlüsselt) | |
| Template=PaymentPageDropDown_v1 | Template für die Hosted Payment Page (HPP) |
| CCTemplate=Cards_v1 | Template für das Credit Card Form (aufgerufen von der HPP) |
| SDDTemplate=DirectDebit_v1 | Template für das Direct Debit Form (aufgerufen von der HPP) |
| Language=en | Initiale Anzeigesprache für den Käufer |
| CustomField1..16 | Zusätzliche Parameter CustomField, um ggf. weitere Informationen auf der Hosted Payment Page durch das Template anzuzeigen. |
https://www.computop-paygate.com/paymentPage.aspx?MerchantID=yourMerchantId&Data=397fb1b3eadb19c4c4610422e3426cecbc9e5f3c83ff04be4d78a63827839703847465e7118da27f8e186b7053923d5189c321d6bb04dbe1f147561184fc3c4c999861c69b79a94a1a44494219adaec1688765fa72282e04eca73b5725996acddfb874a615610df41c4eb8ae12bc62eece8c44dc50726afcf4d249d8a4d5af7ee93f9ea95839bf6ffcaa94eaa70e46f002b5954c3bbe9ae2a69ee1b451cf8d96387c09c4c7300ab95e5850df082d778a31f84e7c3722760d5f71927869a1ab3139154673d908a96ab2f5be4493b10112a4fa825b257310b79834027703224aa831f84e7c3722760d5f71927869a1ab314f78b3f489b9b6e165163bbdbb086ca49072acdfbb9fa317d847056fc38d6e0ec7a19685cfc7eaf733c965596e2a2df611686b5078cbf4f3f73338a8769334d88b674fa0ef1a03ffa518668a6f12e6fd0a4ab5fdfb093354f551c52de3a75c0a113dd8837ba810ae8926051ed6edbfcc3c1aef6417699fb6&Len=354&Template=PaymentPageDropDown_v1&Language=en&CCTemplate=Cards_v1&SDDTemplate=DirectDebit_v1&URLBack=https%3A%2F%2Fwww.yourshop.info%2F&CustomField1=12%2C34+EUR&CustomField2=Order+Text&CustomField3=https%3A%2F%2Fwww.paytest.info%2Fphantasy-logo.png&CustomField4=Shopping+Cart&CustomField5=Company+Name&CustomField6=First+Name&CustomField7=Stra%C3%9Fe+4&CustomField8=12345+City&CustomField9=Shipping+Company&CustomField10=Shipping+Name&CustomField11=Shipping+Street&CustomField12=23456+Shipping+City&CustomField13=RG-Inv+123%2F2021&CustomField14=Some+Label&CustomField15=Some+Text&PayType=0
Diese URL wird nicht funktionieren und eine "Unexpected exception" als Ergebnis bringen, da die MerchantId "yourMerchantId" nicht existiert. Sie finden funktionierende URLs weiter unten.
Putting API-call together
Der API-Aufruf besteht aus:
| Kategorie | Beschreibung |
|---|---|
Computop Paygate endpoint | e.g. https://www.computop-paygate.com/paymentPage.aspx |
| MerchantID=<> | MerchantID=YourMerchantID |
| Len & Data | Verschlüsselte API-Daten |
| Zusätzliche Parameter | Zusätzliche Key-Value-Parameter, unverschlüsselt |
Senden des API request
Ein Request kann entweder per GET oder per POST gesendet werden. Wir empfehlen aus folgenden Gründen das Verwenden von POST:
- bei GET ist die Länge des Requests auf 2048 Bytes beschränkt in Abhängigkeit des Browsers - während die Grenze bei Post auf 5120 Bytes beschränkt ist. Sollten Sie längere Requests benötigen, so wenden Sie sich bitte an unseren Computop Helpdesk
- via GET the parameters are attached to the URL which can be easily manipulated by a customer - therefore The page .Wording vDocumentation was not found -- Please check/update the page name used in the MultiExcerpt-Include macro prevents manipulation using Blowfish/AES encryption
Prüfen der Paygate Antwort
Server-2-Server Antwort
Bei Server-2-Server-Aufrufen wird der Aufruf mit einer direkten Antwort beantwortet, die Folgendes enthält
- einen Status, der den Erfolg oder Misserfolg der Transaktion anzeigt
- ein Code (Antwortcode), der Details der Transaktion zusammen mit einer Beschreibung erläutert
- weitere Daten wie PayId für jeden Bezahlvorgang
- und andere Daten je nach Art der Transaktion
Payment Page / ansynchrone Benachrichtigung (Notification)
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.
Allgemein
Bitte prüfen Sie:
- nur zu prüfen, ob "URLFailed" oder "URLSuccess" aufgerufen wurde, reicht nicht aus und kann leicht missbraucht werden
- Response code: nur "code=00000000" zeigt eine vollständige und abgeschlossene Verarbeitung an
- prüfen Sie, ob der MAC-Wert in der Computop Paygate Antwort gültig ist - um sicherzustellen, dass die Antwort nicht manipuliert wurde.
Einige Tipps für Paygate Antworten
Some tips on responses
| Result | Description |
|---|---|
| Unexpected exception | Computop Paygate Antwort enthält keinen "code" und keinen "status". Vermutlich haben Sie eine ungültige MerchantId oder ein ungültiges Template verwendet. Weitere Informationen zu Templates finden Sie bei unseren Hosted Payment Pages. |
| Computop Paygate hat einen Fehler im API-Aufruf entdeckt und konnte keinen Zahlungsvorgang/Zahlungstransaktion anlegen. Diese Zahlungsvorgänge können nicht in Computop Analytics gefunden werden. Eine Übersicht der Antwort-Codes finden Sie hier: Response codes |
| Ein Zahlungsvorgang konnte angelegt werden, jedoch wurde von einem nachgelagerten System ein Fehler erkannt. Eine Übersicht der Antwort-Codes finden Sie hier: Response codes |
| Der Betrag ist der erste Parameter, welcher geprüft wird. Der Betrag wird als kleinste Währungseinheit und ohne Dezimalpunkt-/komma angegeben. Es kann auch sein, dass Sie ihre verschiedenen MIDs und Verschlüsselungs-Passwörter vertauscht haben. |
| Zahlungsvorgang-/transaktion ist erfolgreich und abgeschlossen |
| Zahlungsvorgang-/transaktion ist erfolgreich, aber noch nicht endgültig abgeschlossen |
Einige URLs zum direkten Aufruf und "Spielen"
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. ( |
| 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. ( |
