API Aufruf und Verschlüsselung | Computop Documents

Einen einfachen API Aufruf erzeugen

Ein API-Aufruf an das Computop Paygate erfolgt immer nach demselben Ablauf:

*DRAW.IO* Multiexcerpt: EN:Create an API call and use encryption: Sequence Diagramm

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

Value

Comments

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")
hier finden Sie weitere Details zur HMAC-Berechnung
- für Requests/Anfragen: HMAC-Authentisierung (Anfrage)
- für Response/Benachrichtigungen/Notifies: HMAC-Authentisierung (Notify)
- *Conditional Content: CT* 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=yourMerchantId

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

Parameter vor der Verschlüsselung

1
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:
2
//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.phpctHMACctEncryptctDecrypt

Beispiel

Element

Value

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

*Conditional Content: CT*

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 vomComputop Helpdeskfü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:

Ihre Programmiersprache	Links
ASP	https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.aescryptoserviceprovider.iv?view=net-6.0
Java	https://docs.oracle.com/javase/7/docs/api/javax/crypto/Cipher.html
PHP	https://www.php.net/manual/en/function.openssl-encrypt.php

Beispiel

Element

Value

MerchantID

yourMerchantId

Password

TestTestTestTest

Unencrypted request

Len

354

Data

Notiz

5b447021b775137d2a4249f271200071 ist der Initialization Vector (IV) 16 Bytes, welcher bei der AES Verschlüsselung gebildet und unverschlüsselt ins Data eingefügt wird.

*Conditional Content: CT*

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

e.g. 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.

Building the API Call

1
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:

*Conditional Content: CT*

*Conditional Content: BNP*

*Conditional Content: VR*

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

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.
PayId=0000....0000 code = 8 Ziffern	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
gültige PayID code = 8 Ziffern	Ein Zahlungsvorgang konnte angelegt werden, jedoch wurde von einem nachgelagerten System ein Fehler erkannt. Eine Übersicht der Antwort-Codes finden Sie hier: Response codes
code=xxxx0005	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.
gültige PayID code = 00000000	Zahlungsvorgang-/transaktion ist erfolgreich und abgeschlossen
gültige PayID code = 0	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.

*Conditional Content: CT*

*Conditional Content: BNP*

*Conditional Content: VR*

Click and try	Comments	Notes
Click and try	Link zur Hosted Payment Page ohne spezifische Vorlagendaten, um einen Zahlungsvorgang für 12,34 EUR zu starten	Keine Template-Daten definiert
Click and try	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.)
Click and try	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.)