Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Google Pay™ 3DS processing for Cryptogram_3DS and PAN_ONLY 

Multiexcerpt
MultiExcerptName3DS2Short1
Info

Please note, that due to PSD2 regulation, payments need to have SCA (Strong Customer Authentication). This also applies to Google Pay™. Google Pay™ in general is providing 2 types of payload containing payment data.

In case of CRYPTOGRAM_3DS payload, payment is already SCA authenticated on the customer device, payload contains proof of authentication and therefore there is no need for addition SCA in form of 3-D Secure.

In case of PAN_ONLY payload, payment data are not SCA authenticated. Therefore in order to avoid Soft Declines, 3-D Secure authentication is required.

Below guide describes how 3-D Secure 2.0 can be applied for Google Pay payments.

This guide can be applied for all Google Pay payments, because

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Kurz
PageWithExcerptWording
will dynamically recognize PAN_ONLY payloads and start the 3-D Secure process. In case of CRYPTOGRAM_3DS payload, 3-D Secure will not be started.


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

Multiexcerpt
MultiExcerptName3DS2Short2
Multiexcerpt
MultiExcerptNameServer-2-Server Sequence Diagram
shouldDisplayInlineCommentsInIncludesfalse

  

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.

Table of Contents


Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNameLink_EMV3DS
DisableCachingtrue
PageWithExcerptReuse API

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNameLink_APIPlayground
DisableCachingtrue
PageWithExcerptReuse API

Payment Initiation

Multiexcerpt
MultiExcerptName3DS2Short3

The initial request to 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
will be the same regardless of the underlying 3-D Secure Protocol.

Multiexcerpt
MultiExcerptNamePayment Initiation
shouldDisplayInlineCommentsInIncludesfalse

  


In order to start Google Pay™ 3-D Secure payment sequence please post the following key-value-pairs to 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNameBaseURL
PageWithExcerptWording
googlepay.aspx.


Call of interface: general parameters

To carry out a Google Pay payment via a Server-to-Server connection, please use the following URL:

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNameBaseURL
PageWithExcerptWording
googlepay.aspx

Request Elements

 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNameRequest_Intro
PageWithExcerptReuse API

Table Filter
defaultBeschreibung
isFirstTimeEnterfalse
hideColumnstrue
sparkNameSparkline
hidePanetrue
datepatterndd M yy
id1640783050667_1204432564
worklog365|5|8|y w d h m|y w d h m
isORAND
separatorPoint (.)
order0
"transactionId
Multiexcerpt
MultiExcerptNamerequest_elements

Axepta Platform Message version. Valid values:

Table Transformer
dateFormatdd M yy
export-wordfalse
show-sourcefalse
export-csvfalse
id1640783050669_-1498353692
transposefalse
worklog365|5|8|y w d h m|y w d h m
separator.
export-pdffalse
sqlSELECT * FROM T*


KeyRESTFormatCNDDescriptionBeschreibung

MerchantID

BasicAuth.Username

ans..30

M

MerchantID, assigned by BNP. Additionally this parameter has to be passed in plain language too.

 

msgver---

ans..5

M

Axepta Platform Message version. Valid values:

ValueDescription
2.0With 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.


 

TransID"transactionId": "..."

ans..64

MTransactionID provided by you which should be unique for each payment

 

ReqId"requestId": "..."

ans..32

O

To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, Axepta Platform will not carry out the payment or new action, but will just return the status of the original transaction or action.

Please note that the Axepta Platform must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on Platform does not take effect. Submissions with identical ReqID for an open status will be processed regularly.

Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the Platform.

 

RefNr"referenceNumber

Table Excerpt Include
isFirstTimeEntertrue
statictrue
v2
nameMerchantID_REST
pageMerchantID
typepage

Table Excerpt Include
isFirstTimeEntertrue
statictrue
v2
nameMsgVer_REST
pagemsgver
typepage

Table Excerpt Include
isFirstTimeEntertrue
statictrue
v2
nameTransID_REST
pageTransID
typepage

