Kreditkartenformular (paySSL)

MerchantID

BasicAuth.Username

ans..30

M

HändlerID, die von Computop vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben.

msgver

–––

ans..5

M

Computop Paygate Message-Version. Zulässige Werte:

ReqId

"requestId": "..."

ans..32

O

Um Doppelzahlungen (z.B. durch ETM) zu vermeiden, übergeben Sie einen alphanumerischen Wert, der Ihre Transaktion oder Aktion identifiziert und nur einmal vergeben werden darf. Falls die Transaktion oder Aktion mit derselben ReqID erneut eingereicht wird, führt das Computop Paygate keine Zahlung oder weitere Aktion aus, sondern gibt nur den Status der ursprünglichen Transaktion oder Aktion zurück.

Bitte beachten Sie, dass das Computop Paygate für die erste initiale Aktion (Authentifizierung/Autorisierung) einen abgeschlossenen Transaktionsstatus haben muss. Dies gilt nicht für 3-D Secure Authentifizierungen, die durch einem Timeout beendet werden. Der Status 3-D Secure Timeout gilt nicht als abgeschlossener Status, bei dem ReqID-Funktionalität am Paygate nicht greift. Einreichungen mit identischer ReqID auf einen offenen Status werden regulär verarbeitet.

Hinweis: Bitte beachten Sie, dass eine ReqID nur 12 Monate gültig ist, danach wird sie vom Paygate gelöscht.

TransID

"transactionId": "..."

ans..64

M

Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss

RefNr

"referenceNumber": "..."

O

Eindeutige Referenznummer des Händlers, welche als Auszahlungsreferenz in der entsprechenden Acquirer EPA-Datei angegeben wird. Bitte beachten Sie, ohne die Übergabe einer eigenen Auszahlungsreferenz können Sie die EPA-Transaktionen nicht zuordnen, zusätzlich kann das Computop Settlement File (CTSF) auch nicht zusätzlich angereichert werden.

Informationen zum unterstützten Format finden Sie weiter unten in der zahlartspezifischen Beschreibung.

Es sind ausschließlich ASCII-Zeichen erlaubt. Sonderzeichen wie ("Umlaute", ...) sind nicht erlaubt und müssen ggf. durch ASCII-Zeichen ersetzt werden (z.B. ü → ue, é → e, ...).

MAC

–––

an64

M

Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier:

• HMAC-Authentisierung (Anfrage)

• HMAC-Authentisierung (Notify)

Amount

"amount": { "value": ...}

n..10

M

Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den Computop Helpdesk, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten.

Currency

"amount": { "currency": "..."}

a3

M

Währung, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP. Hier eine Übersicht: A1 Währungstabelle

Capture

"capture": {"auto": "Yes"}

"capture": {"manual": "Yes"}

"capture": ...

an..6

OM

Bestimmt Art und Zeitpunkt der Buchung (engl. Capture).

PayTypes

"payment": {"cardForm": { "payTypes": "..." }}

ans..256

O

Mit diesem Parameter können Sie die akzeptierten Schemes übersteuern, d.h. Sie können innerhalb dieses Parameters durch Pipe getrennt entscheiden, welche der verfügbaren Kreditkartenschemes angezeigt werden.

Das Template muss diese Funktion unterstützen wie zum Beispiel das "Cards_v1".

Beispiel: PayTypes=VISA|MasterCard

billingDescriptor

"billing": {"addressInfo": { "descriptor": "..." }}

ans..22

O

Eine Bezeichnung, die auf dem Kontoauszug des Karteninhbaers gedruckt wird. Beachten Sie bitte auch die zusätzliche Hinweise an anderer Stelle für weitere Informationen über Regeln und Vorschriften.

OrderDesc

"order": {"description": "..."}

ans..768

O

Beschreibung der gekauften Waren, Einzelpreise etc.

AccVerify

"payment": {"card": { "accountVerification": "..." }}

a3

O

Indikator für Anforderung einer Kontoverifizierung (alias Nullwert-Authorisierung). Bei einer angeforderten Kontoverifizierung ist der übermittelte Betrag optional und wird für die tatsächliche Zahlungstransaktion ignoriert (z.B. Autorisierung).

Zulässiger Wert:

• Yes

threeDSPolicy

