Request Elements
In order to start a
Chart of process flow via Server-to-Server
For theserver-to-server card payment
sequence please
Overview
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 carholder if mandated
Authorization
Authorize the authenticated transaction with the acquirer
Server-2-Server Sequence Diagram
Multiexcerpt | ||||
---|---|---|---|---|
| ||||
Info |
---|
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. |
post the following key-value-pairs to
https://paymentpage.axepta.bnpparibas/direct.aspx |
Notice: For security reasons, Axepta Platform 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 3D Secure and no risk evaluation is done by the card issuing bank and the payment result is directly returned within the response.
Parameter | Format | CND | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
ans..30 | M | MerchantID, assigned by Axepta. Additionally this parameter has to be passed in plain language too. | |||||||||
MsgVer | ans..5 | M | Message version. Values accepted:
| ||||||||
TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment | ||||||||
RefNr | ans..30 | 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 BNP settlement file (CTSF) we cannot add the additional payment data. Notes:
| ||||||||
schemeReferenceID | ans..64 | C | Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmssions. Mandatory: CredentialOnFile – initial false – unschedule MIT / recurring | ||||||||
Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit). | ||||||||
Currency | a3 | M | Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table EN | ||||||||
card | JSON | M | Card data | ||||||||
Capture | an..6 | OM | Determines the type and time of capture.
| ||||||||
channel | a..20 | C | Indicates the type of channel interface being used to initiate the transaction. Values accepted:
If not present the value | ||||||||
billingDescriptor | ans..22 | O | A descriptor to be printed on a cardholder’s statement. Please also refer to the additional comments made elswhere for more information about rules and regulations. | ||||||||
OrderDesc | ans..768 | O | Order description | ||||||||
TermURL | ans..256 | O | In case of 3-D Secure 1.0 fallback: the URL the customer will be returned to at the end of the 3-D Secure 1.0 authentication process. | ||||||||
AccVerify | a3 | O | 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:
| ||||||||
JSON | O | Object specifying authentication policies and excemption handling strategies | |||||||||
JSON | C | Object detailing authentication data in case authentication was performed through a third party or by the merchant | |||||||||
JSON | O | Prior Transaction Authentication Information contains optional information about a 3-D Secure cardholder authentication that occurred prior to the current transaction | |||||||||
JSON | O | The account information contains optional information about the customer account with the merchant. Optional for 3-D Secure 2.0 transactions. | |||||||||
JSON | C | The customer that is getting billed for the goods and / or services. Required unless market or regional mandate restricts sending this information. | |||||||||
JSON | C | 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. | |||||||||
JSON | C | Billing address. Required for 3-D Secure 2.0 (if available) unless market or regional mandate restricts sending this information. | |||||||||
JSON | C | Shipping address. If different from billingAddress, required for 3-D Secure 2.0 (if available) unless market or regional mandate restricts sending this information. | |||||||||
JSON | C | 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. | |||||||||
JSON | O | The Merchant Risk Indicator contains optional information about the specific purchase by the customer | |||||||||
subMerchantPF | JSON | O | Object specifying SubMerchant (Payment Facilitator) details | ||||||||
an..256 | M | The merchant URL that receive asynchrounous reqeusts during the authentication process | |||||||||
UserData | ans..1024 | O | If specified at request, Paygate forwards the parameter with the payment result to the shop. | ||||||||
an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: |
General parameters for credit card payments via socket connection
Please note the additional parameter for a specific credit card integration in the section "Specific parameters"
Response Elements
The following table describes the result parameters with which the Axepta Platform responds to your system
pls. be prepared to receive additional parameters at any time and do not check the order of parameters
the key (e.g. MerchantId, RefNr) should not be checked case-sentive
Parameter | Format | CND | Description |
---|---|---|---|
ans..30 | M | MerchantID, assigned by Computop | |
PayID | an32 | M | ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate |
TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
a..20 | M | Status of the transaction. Values accepted:
| |
an12 | M | 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 settlement file we cannot add the additional payment data. Notes:
| |
Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
Code | an8 | M | Error code according to Paygate Response Codes (A4 Error codes) |
UserData | ans..1024 | O | If specified at request, Paygate forwards the parameter with the payment result to the shop. |
JSON | M | 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. | |
JSON | M | Object containing the data elements required to construct the Payer Authentication request in case of a fallback to 3-D Secure 1.0. | |
ans..64 | C | Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmssions. | |
JSON | M | Card data | |
JSON | O | Object containing IP information | |
JSON | M | Authentication data | |
JSON | C | In case the authentication process included a cardholder challenge additional information about the challenge result will be provided. |
Table of Contents |
---|
Payment initiation
The initial request to
will be the same regardless of the underlying 3-D Secure Protocol. Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt EN:Wording
Multiexcerpt | ||||
---|---|---|---|---|
| ||||
Request Elements
In order to start a server-to-server 3-D Secure card payment sequence please post the following key-value-pairs to
https://paymentpage.axepta.bnpparibas/direct.aspx
Notice: For security reasons, Axepta Platform 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 3D Secure and no risk evaluation is done by the card issuing bank and the payment result is directly returned within the response.
default | Beschreibung |
---|---|
isFirstTimeEnter | false |
hideColumns | true |
sparkName | Sparkline |
hidePane | true |
datepattern | dd M yy |
id | 1625492202584_1683736465 |
worklog | 365|5|8|y w d h m|y w d h m |
isOR | AND |
separator | Point (.) |
order | 0 |
MultiExcerptName | request_elements |
---|
dateFormat | dd M yy |
---|---|
export-word | false |
show-source | false |
export-csv | false |
id | 1625492202586_-1877872023 |
transpose | false |
worklog | 365|5|8|y w d h m|y w d h m |
separator | . |
export-pdf | false |
sql | SELECT * FROM T* |
Table Excerpt Include | ||||||||
---|---|---|---|---|---|---|---|---|
|
Message version.
Values accepted:
-
2.0
Message-Version.
Zulässige Werte:
2.0
Table Excerpt Include | ||||||||
---|---|---|---|---|---|---|---|---|
|
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
settlement file (CTSF) we cannot add the additional payment data. Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Partner-Name PageWithExcerpt Wording
Notes:
- Fixed length of 12 characters (only characters (A..Z, a..z) and digits (0..9) are allowed, no special characters like whitespace, underscore...)
- If the number of characters entered is lower than 12, BNP will complete, starting from the left side, with "0" (Example : 000018279568)
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
Settlement File (CTSF) auch nicht zusätzlich angereichert werden. Multiexcerpt include SpaceWithExcerpt DE MultiExcerptName Partner-Name PageWithExcerpt DE:Wording
Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmssions.
Mandatory: CredentialOnFile – initial false – unschedule 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:
Values | Comments |
---|---|
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
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Dieser Parameter ist erforderlich, wenn eine branchenspezifische Transaktion entsprechend dem Kartenmarken MIT-Framework (Merchant Initiated Transactions) verarbeitet wird.
Zulässige Werte:
Werte | Anmerkungen |
---|---|
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 Lieferung be 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ängerte Hotelaufenthaltens, 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 den
Multiexcerpt include | ||||||
---|---|---|---|---|---|---|
|
Table Excerpt Include | ||||||||
---|---|---|---|---|---|---|---|---|
|
Table Excerpt Include | ||||||||
---|---|---|---|---|---|---|---|---|
|
Table Excerpt Include | ||||||||
---|---|---|---|---|---|---|---|---|
|
Indicates the type of channel interface being used to initiate the transaction.
Values accepted:
Browser
App
3RI
If not present the value Browser
is implied.
Gibt die Art der verwendeten Schnittstelle zur Initiierung der Transaktion an.
Zulässige Werte:
Browser
App
3RI
Wenn nicht angegeben, wird der Wert Browser
verwendet.
ans..256
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.
Zulässige Werte:
Yes
JSON
O
Object specifying authentication policies and excemption handling strategies
JSON
C
Object detailing authentication data in case authentication was performed through a third party or by the merchant
JSON
O
Prior Transaction Authentication Information contains optional information about a 3-D Secure cardholder authentication that occurred prior to the current transaction
JSON
M
Accurate browser information are needed to deliver an optimized user experience. Required for 3-D Secure 2.0 transactions.
JSON
O
The account information contains optional information about the customer account with the merchant. Optional for 3-D Secure 2.0 transactions.
JSON
C
The customer that is getting billed for the goods and / or services. Required unless market or regional mandate restricts sending this information.
JSON
C
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.
JSON
C
Billing address. Required for 3-D Secure 2.0 (if available) unless market or regional mandate restricts sending this information.
JSON
C
Shipping address. If different from billingAddress, required for 3-D Secure 2.0 (if available) unless market or regional mandate restricts sending this information.
JSON
C
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.
JSON
O
The Merchant Risk Indicator contains optional information about the specific purchase by the customer
URLNotify
an..256
M
The merchant URL that receive asynchrounous reqeusts during the authentication process
Table Excerpt Include static true name UserData page EN:UserData type page
Table Excerpt Include static true name MAC page EN:MAC type page
General parameters for credit card payments via socket connection
Please note the additional parameter for a specific credit card integration in the section "Specific parameters"
Response Elements
The following table describes the result parameters with which the Axepta Platform responds to your system
pls. be prepared to receive additional parameters at any time and do not check the order of parameters
the key (e.g. MerchantId, RefNr) should not be checked case-sentive
default | Beschreibung |
---|---|
isFirstTimeEnter | false |
hideColumns | true |
sparkName | Sparkline |
hidePane | true |
datepattern | dd M yy |
id | 1625492202587_-170864224 |
worklog | 365|5|8|y w d h m|y w d h m |
isOR | AND |
separator | Point (.) |
order | 0 |
MultiExcerptName | response_elements |
---|
dateFormat | dd M yy |
---|---|
export-word | false |
show-source | false |
export-csv | false |
id | 1625492202588_221028620 |
transpose | false |
worklog | 365|5|8|y w d h m|y w d h m |
separator | . |
export-pdf | false |
sql | SELECT * FROM T* |
Table Excerpt Include static true name MID page EN:MID type page
Table Excerpt Include static true name PayID page EN:PayID type page
Table Excerpt Include static true name XID page EN:XID type page
Table Excerpt Include static true name TransID page EN:TransID type page
Status
a..20
M
Status of the transaction.
Values accepted:
AUTHENTICATION_REQUEST
-
PENDING
FAILED
Status der Transaktion.
Zulässige Werte:
AUTHENTICATION_REQUEST
PENDING
FAILED
RefNr
an12
M
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 settlement file we cannot add the additional payment data.
Notes:
- Fixed length of 12 characters (only characters (A..Z, a..z) and digits (0..9) are allowed, no special characters like whitespace, underscore...)
- For AMEX : RefNr is mandatory
- If the number of characters entered is lower than 12, BNP will complete, starting from the left side, with "0" (Example : 000018279568)
Table Excerpt Include static true name Description page EN:Description type page
Table Excerpt Include static true name Code page EN:Code type page
Table Excerpt Include static true name UserData page EN:UserData type page
JSON
M
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.
JSON
M
Object containing the data elements required to construct the Payer Authentication request in case of a fallback to 3-D Secure 1.0.
schemeReferenceID
ans..64
C
Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmssions.
JSON
M
Card data
JSON
O
Object containing IP information
JSON
M
Authentication data
JSON
C
In case the authentication process included a cardholder challenge additional information about the challenge result will be provided.
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).
versioningData
BASEURL=
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName BaseURL PageWithExcerpt EN:Wording
MultiExcerptName | versioningdata |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
{
"threeDSServerTransID": "14dd844c-b0fc-4dfe-8635-366fbf43468c",
"acsStartProtocolVersion": "2.1.0",
"acsEndProtocolVersion": "2.1.0",
"dsStartProtocolVersion": "2.1.0",
"dsEndProtocolVersion": "2.1.0",
"threeDSMethodURL": "http://www.acs.com/script",
"threeDSMethodDataForm": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly93d3cuY29tcHV0b3AtcGF5Z2F0ZS5jb20vY2JUaHJlZURTLmFzcHg_YWN0aW9uPW10aGROdGZuIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxNGRkODQ0Yy1iMGZjLTRkZmUtODYzNS0zNjZmYmY0MzQ2OGMifQ==",
"threeDSMethodData": {
"threeDSMethodNotificationURL": "BASEURLcbThreeDS.aspx?action=mthdNtfn",
"threeDSServerTransID": "14dd844c-b0fc-4dfe-8635-366fbf43468c"
}
} |
3-D Secure Method
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
Multiexcerpt | ||||
---|---|---|---|---|
| ||||
Please not that the threeDSMethodURL
will be populated by
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 Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt EN:Wording
in case of a mandated challenge or a frictionless flow. Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt EN:Wording
threeDSMethodURL
Multiexcerpt | ||||
---|---|---|---|---|
| ||||
3-D Secure Method Form Post
MultiExcerptName | 3ds_method |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
<form name="frm" method="POST" action="Rendering URL">
<input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIn0">
</form> |
The ACS will intercat 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.
title | Netcetera 3DS Web SDK |
---|
init3DSMethod
or createIframeAndInit3DSMethod
at your discreation from the nca3DSWebSDK in order to iniatiate the 3-D Secure Method. Please refer to the Integration Manual at https://mpi.netcetera.com/3dsserver/doc/current/integration.html#Web_Service_API.Once the 3-D Secure Method is concluded the ACS will instruct the 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
MultiExcerptName | acs_response |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
<!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> |
3-D Secure Method Notification Form
MultiExcerptName | 3ds_method_notification_form |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
<form name="frm" method="POST" action="3DS Method Notification URL">
<input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImUxYzFlYmViLTc0ZTgtNDNiMi1iMzg1LTJlNjdkMWFhY2ZhMiJ9">
</form> |
Note | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Please note that the |
Authentication
If 3-D Secure Method is supported by the issuer ACS and was invoked by the merchant
will automatically continue with the authentication request once the 3-D Secure Method has completed (i.e. 3-D Secure Method Notification). Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt EN:Wording
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 necessary
will transfer a JSON object within the body of HTTP browser response with the elements Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt EN:Wording acsChallengeMandated
, challengeRequest
, base64EncodedChallengeRequest
and acsURL
. Otherwise, in a frictionless flow,
will automatically continue and respond to the cardholder browser once the authorization completed. Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt EN:Wording
Cardholder Challenge: Browser Response
Multiexcerpt | ||||
---|---|---|---|---|
| ||||
Browser Challenge Response
Data Elements
default | Beschreibung |
---|---|
isFirstTimeEnter | false |
hideColumns | true |
sparkName | Sparkline |
hidePane | true |
datepattern | dd M yy |
id | 1625492202590_-863270165 |
worklog | 365|5|8|y w d h m|y w d h m |
isOR | AND |
separator | Point (.) |
order | 0 |
MultiExcerptName | challenge_response |
---|
dateFormat | dd M yy |
---|---|
export-word | false |
show-source | false |
export-csv | false |
id | 1625492202591_1231229094 |
transpose | false |
worklog | 365|5|8|y w d h m|y w d h m |
separator | . |
export-pdf | false |
sql | SELECT * FROM T* |
acsChallengeMandated
boolean
M
Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable
object
M
Challenge request object
base64EncodedChallengeRequest
string
M
Base64-encoded Challenge Request object
acsURL
string
M
Fully qualified URL of the ACS to be used to post the Challenge Request
Schema: Browser Challenge Response
MultiExcerptName | schema |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"acsChallengeMandated": {"type": "boolean"},
"challengeRequest": {"type": "object"},
"base64EncodedChallengeRequest": {"type": "string"},
"acsURL": {"type": "string"}
},
"required": ["acsChallengeMandated", "challengeRequest", "base64EncodedChallengeRequest", "acsURL"],
"additionalProperties": false
} |
Sample: Browser Challenge Response
MultiExcerptName | sample |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
{
"acsChallengeMandated": true,
"challengeRequest": {
"threeDSServerTransID": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e",
"acsTransID": "d7c1ee99-9478-44a6-b1f2-391e29c6b340",
"messageType": "CReq",
"messageVersion": "2.1.0",
"challengeWindowSize": "01",
"messageExtension": [
{
"name": "emvcomsgextInChallenge",
"id": "tc8Qtm465Ln1FX0nZprA",
"criticalityIndicator": false,
"data": "messageExtensionDataInChallenge"
}
]
},
"base64EncodedChallengeRequest": "base64-encoded-challenge-request",
"acsURL": "acsURL-to-post-challenge-request"
} |
Authentication Notification
The data elements of the authentication notification are listed in the table below.
default | Beschreibung |
---|---|
isFirstTimeEnter | false |
hideColumns | true |
sparkName | Sparkline |
hidePane | true |
datepattern | dd M yy |
id | 1625492202592_69706183 |
worklog | 365|5|8|y w d h m|y w d h m |
isOR | AND |
separator | Point (.) |
order | 0 |
MultiExcerptName | authentification_notification |
---|
dateFormat | dd M yy |
---|---|
export-word | false |
show-source | false |
export-csv | false |
id | 1625492202593_815229849 |
transpose | false |
worklog | 365|5|8|y w d h m|y w d h m |
separator | . |
export-pdf | false |
sql | SELECT * FROM T* |
Table Excerpt Include static true name MID page EN:MID type page
Table Excerpt Include static true name PayID page EN:PayID type page
Table Excerpt Include static true name TransID page EN:TransID type page
Table Excerpt Include static true name Code page EN:Code type page
Table Excerpt Include static true name MAC page EN:MAC type page
JSON
M
Response object in return of the authentication request with the 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.
Challenge Request
MultiExcerptName | challenge_request |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
<form name="challengeRequestForm" method="post" action="acsChallengeURL">
<input type="hidden" name="creq" value="ewogICAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjogIjhhODgwZGMwLWQyZDItNDA2Ny1iY2IxLWIwOGQxNjkwYjI2ZSIsCiAgICAiYWNzVHJhbnNJRCI6ICJkN2MxZWU5OS05NDc4LTQ0YTYtYjFmMi0zOTFlMjljNmIzNDAiLAogICAgIm1lc3NhZ2VUeXBlIjogIkNSZXEiLAogICAgIm1lc3NhZ2VWZXJzaW9uIjogIjIuMS4wIiwKICAgICJjaGFsbGVuZ2VXaW5kb3dTaXplIjogIjAxIiwKICAgICJtZXNzYWdlRXh0ZW5zaW9uIjogWwoJCXsKCQkJIm5hbWUiOiAiZW12Y29tc2dleHRJbkNoYWxsZW5nZSIsCgkJCSJpZCI6ICJ0YzhRdG00NjVMbjFGWDBuWnByQSIsCgkJCSJjcml0aWNhbGl0eUluZGljYXRvciI6IGZhbHNlLAoJCQkiZGF0YSI6ICJtZXNzYWdlRXh0ZW5zaW9uRGF0YUluQ2hhbGxlbmdlIgoJCX0KICAgIF0KfQ==">
</form> |
You may use the operations init3DSChallengeRequest
or createIFrameAndInit3DSChallengeRequest
from the nca3DSWebSDK in order submit the challenge message through the cardholder browser.
Init 3-D Secure Challenge Request - Example
MultiExcerptName | init_challenge_request |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<script src="nca-3ds-web-sdk.js" type="text/javascript"></script>
<title>Init 3-D Secure Challenge Request - Example</title>
</head>
<body>
<!-- This example will show how to initiate Challenge Reqeuests for different window sizes. -->
<div id="frameContainer01"></div>
<div id="frameContainer02"></div>
<div id="frameContainer03"></div>
<div id="frameContainer04"></div>
<div id="frameContainer05"></div>
<iframe id="iframeContainerFull" name="iframeContainerFull" width="100%" height="100%"></iframe>
<script type="text/javascript">
// Load all containers
iFrameContainerFull = document.getElementById('iframeContainerFull');
container01 = document.getElementById('frameContainer01');
container02 = document.getElementById('frameContainer02');
container03 = document.getElementById('frameContainer03');
container04 = document.getElementById('frameContainer04');
container05 = document.getElementById('frameContainer05');
// nca3DSWebSDK.init3DSChallengeRequest(acsUrl, creqData, container);
nca3DSWebSDK.init3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', iFrameContainerFull);
// nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest(acsUrl, creqData, challengeWindowSize, frameName, rootContainer, callbackWhenLoaded);
nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '01', 'threeDSCReq01', container01);
nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '02', 'threeDSCReq02', container02);
nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '03', 'threeDSCReq03', container03);
nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '04', 'threeDSCReq04', container04);
nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '05', 'threeDSCReq05', container05, () => {
console.log('Iframe loaded, form created and submitted');
});
</script>
</body>
</html> |
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.
Note | ||||||||
---|---|---|---|---|---|---|---|---|
Please note that the notification URL submited in the challenge request points to |
Authorization
After succefull cardholder authentication or proof of attempted authentication/verification is provided
will automatically continue with the payment authorization. Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt EN:Wording
In case the cardholder authentication was not succesfull or proof proof of attempted authentication/verification can not be provided
will not continue with an authorization request. Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt EN:Wording
In both cases
will deliver a final notification to the merchant specified Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Kurz PageWithExcerpt EN:Wording URLNotify
with the data elements as listed in the table below.
Payment Notification
default | Beschreibung |
---|---|
isFirstTimeEnter | false |
hideColumns | true |
sparkName | Sparkline |
hidePane | true |
datepattern | dd M yy |
id | 1625492202594_-398328237 |
worklog | 365|5|8|y w d h m|y w d h m |
isOR | AND |
separator | Point (.) |
order | 0 |
MultiExcerptName | payment_notification |
---|
dateFormat | dd M yy |
---|---|
export-word | false |
show-source | false |
export-csv | false |
id | 1625492202596_-1528328090 |
transpose | false |
worklog | 365|5|8|y w d h m|y w d h m |
separator | . |
export-pdf | false |
sql | SELECT * FROM T* |
Table Excerpt Include static true name MID page EN:MID type page
MsgVer
ans..5
M
Message version.
Accepted values:
2.0
Message-Version.
Zulässige Werte:
2.0
Table Excerpt Include static true name PayID page EN:PayID type page
Table Excerpt Include static true name XID page EN:XID type page
Table Excerpt Include static true name TransID page EN:TransID type page
schemeReferenceID
ans..64
C
Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmssions.
TrxTime
an21
M
Transaction time stamp in 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
.
Table Excerpt Include static true name Description page EN:Description type page
Table Excerpt Include static true name Code page EN:Code type page
Table Excerpt Include static true name MAC page EN:MAC type page
JSON
M
Card data
JSON
O
Object containing IP information
JSON
M
Authentication data
JSON
C
In case the authentication process included a cardholder challenge additional information about the challenge result will be provided.
Browser Payment Response
Additionally the JSON formated data elements as listed below are trasferred in the HTTP response body to the cardholder browser. Please note that the data elements (i.e. MID
, Len
, Data
) are base64 encoded.
Data Elements
default | Beschreibung |
---|---|
isFirstTimeEnter | false |
hideColumns | true |
sparkName | Sparkline |
hidePane | true |
datepattern | dd M yy |
id | 1625492202597_2129413440 |
worklog | 365|5|8|y w d h m|y w d h m |
isOR | AND |
separator | Point (.) |
order | 0 |
MultiExcerptName | payment_response |
---|
dateFormat | dd M yy |
---|---|
export-word | false |
show-source | false |
export-csv | false |
id | 1625492202598_-100517279 |
transpose | false |
worklog | 365|5|8|y w d h m|y w d h m |
separator | . |
export-pdf | false |
sql | SELECT * FROM T* |
Table Excerpt Include static true name MID page EN:MID type page
Len
integer
M
Length of the unencrypted Data
string
Data
Data
string
M
Blowfish encrypted string containg a JSON object with MID
, PayID
and TransID
MID
, PayID
und TransID
enthältSchema
MultiExcerptName | response_schema |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"MID": {
"type": "string"
},
"Len": {
"type": "integer"
},
"Data": {
"type": "string"
}
},
"required": ["MID", "Len", "Data"],
"additionalProperties": false
} |
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).
Decrypted Data
default | Beschreibung |
---|---|
isFirstTimeEnter | false |
hideColumns | true |
sparkName | Sparkline |
hidePane | true |
datepattern | dd M yy |
id | 1625492202599_-528830725 |
worklog | 365|5|8|y w d h m|y w d h m |
isOR | AND |
separator | Point (.) |
order | 0 |
MultiExcerptName | decrypted_data |
---|
Table Transformer | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||
|
Sample decrypted Data
MultiExcerptName | sample_decrypted_data |
---|
language | xml |
---|---|
linenumbers | true |