Table Excerpt Include
isFirstTimeEntertrue
statictrue
v2
nameReqId-ans..32_REST
pageReqId
typepage

MerchantID

BasicAuth.Username

ans..30

M

MerchantID, assigned by BNP. Additionally this parameter has to be passed in plain language too.

msgver---

ans..5

M
ValueDescription
2.0With 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.
TransID
": "..."

ans..64

MTransactionID provided by you which should be unique for each payment

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 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePartner-Name
PageWithExcerptWording
settlement file (CTSF) we cannot add the additional payment data.

(info) Details on supported format can be found below in payment specific section.

multiexcerpt-

ReqId"requestId": "..."

ans..32

O

To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, Axepta Platform will not carry out the payment or new action, but will just return the status of the original transaction or action.

Please note that the Axepta Platform must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on Platform does not take effect. Submissions with identical ReqID for an open status will be processed regularly.

Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the Platform.

KeyRESTFormatCNDDescriptionBeschreibung
RefNr"referenceNumber": "..."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 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePartner-Name
PageWithExcerptWording
settlement file (CTSF) we cannot add the additional payment data.

(info) Details on supported format can be found below in payment specific section.

multiexcerpt-include
SpaceWithExcerptEN
MultiExcerptNameRefNr_Ascii
PageWithExcerptReuse API

Eindeutige Referenznummer des Händlers, welche als Auszahlungsreferenz in der EPA-Datei des Acquirers dient.Bitte beachten Sie, dass ohne die eigene Shop-Referenzlieferung die EPA-Transaktion nicht ausgelesen werden kann und wir die zusätzlichen Zahlungsdaten nicht in die zusätzliche

Multiexcerpt include
SpaceWithExcerptDE
MultiExcerptNamePartner-Name
PageWithExcerptDE:Wording
Abrechnungsdatei (CTSF) aufnehmen können.

(info) Einzelheiten zum unterstützten Format finden Sie weiter unten im zahlungsspezifischen Abschnitt.

Multiexcerpt include
SpaceWithExcerptDE
MultiExcerptNameRefNr_Ascii
PageWithExcerptDE:Reuse API

Table Excerpt Include
isFirstTimeEntertrue
statictrue
v2
nameAmount_REST
pageAmount
typepage

Multiexcerpt

table-excerpt

-include

isFirstTimeEnter

SpaceWithExcerpt

true

DE

static

MultiExcerptName

true

RefNr_Ascii

v2nameCurrency_RESTpageCurrencytypepage

Table Excerpt Include
isFirstTimeEntertrue
statictrue
v2
nameCapture_REST
pageCapture
typepage

KeyRESTFormatCNDDescriptionBeschreibungOrderDesc"order": {"description": "..."}ans..768OOrder descriptionBeschreibung der Bestellung

browserInfo

"browserInfo": JSON

JSON

M

Accurate browser information are needed to deliver an optimized user experience. Required for 3-D Secure 2.0 transactions.

Exakte Browserinformationen sind nötig, um eine optimierte Nutzererfahrung zu liefern. Erforderlich für 3-D Secure 2.0 Transaktionen.

billToCustomer

"billing": JSON

JSON

C

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.

PageWithExcerptDE:Reuse API

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

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Axepta Helpdesk, if you want to capture amounts <100 (smallest currency unit).

 

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

a3

M

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table

 

Capture

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

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

"capture": ...


an..6

OM

Determines the type and time of capture.

Capture ModeDescription
AUTOCapturing immediately after authorisation (default value).
MANUALCapturing made by the merchant. Capture is normally initiated at time of delivery.
<Number>Delay in hours until the capture (whole number; 1 to 696).


 

OrderDesc"order": {"description": "..."}ans..768OOrder description

 

browserInfo

"browserInfo": JSON

JSON

M

Accurate browser information are needed to deliver an optimized user experience. Required for 3-D Secure 2.0 transactions.

 

billToCustomer

"billing": JSON

JSON

C

The customer that is getting billed for the goods and / or services. Required unless market or regional mandate restricts sending this information.

 

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

ans..256

C