"payment": {"card": { "threeDsPolicy": JSON }}

JSON

O

Objekt, das Authentisierungs-Richtlinien und Vorgaben für die Ausnahmenbehandlung festlegt

priorAuthenticationInfo

"payment": {"card": { "priorAuthenticationInfo": JSON }}

JSON

O

Das Objekt Prior Transaction Authentication Information enthält optionale Informationen über eine Authentisierung eines 3DS-Karteninhabers, die vor der aktuellen Transaktion erfolgt ist

accountInfo

"accountInfo": JSON

JSON

O

Das Objekt Kontoinformationen enthält optionale Informationen über das Kundenkonto beim Händler

billToCustomer

"billing": JSON

JSON

C

Der Kunde, dem die Waren und / oder Dienstleistungen in Rechnung gestellt werden. Für EMV 3DS erforderlich, sofern nicht Markt- oder Regionalmandate die Übermittlung dieser Informationen beschränken.

shipToCustomer

"shipping": JSON

JSON

C

Der Kunde, an den die Waren und / oder Dienstleistungen gesendet werden. Erforderlich, falls von billToCustomer abweichend.

billingAddress

"billing": {"addressInfo": JSON}

JSON

C

Rechnungsadresse. For EMV 3DS erforderlich (falls verfügbar), sofern nicht Markt- oder Regionalmandate die Übermittlung dieser Informationen beschränken.

shippingAddress

"shipping": {"addressInfo": JSON}

JSON

C

Lieferadresse. Falls von billingAddress abweichend; für EMV 3DS erforderlich (falls verfügbar), sofern nicht Markt- oder Regionalmandate die Übermittlung dieser Informationen beschränken.

credentialOnFile

"credentialOnFile": JSON

JSON

C

Objekt, das Art und Reihe von Transaktionen mittels Zahlungskonto-Zugangsdaten festlegt (z.B. Kontonummer oder Zahlungs-Token), die bei einem Händler für die Verarbeitung zukünftiger Einkäufe für einen Kunden gespeichert sind. Erforderlich, falls zutreffend.

merchantRiskIndicator

"riskIndicator": JSON

JSON

O

Der Händler-Risikoindikator enthält optionale Informationen über den bestimmten Einkauf des Kunden.

Falls shippingAddress nicht vorhanden ist, ist es dringend empfohlen, das Merkmal shippingAddressIndicator mit einem entsprechenden Wert wie shipToBillingAddress, digitalGoods oder noShipment auszufüllen.

subMerchantPF

"subMerchantPaymentFacilitator": JSON

JSON

O

Objekt, das die Details des SubMerchant (Payment Facilitator) angibt.

Wird ausschließlich von SafeCharge unterstützt.

URLSuccess

"urls": {"success": "..."}

ans..256

M

Vollständige URL, die das Paygate aufruft, wenn die Zahlung erfolgreich war. Die URL darf nur über Port 443 aufgerufen werden. Diese URL darf keine Parameter enthalten: Um Parameter durchzureichen, nutzen Sie stattdessen den Parameter UserData.

Allgemeine Hinweise:

• Wir empfehlen, den Parameter "response=encrypt" zu verwenden, um eine verschlüsselte Antwort vom Paygate zu erhalten

• Betrüger könnten das verschlüsselte DATA-Element kopieren, welches an URLFailure gesendet wurde, und betrügerisch dasselbe DATA an URLSuccess/URLNotify senden. Überprüfen Sie daher unbedingt den "code"-Wert des DATA-Elements. Nur eine Antwort mit "code=00000000" sollte als erfolgreich angesehen werden.

URLFailure

"urls": {"failure": "..."}

ans..256

M

Vollständige URL, die das Paygate aufruft, wenn die Zahlung gescheitert ist. Die URL darf nur über Port 443 aufgerufen werden. Diese URL darf keine Parameter enthalten: Um Parameter durchzureichen, nutzen Sie stattdessen den Parameter UserData.

Allgemeine Hinweise:

• Wir empfehlen, den Parameter "response=encrypt" zu verwenden, um eine verschlüsselte Antwort vom Paygate zu erhalten

