Beispiel
Info |
---|
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
| ||||||||
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
| ||||||||
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 |
| ||||||||
Language=en | Der Käufer wünscht Anzeige in englischer Sprache |
Code Block | ||||
---|---|---|---|---|
| ||||
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 |
Info |
---|
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)):
|
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. Die oben gezeigten und unverschlüsselten Daten werden verschlüsselt in:
Code Block | ||||
---|---|---|---|---|
| ||||
Len=342&
Data=550a705ffb8fb2d59f72a116a55b26ef97d92d6ebec45ea10efe79b05d93f6fd6a69e8f810509d7e754899153e459f05cfd2c9bd9e71f92acda33e453f329a641328b32411b5c08ded80711c13d64e01d2cbae26a884f8c8781db17f31434fe34032ec5ef961dfb53006add8abc7f9cfa39d582962f3a70af105eb1f2240376e358d7cf8a7dadfef6afeac3bf0f043f578f5040995a7b29ca23fbcc0f84f5e416fe1ef60c3ff58028b3aa017b2fb50715fc3ef42b3947cc89f2639f61f6dbd8fea1f0b17716115676b2762ea14f0ca8d6fe1ef60c3ff58028b3aa017b2fb50715fc3ef42b3947cc86f80ef28614f1f739345550e4a0fc83bc7ca605f8477fcb5fa93da00daa0bddf9faace1829eeea32c8ffd87cffaf85930479d79b121d2662172cd81022e35232777bedb997aeb1deba02dc2fc4af5297802ace7338757a9058e220fd1c0abb8b2f3d8309b9d7375cae9897dc2aeda201 |
Notizen:
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
Multiexcerpt include MultiExcerptName Platform-Name PageWithExcerpt Wording
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.
- Sie können hier eine Anwendung zur Verifizierung Ihrer HMAC-Berechnung und Blowfish-Verschlüsselung finden: https://computop.com/de/developer/paygate-test
Nun fügen wir alles zusammen - der API Request/Aufruf
Der API Request/Aufruf wird dann wie folgt zusammengestellt:
Gewünschter Endpunkt von
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Ihre MerchantId zur Identifizierung Ihres Aufrufes im
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Template für das Credit Card Form (aufgerufen von der HPP)
Template für das Direct Debit Form (aufgerufen von der HPP)
Initiale Anzeigesprache für den Käufer
Zusätzliche Parameter CustomField, um ggf. weitere Informationen auf der Hosted Payment Page durch das Template anzuzeigen.
Code Block | ||||
---|---|---|---|---|
| ||||
https://www.computop-paygate.com/paymentPage.aspx?MerchantID=yourMerchantId&Data=550a705ffb8fb2d5f5694cad1b6e61237d35e1834c8728baa5b48f831cce342ffb0f6ee9876fea46f0c9da4224b3559fc316aa2a253347167c8922cf40eb9a1d25b9b63ddf39f2c8c60bdadd0a6acda9b86e7c44a404f0bb93d974c6b6365d9c9568d959ff666e47b145d79d030a22f9cf1da025435595926b7e2788fb0004190c3cfdb65d3b5dce626385d41347aeb276a4dc2917b156a0101b0fd0788bb891a39d582962f3a70af105eb1f2240376e358d7cf8a7dadfef2fd3fbb52edb398878f5040995a7b29c8d409787275b6ad1a39d582962f3a70af105eb1f2240376e358d7cf8a7dadfef586eaac76b23528323aa63cb97349376352eca4a77a129bda3b8fc184ffd9dfbe9cff61196ac80f1429815d4444150f543eb60c0a1f3a706ea77f63eccd216a2188cf94505690adfbb95d59473f3ee6b7252654a65f1f6525238d93eea0ae67abc82ed7ecd23bb957791f6e4e2c34fa4&Len=341&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 |
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
für Sie aktiviert werden.Multiexcerpt include MultiExcerptName Helpdesk-Name PageWithExcerpt Wording - 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
Hinweis: Wenn Sie als Händler auf die AES-Verschlüsselung umstellen möchten, beachten Sie bitte, dass alle Requests zu allen Aktionen auch mit AES verschlüsselt werden müssen. Stimmen sie die Umstellung bitte vorab mit allen Parteien ab. Die Batch-Einreichung ist hier ausgenommen, da bei dieser keine API-Verschlüsselung verwendet wird. Hier erfolgt die Sicherung mittels PGP.
Diese URL wird nicht funktionieren und eine "Unexpected exception" als Ergebnis bringen, da die MerchantId "yourMerchantId" nicht existiert. Sie finden funktionierende URLs weiter unten.
title | Putting API-call together |
---|
Der API-Aufruf besteht aus:
Senden des API-Requests
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
Multiexcerpt include SpaceWithExcerpt DE MultiExcerptName
Helpdesk-Name PageWithExcerpt Wording
- via GET the parameters are attached to the URL which can be easily manipulated by a customer - therefore
Multiexcerpt include
MultiExcerptName
Backoffice-Kurz PageWithExcerpt .Wording
prevents manipulation using Blowfish/AES encryptionvDocumentation
Prüfen der
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
-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
Antwort Antwort gültig ist - um sicherzustellen, dass die Antwort nicht manipuliert worden istwurde.Multiexcerpt include SpaceWithExcerpt DE MultiExcerptName Platform-Name PageWithExcerpt Wording
Einige Tipps für
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Info | ||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||
|
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. ( 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.) |