Complete URL which Platform calls 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.

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.

(info) Common notes:

  • 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.

 

MAC

---

an64

M
Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:
  • HMAC Authentication (Request)
  • HMAC Authentication (Notify)

 

TokenExt

"payment": {"googlePay": { "token": "..." }}

ans..1024

M

Google Pay Token as JSON string in the Base64 format
Example for TokenExt

{
 "signature":

Table Excerpt Include
isFirstTimeEntertrue
statictrue
v2
nameURLNotifyCC_REST
pageURLNotify
typepage

Table Excerpt Include
isFirstTimeEntertrue
statictrue
v2
nameMAC_REST
pageMAC
typepage

Google Pay Token als JSON-String im Base64-Format

{ "signature": it if your processor is RedSys. For other processors, it is not obligatory to provide this information.

Key

REST

Format

CND

Description

Beschreibung

TokenExt

"payment": {"googlePay": { "token": "..." }}

ans..1024

M

Google Pay Token as JSON string in the Base64 format

Code Block
languagexml
titleExample for TokenExt
{
 "signature": "MEQCIC4z/QHSrzekRkkuk3vGYxBTBdNgEQl5XFHx0Wk5fFLIUAiB3+q227havAJdagfGZaMXbefhatdJE7Df2qrIoKDv1Og==",
 "protocolVersion": "ECv1",
 "signedMessage": "{\"encryptedMessage\":\"bOYRmExGeCsBrFqESt7kd9O1FN+vQZf2KG0UNYC8jNA+VVf9nQeK7lDvU8k37cH+LOziJQkHNL2OxDHIk6GoRV1BrXprwBnAJR0O2VnCUH8lsqq0ELwemeqW364Ir8cU/hDFzWNp+38H25JVDAMExZBKodMMTzUXXgyO+s5jOyAl8jUhnAw3fTRPkefuYsE8NFK5tvcs4L29h87Zo7ot0/8XrUhXt9b/Fld1LEthkuPSN+K1eEFP7bseB6jjRdHnwYAdqiE3iOmh71pcDmNIyrlWRj74UJaszeerZW7DoZNx11oN7fouq/8fe1vklsr/e+y/RSG2nQMWg5yR/fMTfqCyabTDhJMvMM1Zhe91+dQ0/xi/zKRgsIhiongJUjYtoSNIjUHnMLRuVTKdjX50CCI1QOiBtr9h0bOLePhxw9cLYeU1KwCfYJyt28DBKCvaWFSbCl+dzNcZ9B83kv\",\"ephemeralPublicKey\":\"BFUju73/IT/KqnB/nc0W3BaL3BXFybrbYaPiMCKXIcg78PbslwV7MRUq3SpWEDEJT6pakLCvf34412HbDGCpsa4\\u003d\",\"tag\":\"xIuCUWB2U6yWEfidsJpQaa+leU/kqS522JLOnrnk42g\\u003d\"}"
}
Code Block
languagexml
titleBeispiel für TokenExt

"MEQCIC4z/QHSrzekRkkuk3vGYxBTBdNgEQl5XFHx0Wk5fFLIUAiB3+q227havAJdagfGZaMXbefhatdJE7Df2qrIoKDv1Og==",


 "protocolVersion":

"ECv1",


 "signedMessage":

"{\"encryptedMessage\":\"bOYRmExGeCsBrFqESt7kd9O1FN+vQZf2KG0UNYC8jNA+VVf9nQeK7lDvU8k37cH+LOziJQkHNL2OxDHIk6GoRV1BrXprwBnAJR0O2VnCUH8lsqq0ELwemeqW364Ir8cU/hDFzWNp+38H25JVDAMExZBKodMMTzUXXgyO+s5jOyAl8jUhnAw3fTRPkefuYsE8NFK5tvcs4L29h87Zo7ot0/8XrUhXt9b/Fld1LEthkuPSN+K1eEFP7bseB6jjRdHnwYAdqiE3iOmh71pcDmNIyrlWRj74UJaszeerZW7DoZNx11oN7fouq/8fe1vklsr/e+y/RSG2nQMWg5yR/fMTfqCyabTDhJMvMM1Zhe91+dQ0/xi/zKRgsIhiongJUjYtoSNIjUHnMLRuVTKdjX50CCI1QOiBtr9h0bOLePhxw9cLYeU1KwCfYJyt28DBKCvaWFSbCl+dzNcZ9B83kv\",\"ephemeralPublicKey\":\"BFUju73/IT/KqnB/nc0W3BaL3BXFybrbYaPiMCKXIcg78PbslwV7MRUq3SpWEDEJT6pakLCvf34412HbDGCpsa4\\u003d\",\"tag\":\"xIuCUWB2U6yWEfidsJpQaa+leU/kqS522JLOnrnk42g\\u003d\"}"


}

 

Channel

"channel": {"type": "..."}

a..10

C

Channel over which the order is processed. Allowed values are WEBSITE and MOBILE_APP.

The channel parameter is mandatory for RedSys. Please provide

Kanal, über den die Bestellung abgewickelt wird. Erlaubt sind die Werte WEBSITE und MOBILE_APP.

Der Parameter Channel ist für RedSys obligatorisch. Bitte geben Sie ihn an, wenn Ihr Prozessor RedSys ist. Für andere Prozessoren ist die Angabe dieser Information nicht obligatorisch.

it if your processor is RedSys. For other processors, it is not obligatory to provide this information.

 


General parameters for credit card payments via socket connection

(info) Please note the additional parameter for a specific credit card integration in the section "Specific parameters"


Response Elements (authentication)

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNameResponse_Intro
PageWithExcerptReuse API

Table Filter
defaultBeschreibung
isFirstTimeEnterfalse
hideColumnstrue
sparkNameSparkline
hidePanetrue
datepatterndd M yy
id1640783050671_-1200718893
worklog365|5|8|y w d h m|y w d h m
isORAND
separatorPoint (.)
order0
Multiexcerpt
MultiExcerptNameresponse_elements
Table Transformer
dateFormatdd M yy
export-wordfalse
show-sourcefalse
export-csvfalse
id1640783050672_-872780111
transposefalse
worklog365|5|8|y w d h m|y w d h m
separator.
export-pdffalse
sqlSELECT * FROM T*


KeyFormatCNDDescription

mid

ans..30

M

MerchantID, assigned by BNP

PayID

an32

M

ID assigned by Platform 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 Platform

TransID

ans..64

MTransactionID provided by you which should be unique for each payment

Table Excerpt Include
statictrue
nameMID
pagemid
typepage

Table Excerpt Include
statictrue
namePayID
pagePayID
typepage

Table Excerpt Include
statictrue
nameXID
pageXID
typepage

Table Excerpt Include
statictrue
nameTransID
pageTransID
typepage

Beschreibung

Values accepted:

  • AUTHENTICATION_REQUEST

  • PENDING
  • FAILED

KeyFormatCNDDescription
refnr
OReference number as given in requestReferenznummer wie im Request angegeben

Status

a..20

M

Status of the transaction.

Status der Transaktion.

Zulässige Werte:

  • AUTHENTICATION_REQUEST

  • PENDING
  • FAILED

Table Excerpt Include
statictrue
nameDescription
pageDescription
typepage

Table Excerpt Include
statictrue
nameCode
pageCode
typepage

Table Excerpt Include
statictrue
nameUserData
pageUserData
typepage

Beschreibung 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

Values accepted:

  • AUTHENTICATION_REQUEST

  • PENDING
  • FAILED

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 Platform Response Codes (A4 Error codes)

UserData

ans..1024

O

If specified at request, Platform forwards the parameter with the payment result to the shop.

KeyFormatCNDDescription

cardJSONMCard dataKartendaten

versioningdata

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.

threeDSLegacy

JSON

C

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).