• Betrüger könnten das verschlüsselte DATA-Element kopieren, welches an URLFailure gesendet wurde, und betrügerisch dasselbe DATA an URLSuccess/URLNotify senden. Überprüfen Sie daher unbedingt den "code"-Wert des DATA-Elements. Nur eine Antwort mit "code=00000000" sollte als erfolgreich angesehen werden.

URLBack

"urls": {"cancel": "..."}

ans..256

O

Vollständige URL, die das Paygate aufruft, wenn der Kunde auf Abbruch klickt.

Der Parameter "URLBack" kann

• sowohl unverschlüsselt ans Paygate übermittelt werden (Kompabilitätsmodus)

• als auch in den verschlüsselten Übergabeparametern (bevorzugte Variante)

Wenn Sie Parameter/Werte in der URLBack übergeben möchten, so können Sie folgende Methode verwenden:

1
URLBack=https://your.shop.com/back.php?param1%3Dvalue1%26param2%3Dvalue3%26status%3Dcancelled

Wenn der Kunde auf Abbruch klickt, so wird die URL genauso aufgerufen, so dass Sie URL Decode verwenden können, um Parameter und Werte zu extrahieren.

Response

–––

a7

O

Die Status-Rückmeldung, die das Paygate an URLSuccess und URLFailure sendet, sollte verschlüsselt werden. Dazu übergeben Sie den Parameter Response=encrypt.

URLNotify

"urls": {"notify": "..."}

ans..256

M

Vollständige URL, die das Paygate aufruft, um den Shop zu benachrichtigen. Die URL darf nur über Port 443 aufgerufen werden. Diese URL darf keine Parameter enthalten: Um Parameter durchzureichen, nutzen Sie stattdessen den Parameter UserData.

Allgemeine Hinweise:

• Bevor Folgeaktionen (Buchung / Gutschrift / Storno) auf eine bestehende Transaktion ausgeführt werden, muss zuvor das erste Notify durch den Shop beantwortet worden sein.

• Betrüger könnten das verschlüsselte DATA-Element kopieren, welches an URLFailure gesendet wurde, und betrügerisch dasselbe DATA an URLSuccess/URLNotify senden. Überprüfen Sie daher unbedingt den "code"-Wert des DATA-Elements. Nur eine Antwort mit "code=00000000" sollte als erfolgreich angesehen werden.

UserData

"metadata[userData]": "..."

ans..1024

O

Wenn beim Aufruf angegeben, übergibt das Paygate die Parameter mit dem Zahlungsergebnis an den Shop.

Plain

"metadata[plain]": "..."

ans..50

O

Ein einzelner Wert, der von Ihnen gesetzt werden kann, um Informationen wieder unverschlüsselt in der Antwort bzw. im Notify zurückzugeben, z.B. die MID.

Da der "Plain"-Parameter Teil des verschlüsselten "Data" im Computop Paygate ist, ist dieser vor Manipulationen geschützt.

Custom

"metadata": "..."

ans..1024

O

Der "Custom"-Parameter wird vor der Verschlüsselung an den Aufruf angehängt und ist Teil des verschlüsselten "Data" im Computop Paygate -Aufruf. Dadurch ist der Wert gegen Manipulation geschützt.

Der Custom-Wert wird dann in Klartext an die Computop Paygate-Antwort angehängt und dabei wird "|" durch "&" ersetzt. Dadurch können Sie einen Custom-Wert übergeben und bekommen mehrere Key-Value-Paare zu Ihrer eigenen Verwendung in der Antwort zurück.

Hier finden Sie ein Beispiel: Custom

expirationTime

"expirationTime": "..."

ans..19

O

Zeitstempel für den Endzeitpunkt der Transaktionsverarbeitung, Angabe in UTC.

Format: YYYY-MM-ddTHH:mm:ss

REST

Format

CND

Beschreibung

"paymentId": "..."

an32

M

Kann "00000000000000000000000000000000" lauten, wenn dies noch nicht vom Paygate festgelegt wurde

"_Links.self.type": "..."

an..20

M

"application/json"

"_Links.redirect.href": "..."

an..1024

M

Der Händler muss den Kunden zu dieser URL weiterleiten, um die Zahlung abzuschließen

"_Links.redirect.type": "..."

an..20

M

"text/html"

mid

ans..30

M

HändlerID, die von Computop vergeben wird

msgver

ans..5

M

Computop Paygate Message-Version. Zulässige Werte:

