A 3-D Secure 2.0 payment sequence may comprise the following distinct activities:
Versioning
Request ACS and DS Protocol Version(s) that correspond to card account range as well as an optional 3-D Secure Method URL
3-D Secure Method
Connect the cardholder browser to the issuer ACS to obtain additional browser data
Authentication
Submit authentication request to the issuer ACS
Challenge
Challenge the card holder if mandated
Authorization
Authorize the authenticated transaction with the acquirer
Server-2-Server Sequence Diagram
Please note that the the communication between client and Access Control Server (ACS) is implemented through iframes. Thus, responses arrive in an HTML subdocument and you may establish correspondent event listeners in your root document.
Alternatively you could solely rely on asynchronous notifications delivered to your backend. In those cases you may have to consider methods such as long polling, SSE or websockets to update the client.
Payment Initiation
The initial request to Pay-Jet Cockpit will be the same regardless of the underlying 3-D Secure Protocol.
In order to start a server-to-server 3-D Secure card payment sequence please post the following key-value-pairs to https://www.payjet-cockpit.de/direct.aspx.
Call of interface: general parameters
Notice: For credit card payments with 3-D Secure, please note the different cases as explained separately in the chapter at the start of the handbook. If the credit card is registered for Verified or SecureCode or SafeKey, the next phase is divided into two steps of authentication and payment. However it always begins in the same way via the direct.aspx interface. The first response however is the receipt of Javascript code or other parameters in order to carry out a second call up of the direct3d.aspx interface. Only after that, do you receive the listed parameter as a response.
To carry out a credit card payment via a Server-to-Server connection, call the following URL:
Notice: For security reasons, Pay-Jet Cockpit rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.
Notice: In case of a merchant initiated recurring transaction the JSON objects (besides credentialOnFile and card), the URLNotify and TermURL are not mandatory parameters, because no 3-D Secure and no risk evaluation is done by the card issuing bank and the payment result is directly returned within the response.
With 3-D Secure 2.x a lot of additional data were required (e.g. browser-information, billing/shipping-address, account-info, ...) to improve authentication processing. To handle these information the JSON-objects have been put in place to handle such data. To indicate that these data are used the MsgVer has been implemented.
The page DEWORK:.Wording vDokumentation was not found -- Please check/update the page name used in the MultiExcerpt-Include macro Message-Version. Zulässige Werte:
Wert
Beschreibung
2.0
Mit 3-D Secure 2.x wurde eine Vielzahl zusätzlicher Daten (Browser-Information, Rechnungs-/Versand-Adresse, ...) erforderlich, um den Authentifizierungs-Prozess zu optimieren. Um diese Informationen zu handhaben, wurden die JSON-Objekte eingeführt. Der Parameter MsgVer zeigt an, dass diese Daten verwendet werden.
To avoid double payments / actions, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction / action is submitted again with the same ReqID, Pay-Jet Cockpit will not carry out the payment or new action, but will just return the status of the original transaction / action. Please note that the Pay-Jet Cockpit must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly.
Um Doppelzahlungen zu vermeiden, übergeben Sie einen alphanumerischen Wert, der Ihre Transaktion / Aktion identifiziert und nur einmal vergeben werden darf. Falls die Transaktion oder auch jede Aktion mit derselben ReqID erneut eingereicht wird, führt das Pay-Jet Cockpit keine Zahlung / weitere Aktion aus sondern gibt nur den Status der ursprünglichen Transaktion / Aktion zurück. Bitte beachten Sie, dass das Pay-Jet Cockpit für die erste initiale Aktion einen abgeschlossenen Transaktionsstatus haben muss. Einreichungen mit identischer ReqID auf einen offenen Status werden regulär verarbeitet.
Key
Format
CND
Description
Beschreibung
RefNr
O
Merchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional Pay-Jet settlement file (CTSF) we cannot add the additional payment data.
Details on supported format can be found below in payment specific section.
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 Pay-Jet Settlement File (CTSF) auch nicht zusätzlich angereichert werden.
Informationen zum unterstützten Format finden Sie weiter unten in der zahlartspezifischen Beschreibung.
Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmissions.
Mandatory: CredentialOnFile – initial false – unscheduled MIT / recurring
Kartensystemspezifische Transaktions-ID, die für nachfolgende Zahlungen mit hinterlegten Daten, verzögerte Autorisierungen und Wiedereinreichungen erforderlich ist.
Pflicht: CredentialOnFile – initial false – unschedule MIT / recurring
This parameter is required whenever an industry specific transaction is processed according to the card brands MIT (Merchant Initiated Transactions) Framework. Values accepted:
Value
Description
Resubmission
A merchant performs a re-submission in cases where it requested an authorization, but received a decline due to insufficient funds; however, the goods or services were already delivered to the cardholder.
Merchants in such scenarios can resubmit the request to recover outstanding debt from cardholders.
Reauthorization
A merchant initiates a re-authorization when the completion or fulfillment of the original order or service extends beyond the authorization validity limit set by Visa.
There are two common re-authorization scenarios:
• Split or delayed shipments at eCommerce retailers. A split shipment occurs when not all the goods ordered are available for shipment at the time of purchase. If the fulfillment of the goods takes place after the authorization
validity limit set by Visa, eCommerce merchants perform a separate authorization to ensure that consumer funds are available.
• Extended stay hotels, car rentals, and cruise lines. A re-authorization is used for stays, voyages, and/or rentals that extend beyond the authorization validity period set by Visa.
DelayedCharges
Delayed charges are performed to process a supplemental account charge after original services have been rendered and respective payment has been processed.
NoShow
Cardholders can use their Visa cards to make a guaranteed reservation with certain merchant segments. A guaranteed reservation ensures that the reservation will be honored and allows a merchant to perform a No Show transaction to charge the cardholder a penalty according to the merchant’s cancellation policy. Note: For merchants that accept token-based payment credentials to guarantee a reservation, it is necessary to perform a CIT (Account Verification Service) at the time of reservation to be able perform a No Show transaction later.
Note: It is always submitted in conjunction with the "schemeReferenceID" parameter. Please contact Pay-Jet Support for the supported Acquirer and card brands.
Only supported with Omnipay and GICC.
Dieser Parameter ist erforderlich, wenn eine branchenspezifische Transaktion entsprechend dem Kartenmarken MIT-Framework (MerchantInitiatedTransactions) verarbeitet wird. Zulässige Werte:
Wert
Beschreibung
Resubmission
Ein Händler führt eine erneute Einreichung durch, wenn er eine Autorisierung angefordert hat, diese aber aufgrund unzureichender Mittel abgelehnt wurde; die Waren oder Dienstleistungen wurden jedoch bereits an den Karteninhaber geliefert.
In solchen Szenarien können Händler den Antrag auf Beitreibung ausstehender Forderungen von Karteninhabern erneut einreichen.
Reauthorization
Ein Händler leitet eine erneute Autorisierung ein, wenn Abschluss oder Erfüllung der ursprünglichen Bestellung oder Dienstleistung die von Visa festgelegte Gültigkeitsdauer der Autorisierung überschreitet.
Es gibt zwei gängige Szenarien für die erneute Autorisierung:
•Geteilte oder verzögerte Lieferungbe E-Commerce-Händlern. Eine Teillieferung liegt vor, wenn zum Zeitpunkt des Kaufs nicht alle bestellten Waren versandbereit sind. Erfolgt die Lieferung der Ware nach der von Visa festgelegten Gültigkeitsdauer der Autorisierung, führen E-Commerce-Händler eine separate Autorisierung durch, um sicherzustellen, dass Kundengelder verfügbar sind.
•VerlängerteHotelaufenthaltens, Autovermietungen und Keuzfahrten. Eine erneute Autorisierung wird für Aufenthalte, Reisen und/oder Anmietungen verwendet, die über die von Visa festgelegte Gültigkeitsdauer der Autorisierung hinausgehen.
DelayedCharges
Verzögerte Gebühren dienen dazu, um eine zusätzliche Kontogebühr zu verarbeiten, nachdem die ursprünglichen Dienstleistungen erbracht und die entsprechende Zahlung verarbeitet wurde.
NoShow
Karteninhaber können mit ihren Visa-Karten eine garantierte Reservierung bei bestimmten Händlersegmenten vornehmen. Eine garantierte Reservierung stellt sicher, dass die Reservierung berücksichtigt wird und ermöglicht es einem Händler, eine No-Show-Transaktion durchzuführen, um dem Karteninhaber eine Strafe gemäß den Stornierungsbedingungen des Händlers zu berechnen. Hinweis: Für Händler, die tokenbasierte Zahlungsinformationen akzeptieren, um eine Reservierung zu garantieren, ist es zum Zeitpunkt der Reservierung erforderlich, einen CIT (Kontoverifizierungsservice) durchzuführen, um später eine No-Show-Transaktion durchführen zu können.
Hinweis: Das wird immer zusammen mit dem Parameter "schemeReferenceID" übermittelt. Bezüglich unterstützer Acquirer und Kartenmarken wenden Sie sich bitte an denPay-Jet Support.
Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Pay-Jet Support, if you want to capture amounts <100 (smallest currency unit).
Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den Pay-Jet Support, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten.
A descriptor to be printed on a card holder’s statement. Please also refer to the additional comments made elsewhere for more information about rules and regulations.
Ein auf dem Kontoauszug des Karteninhabers zu druckender Beschreiber. Beachten Sie bitte auch die andernorts gemachten zusätzlichen Hinweise für weitere Informationen über Regeln und Vorschriften.
Indicator to request an account verification (aka zero value authorization). If an account verification is requested the submitted amount will be optional and ignored for the actual payment transaction (e.g. authorization).
Values accepted:
Yes
Indikator zur Anforderung einer Konto-Verifizierung (alias Nullwert-Autorisierung). Wenn eine Konto-Verifizierung angefordert wird, ist der übermittelte Betrag optional und wird für die tatsächliche Zahlungstransaktion (d.h. Autorisierung) ignoriert.
Prior Transaction Authentication Information contains optional information about a 3-D Secure cardholder authentication that occurred prior to the current transaction
Das Objekt Prior Transaction Authentication Information enthält optionale Informationen über eine 3-D Secure-Authentisierung eines Karteninhabers, die vor der aktuellen Transaktion erfolgt ist
The customer that is getting billed for the goods and / or services. Required unless market or regional mandate restricts sending this information.
Der Kunde, dem die Waren und / oder Dienstleistungen in Rechnung gestellt werden. Erforderlich, sofern nicht Markt- oder regionale Mandate das Senden dieser Informationen beschränken.
The customer that the goods and / or services are sent to. Required (if available and different from billToCustomer) unless market or regional mandate restricts sending this information.
Der Kunde, an den die Waren und / oder Dienstleistungen gesendet werden. Erforderlich (falls verfügbar und von billToCustomer abweichend), sofern nicht Markt- oder regionale Mandate das Senden dieser Informationen beschränken.
Billing address. Required for 3-D Secure 2.0 (if available) unless market or regional mandate restricts sending this information.
Rechnungsadresse. Erforderlich für 3-D Secure 2.0 (falls verfügbar), sofern nicht Markt- oder regionale Mandate das Senden dieser Informationen beschränken.
Shipping address. If different from billingAddress, required for 3-D Secure 2.0 (if available) unless market or regional mandate restricts sending this information.
Lieferadresse. Falls abweichend von billingAddress, erforderlich für 3-D Secure 2.0 (falls verfügbar), sofern nicht Markt- oder regionale Mandate das Senden dieser Informationen beschränken.
Object specifying type and series of transactions using payment account credentials (e.g. account number or payment token) that is stored by a merchant to process future purchases for a customer. Required if applicable.
Objekt, dass Art und Reihe der Transaktionen angibt, die unter Verwendung von beim Händler hinterlegten Zahlungsdaten (z.B. Kontonummer oder Zahlungs-Token) zur Verarbeitung künftiger Käufe eines Kunden erfolgen. Erforderlich, falls zutreffend.
Only for 3-D Secure: URL of the shop which has been selected by the Access Control Server (ACS) of the bank to transmit the result of the authentication. The bank transmits the parameters PayID, TransID and MerchantID via GET and the PAResponse parameter via POST to the TermURL.
Nur bei 3-D Secure: URL des Shops, die vom Access Control Server (ACS) der Bank aufgerufen wird, um das Ergebnis der Authentisierung zu übermitteln. Dabei übergibt die Bank per GET die ParameterPayID,TransID,MerchantIDund per POST den ParameterPAResponsean die TermURL.
Complete URL which Cockpitcalls up in order to notify the shop about the payment result. The URL may be called up only via port 443. It may not contain parameters: Use the UserData parameter instead.
Common notes:
We recommend to use parameter "response=encrypted" to get an encrypted response by Cockpit
However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.
Vollständige URL, die das Cockpit aufruft, um den Shop zu benachrichtigen. Die URL darf nur über Port 443 aufgerufen werden. Sie darf keine Parameter enthalten: Nutzen Sie stattdessen den Parameter UserData.
Allgemeine Hinweise:
Wir empfehlen, den Parameter "response=encrypted" zu verwenden, um eine verschlüsselte Antwort von Cockpit 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.
The Card Range Data data element contains information that indicates the most recent EMV 3-D Secure version supported by the ACS that hosts that card range. It also may optionally contain the ACS URL for the 3-D Secure Method if supported by the ACS and the DS Start and End Protocol Versions which support the card range.
Das Datenelement Card Range Data enthält Informationen, welche die jüngste vom ACS, der den Kartenbereich hostet, unterstützte EMV 3-D Secure-Version angeben. Es kann optional auch die ACS URL für die 3-D Secure Methode enthalten, falls vom ACS unterstützt, sowie die DS Start- und End-Protokoll-Versionen, die den Kartenbereich unterstützen.
Object containing the data elements required to construct the Payer Authentication request in case of a fallback to 3-D Secure 1.0.
Objekt, dass die erforderlichen Datenelemente für die Konstruktion der Anfrage zur Zahler-Authentisierung im Falle eines Fallbacks auf 3-D Secure 1.0 enthält.
versioningData
The versioningData object will indicate the EMV 3-D Secure protocol versions (i.e. 2.1.0 or higher) that are supported by Access Control Server of the issuer.
If the corresponding protocol version fields are NULL it means that the BIN range of card issuer is not registered for 3-D Secure 2.0 and a fallback to 3-D Secure 1.0 is required for transactions that are within the scope of PSD2 SCA.
When parsing versioningData please also refer to the subelement errorDetails which will specify the reason if some fields are not pupoluated (e.g. Invalid cardholder account number passed, not available card range data, failure in encoding/serialization of the 3-D Secure Method data etc).
The 3-D Secure Method allows for additional browser information to be gathered by an ACS prior to receipt of the authentication request message (AReq) to help facilitate the transaction risk assessment. Support of 3-D Secure Method is optional and at the discretion of the issuer.
The versioningData object contains a value for threeDSMethodURL. The merchant is supposed to invoke the 3-D Secure Method via a hidden HTML iframe in the cardholder browser and send a form with a field named threeDSMethodData via HTTP POST to the ACS 3-D Secure Method URL.
3-D Secure Method: threeDSMethodURL
Please note that the threeDSMethodURL will be populated by Pay-Jet Cockpit if the issuer does not support the 3-D Secure Method. The 3-D Secure Method Form Post as outlined below must be performed independently from whether it is supported by the issuer. This is necessary to facilitate direct communication between the browser and Pay-Jet Cockpit in case of a mandated challenge or a frictionless flow.
The ACS will interact with the Cardholder browser via the HTML iframe and then store the applicable values with the 3-D Secure Server Transaction ID for use when the subsequent authentication message is received containing the same 3-D Secure Server Transaction ID.
Once the 3-D Secure Method is concluded the ACS will instruct the cardholder browser through the iFrame response document to submit threeDSMethodData as a hidden form field to the 3-D Secure Method Notification URL.
ACS Response Document
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8"/>
<title>Identifying...</title>
</head>
<body>
<script>
var tdsMethodNotificationValue = 'eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImUxYzFlYmViLTc0ZTgtNDNiMi1iMzg1LTJlNjdkMWFhY2ZhMiJ9';
var form = document.createElement("form");
form.setAttribute("method", "post");
form.setAttribute("action", "notification URL");
addParameter(form, "threeDSMethodData", tdsMethodNotificationValue);
document.body.appendChild(form);
form.submit();
function addParameter(form, key, value) {
var hiddenField = document.createElement("input");
hiddenField.setAttribute("type", "hidden");
hiddenField.setAttribute("name", key);
hiddenField.setAttribute("value", value);
form.appendChild(hiddenField);
}
</script>
</body>
</html>
Please note that the threeDSMethodNotificationURL as embedded in the Base64 encoded threeDSMethodData value points to Pay-Jet Cockpit and must not be modified. The merchant notification is delivered to the URLNotify as provided in the original request or as configured for the MerchantID in Pay-Jet Cockpit.
Authentication
If 3-D Secure Method is supported by the issuer ACS and was invoked by the merchant Pay-Jet Cockpit will automatically continue with the authentication request once the 3-D Secure Method has completed (i.e. 3-D Secure Method Notification).
The authentication result will be transferred via HTTP POST to the URLNotify. It may indicate that the Cardholder has been authenticated, or that further cardholder interaction (i.e. challenge) is required to complete the authentication.
In case a cardholder challenge is deemed necessaryPay-Jet Cockpit will transfer a JSON object within the body of HTTP browser response with the elements acsChallengeMandated, challengeRequest, base64EncodedChallengeRequest and acsURL. Otherwise, in a frictionless flow, Pay-Jet Cockpit will automatically continue and respond to the cardholder browser once the authorization completed.
Response object in return of the authentication request with the ACS
Antwort-Objekt als Rückgabe zur Authentisierungs-Anfrage beim ACS
Browser Challenge
If a challenge is deemed necessary (see challengeRequest) the browser challenge will occur within the cardholder browser. To create a challenge it is required to post the value base64EncodedChallengeRequest via an HTML iframe to the ACS URL.
You may use the operations init3DSChallengeRequest or createIFrameAndInit3DSChallengeRequest from the nca3DSWebSDK in order submit the challenge message through the cardholder browser.
Once the cardholder challenge is completed, was cancelled or timed out the ACS will instruct the browser to post the results to the notfication URL as specified in the challenge request and to send a Result Request (RReq) via the Directory Server to the 3-D Secure Server.
Please note that the notification URL submited in the challenge request points to Pay-Jet Cockpit and must not be changed.
Authorization
After successful cardholder authentication or proof of attempted authentication/verification is provided Pay-Jet Cockpit will automatically continue with the payment authorization.
In case the cardholder authentication was not successful or proof proof of attempted authentication/verification can not be provided Pay-Jet Cockpit will not continue with an authorization request.
In both cases Cockpit will deliver a final notification to the merchant specified URLNotify with the data elements as listed in the table below.
With 3-D Secure 2.x a lot of additional data were required (e.g. browser-information, billing/shipping-address, account-info, ...) to improve authentication processing. To handle these information the JSON-objects have been put in place to handle such data. To indicate that these data are used the MsgVer has been implemented.
The page DEWORK:.Wording vDokumentation was not found -- Please check/update the page name used in the MultiExcerpt-Include macro Message-Version. Zulässige Werte:
Wert
Beschreibung
2.0
Mit 3-D Secure 2.x wurde eine Vielzahl zusätzlicher Daten (Browser-Information, Rechnungs-/Versand-Adresse, ...) erforderlich, um den Authentifizierungs-Prozess zu optimieren. Um diese Informationen zu handhaben, wurden die JSON-Objekte eingeführt. Der Parameter MsgVer zeigt an, dass diese Daten verwendet werden.
Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmissions.
Kartensystemspezifische Transaktions-ID, die für nachfolgende Zahlungen mit hinterlegten Daten, verzögerte Autorisierungen und Wiedereinreichungen erforderlich ist
TrxTime
an21
M
Transaction time stamp in format DD.MM.YYYY HH:mm:ssff
Zeitstempel der Transaktion im Format DD.MM.YYYY HH:mm:ssff
Status
a..20
M
Status of the transaction.
Values accepted:
Authorized
OK (Sale)
PENDING
FAILED
In case of Authentication-only the Status will be either OK or FAILED.
Status der Transaktion.
Zulässige Werte:
Authorized
OK (Sale)
PENDING
FAILED
Im Falle von nur Authentisierung ist der Status entweder OK oder FAILED.
In case the authentication process included a cardholder challenge additional information about the challenge result will be provided.
Falls der Authentisierungsprozess eine Challenge des Karteninhabers enthalten hat, werden zusätzliche Informationen über das Ergebnis der Challenge bereitgestellt
Pseudo Card Number: Random number generated by Pay-Jet Cockpit which represents a genuine credit card number. The pseudo card number (PCN) starts with 0 and the last 3 digits correspond to those of the real card number. You can use the PCN like a genuine card number for authorisation, capture and credits.
PCNr is a response value from Pay-Jet Cockpit and is sent as CCNr in Request or part of card-JSON
Pseudo Card Number: Vom Pay-Jet Cockpit 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 können Sie wie eine reale Kartennummer für Autorisierung, Buchung und Gutschriften verwenden.
PCNr ist ein Antwortwert von Pay-Jet Cockpit und kann ebenfalls als CCNr im Request oder als Teil von card-JSON verwendet werden.
Browser Payment Response
Additionally the JSON formatted data elements as listed below are transferred in the HTTP response body to the cardholder browser. Please note that the data elements (i.e. MID, Len, Data) are base64 encoded.
Merchants are supposed to forward these data elements to their server for decryption and mapping agianst the payment notification. Based on the payment results the merchant server may deliver an appropriate response to the cardholder browser (e.g. success page).
Please note the additional parameter for a specific credit card integration in the section "Specific parameters"