(info) BASEURL=

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNameBaseURL
PageWithExcerptWording

Multiexcerpt
MultiExcerptNameversioningdata
Code Block
languagejson
linenumberstrue
{
	"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": "BASEURL/cbThreeDS.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
MultiExcerptNamethreeDSMethodURL
shouldDisplayInlineCommentsInIncludesfalse

  


Please note that the threeDSMethodURL will be populated by 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
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
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
in case of a mandated challenge or a frictionless flow.


3-D Secure Method: No issuer threeDSMethodURL

Multiexcerpt
MultiExcerptNameNo issuer threeDSMethodURL
shouldDisplayInlineCommentsInIncludesfalse

  


3-D Secure Method Form Post

Multiexcerpt
MultiExcerptName3ds_method
Code Block
languagexml
linenumberstrue
<form name="frm" method="POST" action="Rendering URL">
    <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIn0">
</form>

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.


Info
titleNetcetera 3DS Web SDK

You may use the operations 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 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

Multiexcerpt
MultiExcerptNameacs_response
Code Block
languagexml
linenumberstrue
<!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

Multiexcerpt
MultiExcerptName3ds_method_notification_form
Code Block
languagexml
linenumberstrue
<form name="frm" method="POST" action="3DS Method Notification URL">
    <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImUxYzFlYmViLTc0ZTgtNDNiMi1iMzg1LTJlNjdkMWFhY2ZhMiJ9">
</form>



Note

Please note that the threeDSMethodNotificationURL as embedded in the Base64 encoded threeDSMethodData value points to 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
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
Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
.

Authentication

If 3-D Secure Method is supported by the issuer ACS and was invoked by the merchant 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
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 necessary 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
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, 
Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
will automatically continue and respond to the cardholder browser once the authorization completed.


Cardholder Challenge: Browser Response

Multiexcerpt
MultiExcerptNameChallenge - Browser Response
shouldDisplayInlineCommentsInIncludesfalse

  

Browser Challenge Response

Data Elements

Table Filter
defaultBeschreibung
isFirstTimeEnterfalse
hideColumnstrue
sparkNameSparkline
hidePanetrue
datepatterndd M yy
id1640783050673_1475503702
worklog365|5|8|y w d h m|y w d h m
isORAND
separatorPoint (.)
order0
Multiexcerpt
MultiExcerptNamechallenge_response
Table Transformer
dateFormatdd M yy
export-wordfalse
show-sourcefalse
export-csvfalse
id1640783050674_1368690112
transposefalse
worklog365|5|8|y w d h m|y w d h m
separator.
export-pdffalse
sqlSELECT * FROM T*
KeyFormatCNDDescriptionBeschreibung

acsChallengeMandated

boolean

M

Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable:

  • true → Challenge is mandated by local/regional regulations
  • false → Challenge is not mandated by local/regional regulations, but is deemed necessary by the ACS

Zeigt an, ob eine Challenge für die Autorisierung einer Transaktion wegen lokaler/regionaler Vorschriften oder anderer Variablen nötig ist:

  • true → Challenge ist obligatorisch wegen lokaler/regional Vorschriften
  • false → Challenge ist nicht obligatorisch wegen lokaler/regional Vorschriften, wird aber von ACS als nötig angesehen

challengeRequest

object

M

Challenge request object

Objekt Challenge-Anfrage

base64EncodedChallengeRequest

string

M

Base64-encoded Challenge Request object

Base64-codiertes Objekt Challenge-Anfrage

acsURL

string

M

Fully qualified URL of the ACS to be used to post the Challenge Request

Vollständige URL des ACS, die für das Posten der Challenge-Anfrage verwendet werden soll

Schema: Browser Challenge Response

Multiexcerpt
MultiExcerptNameschema
Code Block
languagejson
linenumberstrue
{
	"$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

Multiexcerpt
MultiExcerptNamesample
Code Block
languagejson
linenumberstrue
{
	"acsChallengeMandated": false,
	"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.

Table Filter
defaultBeschreibung
isFirstTimeEnterfalse
hideColumnstrue
sparkNameSparkline
hidePanetrue
datepatterndd M yy
id1640783050675_1949489413
worklog365|5|8|y w d h m|y w d h m
isORAND
separatorPoint (.)
order0
Multiexcerpt
MultiExcerptNameauthentification_notification
Table Transformer
dateFormatdd M yy
export-wordfalse
show-sourcefalse
export-csvfalse
id1640783050676_1086794018
transposefalse
worklog365|5|8|y w d h m|y w d h m
separator.
export-pdffalse
sqlSELECT * FROM T*
w d h m
separator.
export-pdffalse
sqlSELECT * FROM T*


KeyFormatCNDDescription

mid

ans..30

M

MerchantID, assigned by BNP

PayID

an32

M

ID assigned by Platform for the payment, e.g. for referencing in batch files as well as for capture or credit request.

TransID

ans..64

MTransactionID provided by you which should be unique for each payment
Code

an8

M

Error code according to Platform Response Codes (A4 Error codes)

MAC

an64

M
Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

Table Excerpt Include
statictrue
nameMID
pagemid
typepage

Table Excerpt Include
statictrue
namePayID
pagePayID
typepage

Table Excerpt Include
statictrue
nameTransID
pageTransID
typepage

Table Excerpt Include
statictrue
nameCode
pageCode
typepage

Table Excerpt Include
statictrue
nameMAC
pageMAC
typepage

Beschreibung
KeyFormatCNDDescription

authenticationResponse

JSON

M

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.

Challenge Request

Multiexcerpt
MultiExcerptNamechallenge_request
Code Block
languagexml
linenumberstrue
<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

Multiexcerpt
MultiExcerptNameinit_challenge_request
Code Block
languagexml
linenumberstrue
<!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 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
and must not be changed.

Authorization

After successful cardholder authentication or proof of attempted authentication/verification is provided 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
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 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
will not continue with an authorization request.

In both cases 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Kurz
PageWithExcerptWording
will deliver a notification with the authentication result to the merchant specified URLNotify with the data elements as listed in the table below.

Payment Notification

 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNameKvpResponse_IntroURL
PageWithExcerptReuse API

the authentication result to the merchant specified URLNotify with the data elements as listed in the table below.

Payment Notification

 In case of using Key-Value-Pair API

The following table gives the result parameters which Axepta Platform transmits to URLSuccess or URLFailure and URLNotify. If you have specified the Response=encrypt parameter, the following parameters are sent Blowfish encrypted to your system:

(info) pls. be prepared to receive additional parameters at any time and do not check the order of parameters

(info) the key (e.g. mid, RefNr) should not be checked case-sentive


Table Filter
defaultBeschreibung
isFirstTimeEnterfalse
hideColumnstrue
sparkNameSparkline
hidePanetrue
datepatterndd M yy
id1640783050677_-1425358255
worklog365|5|8|y w d h m|y w d h m
isORAND
separatorPoint (.)
order0


Multiexcerpt
MultiExcerptNamepayment_notification
Table Transformer
dateFormatdd M yy
export-wordfalse
show-sourcefalse
export-csvfalse
id1640783050679_-174924123
transposefalse
worklog365|5|8|y w d h m|y w d h m
separator.
export-pdffalse
sqlSELECT * FROM T*


KeyFormatCNDDescription

mid

ans..30

M

MerchantID, assigned by BNP

msgver

ans..5

M

Axepta Platform Message version. Valid values:



2.0With 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.
PayID

an32

M

ID assigned by Platform 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 Platform

TransID

ans..64

MTransactionID provided by you which should be unique for each payment
schemeReferenceID

ans..64

C

Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmissions.

Mandatory: CredentialOnFile – initial false – unscheduled MIT / recurring

schemeReferenceID is returned for 3DS2-payments. 

Table Excerpt Include
statictrue
nameMID
pagemid
typepage

Table Excerpt Include
statictrue
nameMsgVer
pagemsgver
typepage

Table Excerpt Include
statictrue
namePayID
pagePayID
typepage

Table Excerpt Include
statictrue
nameXID
pageXID
typepage

Table Excerpt Include
statictrue
nameTransID
pageTransID
typepage

Table Excerpt Include
statictrue
nameschemeReferenceID
pageschemeReferenceID
typepage

HH:mm:ssffZeitstempel der Transaktion im Format TT.MM.JJJJ

Status der Transaktion.

Zulässige Werte

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

KeyFormatCNDDescriptionBeschreibung

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 .

M

Status of the transaction.

Values accepted:

  • Authorized

  • OK (Sale)

  • PENDING
  • FAILED

Table Excerpt Include
statictrue
nameDescription
pageDescription
typepage

Table Excerpt Include
statictrue
nameCode
pageCode
typepage

Table Excerpt Include
statictrue
nameMAC
pageMAC
typepage

page
Beschreibung containing IP informationObjekt mit IP-InformationenAuthentisierungsdaten

In case of Authentication-only the Status will be either OK or FAILED .

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 Platform Response Codes (A4 Error codes)

MAC

an64

M
Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:
KeyFormatCNDDescription

card

JSON

M

Card data

Kartendaten

ipinfo

JSON

O

Object

containing IP information

threedsdata

JSON

M

Authentication data

resultsresponse

JSON

C

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
externalPaymentDataJSONOOptional additional data from acquirer/issuer/3rd party for authorization.Optionale Daten des Acquirers/Issuers/externen Dienstleisters für eine Autorisierung
Table Excerpt Include
statictrue
namePCNr
PCNr
typepage

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.

Data Elements

Table Filter
defaultBeschreibung
isFirstTimeEnterfalse
hideColumnstrue
sparkNameSparkline
hidePanetrue
datepatterndd M yy
id1640783050680_-40409341
worklog365|5|8|y w d h m|y w d h m
isORAND
separatorPoint (.)
order0
Multiexcerpt
MultiExcerptNamepayment_response
page
Table Transformer
dateFormatdd M yy
export-wordfalse
show-sourcefalse
export-csvfalse
id1640783050681_-2117094745
transposefalse
worklog365|5|8|y w d h m|y w d h m
separator.
export-pdffalse
sqlSELECT * FROM T*
Table Excerpt Include
statictrue
nameMID
pagemid
type
.
export-pdffalse
sqlSELECT * FROM T*


BeschreibungLänge des unverschlüsselten Strings Data TransID Blowfish-verschlüsselter String, der ein JSON-Objekt mit MID , PayID und enthält
KeyFormatCNDDescription

MID

ans..30

M

MerchantID, assigned by BNP

Len

integer

M

Length of the unencrypted Data string

Data

string

M

Blowfish encrypted string containing a JSON object with MID , PayID and

TransID

Schema

Multiexcerpt
MultiExcerptNameresponse_schema
Code Block
languagejson
linenumberstrue
{
	"$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

Table Filter
defaultBeschreibung
isFirstTimeEnterfalse
hideColumnstrue
sparkNameSparkline
hidePanetrue
datepatterndd M yy
id1640783050682_1987237582
worklog365|5|8|y w d h m|y w d h m
isORAND
separatorPoint (.)
order0
Multiexcerpt
MultiExcerptNamedecrypted_data
page
Table Transformer
dateFormatdd M yy
export-wordfalse
show-sourcefalse
export-csvfalse
id1640783050683_-1436104910
transposefalse
worklog365|5|8|y w d h m|y w d h m
separator.
export-pdffalse
sqlSELECT * FROM T*
sqlSELECT * FROM T*


KeyFormatCNDDescription

MID

ans..30

M

MerchantID, assigned by BNP

PayID

an32

M

ID assigned by Platform for the payment, e.g. for referencing in batch files as well as for capture or credit request.

TransID

ans..64

MTransactionID provided by you which should be unique for each payment

Table Excerpt Include
statictrue
nameMID
pagemid
typepage

Table Excerpt Include
statictrue
namePayID
pagePayID
typepage

Table Excerpt Include
statictrue
nameTransID
pageTransID
type


Sample decrypted Data

Multiexcerpt
MultiExcerptNamesample_decrypted_data
Code Block
languagexml
linenumberstrue
MID=YourMID&PayID=PayIDassignedbyPlatform&TransID=YourTransID