PayID

an32

M

Vom Paygate vergebene ID für die Zahlung; z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request.

XID

an32

M

Vom Paygate vergebene ID für alle einzelnen Transaktionen (Autorisierung, Buchung, Gutschrift), die für eine Zahlung durchgeführt werden

TransID

ans..64

M

Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss

schemeReferenceID

ans..64

C

Spezifische Transaktions-ID des Kartenschemas, die für nachfolgende Zahlungen mit gespeicherten Zugangsdaten, verzögerte Autorisierungen und Wiedereinreichungen erforderlich ist.

Pflicht: CredentialOnFile – initial false – unschedule MIT / recurring

schemeReferenceID wird bei 3DS2-Zahlungsvorgängen zurückgegeben. Bei einem Fallback auf 3DS1 prüfen Sie bitte zusätzlich auf TransactionId.

Die SchemeReferenceID ist eine eindeutige Kennung, die von den Kartenmarken generiert wird. In der Regel können Computop-Händler die SchemeReferenceIDs für Abonnements übergreifend verwenden, welche unter Verwendung eines anderen PSP / separater Paygate-MerchantID / separater Acquirer ContractID / Acquirer erstellt wurden.

RefNr

O

Referenznummer vom Request

Status

a..20

M

Status der Transaction.

Zulässige Werte:

• Authorized

• OK (Sale)

• FAILED

Im Fall von nur-Authentisierung ist der Status entweder OK oder FAILED.

Description

ans..1024

M

Nähere Beschreibung bei Ablehnung der Zahlung. Bitte nutzen Sie nicht den Parameter Description, sondern Code für die Auswertung des Transaktionsstatus!

Code

an8

M

Fehlercode gemäß Paygate Antwort-Codes (A4 Fehlercodes)

card

JSON

M

Kartendaten

ipinfo

JSON

O

Objekt mit IP-Informationen

threedsdata

JSON

M

Authentisierungsdaten

resultsresponse

JSON

C

Falls der Authentisierungsprozess eine Challenge des Karteninhabers enthalten hat, werden zusätzliche Informationen über das Ergebnis der Challenge bereitgestellt

externalPaymentData

JSON

O

Optionale Daten des Acquirers/Issuers/externen Dienstleisters für eine Autorisierung

TimeStamp

Date/Time

O

Zeitstempel dieser Aktion, wenn vom Computop Helpdesk aktiviert, z.B. 30.05.2023 08:47:57 oder 30.05.2023 10:03:01.633

CardHolder

ans..50

O

Name des Karteninhabers, wenn vom Computop Helpdesk aktiviert, z.B. Max Mustermann

bin

n..6

O

BIN der Kreditkarte, wenn vom Computop Helpdesk aktiviert, z.B. 40001

maskedpan

an..19

O

Maskierte Kreditkartennummer, wenn vom Computop Helpdesk aktiviert, z.B. 400001XXXXXX8323

cardinfo

JSON

O

JSON-Struktur, welche Informationen zur Kreditkarte bzw. dem Issuer enthält, wenn vom Computop Helpdesk aktiviert, z.B. {"BIN":"400001","Brand":"VISA","Product":"","Source":"CREDIT","Type":"","Country":{"A3":"USA","N3":"840"},"Issuer":""}

CCBrand

an..20

O

Brand / Karten-Scheme der Kreditkarte, z.B. VISA

PCNr

n16

O

Pseudo Card Number: Vom Computop Paygate generierte Zufallszahl, die eine reale Kreditkartennummer repräsentiert. Die Pseudokartennummer (PKN) beginnt mit 0, und die letzten 3 Stellen entsprechen denen der realen Kartennummer. Die PKN kann wie eine Kreditkartennummer für Autorisierung, Buchung und Gutschriften verwendet werden.

PCNr ist ein Antwortwert vom Computop Paygate und kann ebenfalls als CCNr im Request oder als Teil von card-JSON verwendet werden.

CCExpiry

n6

OC

Optional in Verbindung mit PCNr: Ablaufdatum der Kreditkarte im Format YYYYMM (202207)

Plain

ans..50

O

Ein einzelner Wert, der von Ihnen gesetzt werden kann, um Informationen wieder unverschlüsselt in der Antwort bzw. im Notify zurückzugeben, z.B. die MID.

Da der "Plain"-Parameter Teil des verschlüsselten "Data" im Computop Paygate ist, ist dieser vor Manipulationen geschützt.

Custom

ans..1024

O

Der "Custom"-Parameter wird vor der Verschlüsselung an den Aufruf angehängt und ist Teil des verschlüsselten "Data" im Computop Paygate -Aufruf. Dadurch ist der Wert gegen Manipulation geschützt.

Der Custom-Wert wird dann in Klartext an die Computop Paygate-Antwort angehängt und dabei wird "|" durch "&" ersetzt. Dadurch können Sie einen Custom-Wert übergeben und bekommen mehrere Key-Value-Paare zu Ihrer eigenen Verwendung in der Antwort zurück.

Hier finden Sie ein Beispiel: Custom

UserData

ans..1024

O

Wenn beim Aufruf angegeben, übergibt das Paygate die Parameter mit dem Zahlungsergebnis an den Shop.

MAC

an64

M

Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier:

• HMAC-Authentisierung (Anfrage)

• HMAC-Authentisierung (Notify)

TxType

"payment": {"card": { "transactionType": "..." }}

ans..20

M

Übergeben Sie „Order“, um eine Zahlung zu initialisieren und diese später über die Schnittstelle authorize.aspx zu autorisieren. Bitte beachten Sie, dass in Verbindung mit dem genutzten 3-D Secure-Verfahren eine separate Einstellung notwendig ist.

Bitte wenden Sie sich hierzu direkt an Computop Helpdesk.

MerchantID

BasicAuth.Username

ans..30

M

HändlerID, die von Computop vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben.

PayID

"paymentId": "..."

an32

M

Vom Paygate vergebene ID für die Zahlung; z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request.

TransID

"transactionId": "..."

ans..64

M

Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss

Amount

"amount": { "value": ...}

n..10

M

Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den Computop Helpdesk, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten.

Currency

"amount": { "currency": "..."}

a3

M

Währung, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP. Hier eine Übersicht: A1 Währungstabelle

OrderDesc

"order": {"description": "..."}

ans..768

O

Beschreibung der gekauften Waren, Einzelpreise etc.

MAC

–––

an64

M

Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier:

• HMAC-Authentisierung (Anfrage)

• HMAC-Authentisierung (Notify)

Capture

"capture": {"auto": "Yes"}

"capture": {"manual": "Yes"}

"capture": ...

an..6

OM

Bestimmt Art und Zeitpunkt der Buchung (engl. Capture).

mid

"merchantId": "..."

ans..30

M

HändlerID, die von Computop vergeben wird

PayID

"paymentId": "..."

an32

M

Vom Paygate vergebene ID für die Zahlung; z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request.

XID

"xId": "..."

an32

M

Vom Paygate vergebene ID für alle einzelnen Transaktionen (Autorisierung, Buchung, Gutschrift), die für eine Zahlung durchgeführt werden

TransID

"transactionId": "..."

ans..64

M

Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss

Status

"status": "OK"

"status": "FAILED"

a..50

M

OK (URLSuccess) oder FAILED (URLFailure)

Description

"description": "..."

ans..1024

M

Nähere Beschreibung bei Ablehnung der Zahlung. Bitte nutzen Sie nicht den Parameter Description, sondern Code für die Auswertung des Transaktionsstatus!

Code

"code": ...

an8

M

Fehlercode gemäß Paygate Antwort-Codes (A4 Fehlercodes)

RefNr

"referenceNumber": "..."

O

Eindeutige Referenznummer des Händlers, welche als Auszahlungsreferenz in der entsprechenden Acquirer EPA-Datei angegeben wird. Bitte beachten Sie, ohne die Übergabe einer eigenen Auszahlungsreferenz können Sie die EPA-Transaktionen nicht zuordnen, zusätzlich kann das Computop Settlement File (CTSF) auch nicht zusätzlich angereichert werden.

Informationen zum unterstützten Format finden Sie weiter unten in der zahlartspezifischen Beschreibung.

Es sind ausschließlich ASCII-Zeichen erlaubt. Sonderzeichen wie ("Umlaute", ...) sind nicht erlaubt und müssen ggf. durch ASCII-Zeichen ersetzt werden (z.B. ü → ue, é → e, ...).