3-D Secure
Initial Authentication Request
Use either the payment card or the payment token to initiate a Primary Payment Transaction.
You can instruct the payment to use 3-D Secure if you want to enforce it. The relevant requestTypes for 3-D Secure authentication are as follows:
- PaymentCardPreAuthTransaction
- PaymentCardSaleTransaction
- PaymentTokenPreAuthTransaction
- PaymentTokenSaleTransaction
- PaymentCardPayerAuthTransaction
This message needs to include the authenticationRequest object in the transaction request message and includes the following values:
| Attribute | Description |
|---|---|
authenticationType | the value Secure3DAuthenticationRequest is a default value for 3DS authentication request |
termURL | Indicates the callback URL where the results of the authentication process should be posted by the ACS server (this is the Access Control Server that executes the cardholder authentication). |
methodNotifictionURL | In order to be notified about the 3DSMethod form display completion, you must also submit this element in your transaction request. The URL should be uniquely identifiable, so when there is a notification received on this URL, you should be able to map it with the corresponding transaction. This eliminates any dependency on the Secure3dTransId which you will receive with the 3DSMethod form response. An easy way to ensure correct transaction mapping is to pass a transaction reference as a query string. |
challengeIndicator | In case you would like to influence which authentication flow should be used, you can submit this optional element with one of the values listed below. In case the Challenge Indicator is not sent within your transaction request, the Gateway will populate the default value “01” – No preference. |
challengeWindowSize | If you want to define the size of the challenge window displayed to your customers during the authentication process, you can submit this optional element with one of the values listed below. |
Available values for challengeIndicator are:
01 = No preference (You have no preference whether a challenge should be performed. This is the default value)
02 = No challenge requested (You prefer that no challenge should be performed.)
03 = Challenge requested: 3DS Requestor Preference (You prefer that a challenge should be performed)
04 = Challenge requested: Mandate (There are local or regional mandates that mean that a challenge must be performed)
05 = No challenge requested (Transaction Risk Analysis is already performed)
06 = No challenge requested (Data Share Only)
07 = No challenge requested (SCA is already performed)
08 = No challenge requested (Utilize whitelist exemption if no challenge required)
09 = Challenge requested (Whitelist prompt requested if challenge required)
Available values for challengeWindowSize are:
01 = 250 x 400
02 = 390 x 400
03 = 500 x 600
04 = 600 x 400
05 = Full screen
Based on the payment schemes' observation it is highly recommended to use the value "05 - Full screen" only for browser-based flows. Using full screen mode in app-based flows where the authentication of the cardholder happens on a smartphone or tablet might cause time-outs and trigger an error on issuer/ACS side.
It is highly recommended to include also Billing and Shipping details in your transaction request to lower the risk of authentication declines. To do this, ensure you populate the objects in any of the sale or preauth 'requestType' payloads.
The following JSON documents represents an example of a basic Sale transaction request and a Sale request including browser parameters:
{
"requestType": "PaymentCardSaleTransaction",
"transactionAmount": {
"total": "122.04",
"currency": "USD"
},
"paymentMethod": {
"paymentCard": {
"number": "403587XXXXXX4977",
"securityCode": "977",
"expiryDate": {
"month": "12",
"year": "24"
}
}
},
“authenticationRequest”: {
"authenticationType": "Secure3DAuthenticationRequest",
"termURL": "https://www.mywebshop.com/process3dSecure",
"methodNotificationURL": "https://www.mywebshop.com/process3dSecureMethodNotification?transactionReferenceNumber=ffffffff-ba0b-539f-8000-016b2343ad7e",
"challengeIndicator": "01",
"challengeWindowSize": "01"
}
}
{
"requestType":"PaymentCardSaleTransaction",
"transactionAmount":{
"total":"12.00",
"currency":"EUR"
},
"paymentMethod":{
"paymentCard":{
"number":"401699*******0022",
"securityCode":"XXX",
"expiryDate":{
"month":"12",
"year":"27"
}
}
},
"authenticationRequest":{
"authenticationType":"Secure3DAuthenticationRequest",
"termURL":"https://test.com/webshop/simulator/secure3d/return",
"methodNotificationURL":"https://test.test/notify",
"challengeIndicator":"01",
"cardHolderBrowserParams":{
"browserAcceptHeaders":"Accept: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8",
"browserIP":"85.117.56.12",
"browserLanguage":"es-419",
"browserColorDepth":"32",
"browserScreenHeight":"1080",
"browserScreenWidth":"1920",
"browserTimeZone":"-300",
"browserUserAgent":"Lynx/2.8.4rel.1 libwww-FM/2.14 SSL-MM/1.4.1 OpenSSL/0.9.6c"
}
}
}
Not all Issuers support the collection of browser data using the 3DSMethod Form. In those cases, no data will be posted to the methodNotificationURL, and the flow should continue by posting a status of EXPECTED_BUT_NOT_RECEIVED – see below.
Authentication Response
Our response will include a 3DSMethod element, which generates a hidden iframe that helps to collect the browser data for the issuers. This information adds to the overall consumer profile and helps in identifying potentially fraudulent transactions. It also increases the probability of a frictionless, successful transaction.
You will need to include the 3DSMethod in your website as hidden iframe. No user interface screen is presented to the cardholder.
At this point, a verification request takes place to determine if the 3-D Secure system is functional and the cardholder is enrolled for 3-D Secure. If the 3-D Secure system is not functioning or if the cardholder is not enrolled, the transaction will process normally and be approved or declined by the processing network.
In the above case the transaction status will appear like so:
transactionStatus = `APPROVED` || `DECLINED`
If the cardholder is verified to be enrolled in the 3-D Secure program, then an 'authenticationResponse' object will be included in the transaction response.
While awaiting the response the transaction will have the following transaction status:
transactionStatus = WAITING
The authenticationResponse object will contain the following values:
| Attribute | Value |
|---|---|
type | 3D_SECURE |
version | 2.1 or 2.2 |
secure3DMethod/methodForm | HTML form data with hidden iFrame used to collect the web browser data for the Issuer. |
secure3DMethod/secure3dTransId | A unique identifier for the transaction provided by the Issuer ACS server. |
The following JSON document represents an example of a response:
{
"clientRequestId": "30dd879c-ee2f-11db-8314-0800200c9a66",
"apiTraceId": "rrt-0c80a3403e2c2def0-d-ea-28805-6810951-2",
"ipgTransactionId": "838916029301",
"transactionType": "SALE",
"transactionTime": 1518811817,
"approvedAmount": {
"total": 122.04,
"currency": "USD"
},
"transactionStatus": "WAITING",
“authenticationResponse”: {
"type": "3D_SECURE",
"version": "2.1",
"secure3dMethod": {
"methodForm": "<!DOCTYPE iframe SYSTEM "about:legacy-compat">
<iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame"
style="width: 1px; height: 1px; display: none;" src="javascript:false;"
xmlns="http://www.w3.org/1999/xhtml">
<!--.--> </iframe><form id="tdsMmethodForm"
name="tdsMmethodForm"
action=https://localhost.modirum.com:8543/dstests/ACSEmu2
method="post"
target="tdsMmethodTgtFrame" xmlns="http://www.w3.org/1999/xhtml">
<input type="hidden" name="3DSMethodData"
value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjAwMDAwMDAwLTU2NzYtNTY2My
04MDAwLTAwMDAw &#10;MDAwNDFhOSIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9
uVVJMIiA6ICJodHRwczovL2xvY2Fs&#10;aG9zdC5tb2RpcnVtLmNvbTo4NTQzL21kcGF5bXBpL
01lcmNoYW50U2VydmVyP21uPVkmdHhpZD0x
&#10;NjgwOSZkaWdlc3Q9aSUyQnhhUEF5NWFOcVJRbllqNmozbWFDZlFJbTdFdjJYTm
kwNnh6YmZNJTJG&#10;R3MlM0QiIH0"/> <input type="hidden"
name="threeDSMethodData"
value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjAwMDAwMDAwLTU2NzYtNTY2
My04MDAwLTAwMDA
w&#10;MDAwNDFhOSIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA
6ICJodHRwczovL2xvY 2Fs&#10;aG9zdC5tb2RpcnVtLmNvbTo4NTQzL21kcGF5bXBpL01lcm
NoYW50U2VydmVyP21uPVkmdHhpZD0x&#10;NjgwOSZkaWdlc3Q9aSUyQnhhUEF5NWFOcV
JRbllqNmozbWFDZlFJbTdFdjJYTmkwNnh6YmZNJTJG&#10;R3MlM0QiIH0"/>
</form><script type="text/javascript"
xmlns="http://www.w3.org/1999/xhtml">
document.getElementById("tdsMmethodForm").submit(); </script>",
"secure3dTransId": "3ac7caa7-aa42-2663-791b-2ac05a542c4a"
}
}
}
3DSMethod Notification Request & Response
The 3-D Secure 'methodForm' is used to provide details of the cardholder environment to the Issuer Access Control Server (ACS). The methodForm contains the HTML for a hidden iFrame which is to be included in your web page. This will force the information to be automatically posted to the ACS server via Fiserv. The HTML information is a self-contained HTML block that does not need to be modified or posted, as it will be taken care of automatically when the page in which it is inserted is rendered. Alternatively, this can be created on a page which never becomes visible to the cardholder.
If received properly, the response data will be posted to the URL provided in the original methodNotificationURL field and the posted message will contain a threeDSServerTransID field containing the unique ACS transaction id associated with the original request. Note, that the payload for this response will contain a single element called threeDSMethodData. That element will contain a base64 encoded JSON response that contains the threeDSServerTransID field.
Example:
<form name="frm" method="POST" action="{value from methodNotificationURL}">
<input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSJ9">
</form>
Decoded threeDSMethodData:
{"threeDSServerTransID":"3ac7caa7-aa42-2663-791b-2ac05a542c4a"}
The threeDSServerTransID is not required for any further 3DS processing. However, it is recommended to save this value for reference to the 3DS Server in the future if necessary.
It is highly recommended to wait for 10 seconds for the above POST operation to complete and then determine the methodNotificationStatus as follows:
| Status | Description |
|---|---|
RECEIVED | You have submitted the element methodNotificationURL in the initial Sale transaction request and have received the notification from ACS within 10 seconds, you will receive HTTP POST message from ACS, which will contain a unique transaction identifier represented by secure3dTransId |
EXPECTED_BUT_NOT_RECEIVED | You have submitted the element 'methodNotificationURL' in the initial Sale transaction request and have not received the notification from ACS within 10 seconds. |
NOT_EXPECTED | You have NOT submitted the element methodNotificationURL in the initial Sale transaction request. |
There may be occasions where you will observe duplicate responses to your '3DSMethod Notification URL' or 'Term URL', this could be due to duplicate requests being sent from an issuers ACS or perhaps user behaviour within the browser. It is recommended that you build handling into your system, so in the event you receive a duplicate response to your '3DSMethod Notification URL' or 'Term URL' you do not then send an additional/duplicated request to the Gateway.
Frictionless Flow
Request to continue with 3DS Authentication
Once the 3DS Method call has been completed, you need to notify the Gateway, that the authentication process can continue by submitting the methodNotificationStatus element with the values based on corresponding conditions from the 3DSMethod form above. This is done by performing a PATCH operation on the original transaction.
You may also include the optional cardholder billing address and the security code at this time.
The following JSON document represents an example of a request to be sent after 3DSMethod form display:
{
"authenticationType": "Secure3DAuthenticationUpdateRequest",
"storeId": "12345500000",
"billingAddress": {
"company": "Test Company",
"address1": "5565 Glenridge Conn",
"address2": "Suite 123",
"city": "Atlanta",
"region": "Georgia",
"postalCode": "30342",
"country": "USA"
},
"securityCode": "123",
"methodNotificationStatus": "RECEIVED"
}
Final 3DS Response
When it is determined that a frictionless flow has been performed (i.e. the customer has been fully authenticated by their bank without the need for direct interaction), the 3-D Secure process is completed and transaction authorization is processed.
The transaction response contains a secure3dResponse object and the transaction is either approved or declined.
transactionStatus = APPROVED or DECLINED
The 'secure3dResponse' object will contain the following field: responseCode3dSecure
The following JSON document represents an example of a response you receive from the API indicating, that the authorisation has been successful:
{
"clientRequestId": "30dd879c-ee2f-11db-8314-0800200c9a66",
"apiTraceId": "rrt-0c80a3403e2c2def0-d-ea-28805-6810951-2",
"ipgTransactionId": "838916029301",
"transactionType": "SALE",
"transactionTime": 1518811817,
"approvedAmount": {
"total": 122.04,
"currency": "USD"
},
"transactionStatus": "APPROVED",
"schemeTransactionId": "019078743804756",
"processor": {
"responseCode": "00",
"responseMessage": "APPROVED",
"authorizationCode": "OK7118"
},
"secure3dResponse": {
"responseCode3dSecure": "1"
}
}
}
Challenge Flow
The challenge flow is triggered, when the transaction is not considered as low risk or when the Issuer requires additional authentication by the cardholder. The whole process starts with an initial Authorisation or Sale transaction request through the step where 3DSMethod is displayed, as described in Steps 1 through 4 above.
Request to continue with 3DS Authentication
Once the 3DS Method call has been completed, you need to notify the Gateway that the authentication process can continue by submitting the methodNotificationStatus element with the values based on corresponding conditions from the 3DS Method Form above. This is done by performing a PATCH operation on the original transaction.
You may also include the optional cardholder billing address and the security code at this time.
The following JSON document represents an example of a request to be sent after 3DSMethod form display:
{
"authenticationType": "Secure3DAuthenticationUpdateRequest",
"storeId": "12345500000",
"methodNotificationStatus": "RECEIVED"
}
3DS Authentication Response
For the challenge flow, the transaction status will be returned as follows:
transactionStatus = "WAITING"
The response will contain an authenticationResponse object with the following fields:
| Field | Description |
|---|---|
type | 3D_SECURE |
version | 2.1 or 2.2 |
acsURL | The URL to which the 'cReq and 'sessionData' values should be posted for the cardholder challenge to take place. |
termURL | The URL where the results of the authentication will be posted. |
cReq | An encoded challenge request message returned from the ACS server. |
sessionData | An encoded list of session parameters to be used for authentication. Note that this value may not always be provided. |
The following JSON document represents an example of a response:
{
"clientRequestId": "30dd879c-ee2f-11db-8314-0800200c9a66",
"apiTraceId": "rrt-0c80a3403e2c2def0-d-ea-28805-6810951-2",
"ipgTransactionId": "838916029301",
"transactionType": "SALE",
"transactionTime": 1518811817,
"approvedAmount": {
"total": 122.04,
"currency": "USD"
},
"transactionStatus": "WAITING",
"authenticationResponse": {
"type": "3D_SECURE",
"version": "2.1",
"params": {
"acsURL": "https://3ds-acs.test.com/mdpayacs/creq",
"termURL": "https://www.mywebshop.com/process3dSecure/",
"cReq": "ewogICAiYWNzVHJhbCIgOiA...wMDAtMDAwMDAwMDA0MWE5Igp9",
"sessiondata": "50F2156E03083CA665BCB4.."
}
}
}
}
Cardholder Challenge
In the next step you need to POST data to the indicated acsURL usually implemented as an auto-submit form. This needs to be implemented within your website. The cardholder will be redirected to the ACS and presented with the UI to collect the authentication details - for example enter one-time-password or perform authentication using their banking app. After the authentication is completed, the consumer is redirected back to your webpage.
You need to POST the cReq and the sessionData values to the URL specified in the acsURL field.
This information is posted using the following field names:
cReq | The entire base64 encoded cReq message as obtained above. |
|---|---|
threeDSSessionData | The entire base64 encoded sessionData message as obtained above. |
Example:
<form name="frm" method="POST" action="https://3ds-acs.test.modirum.com/mdpayacs/pareq ">
<input type=”hidden” name=”creq” value=”ewogICAiYWNzVHJhbCIgOiA...wMDAtMDAwMDAwMDA0MWE5Igp9”>
<input type=”hidden” name=”threeDSSessionData” value=”50F2156E03083CA665BCB4..”>
</form>
When the authentication is completed, an authentication response will be posted to the URL specified in the termURLfield.
Transaction Completion
After you received the data from the ACS, you need to submit them to the Gateway in cRes element together with the reference to the original transaction. This is done by sending PATCH request to the original transaction and includes the following values:
| authenticationType | Secure3D21AuthenticationUpdateRequest |
|---|---|
acsResponse.cRes | The cRes data posted to the termURL by the ACS server. |
It is highly recommended to include the optional cardholder billing address and the security code at this time.
The following JSON document represents an example of a request with 'cRes' element:
{
"authenticationType": "Secure3DAuthenticationUpdateRequest",
"storeId": "12345500000",
"billingAddress": {
"company": "Test Company",
"address1": "5565 Glenridge Conn",
"address2": "Suite 123"
"city": "Atlanta",
"region": "Georgia",
"postalCode": "30342",
"country": "USA"
},
"securityCode": "123",
"acsResponse": {
"cRes": "ewogICAiYWNzUmVmZX…Fuc1N0YXR…IKfQ=="
}
}
Final Response
Since this transaction was initiated as a 'Sale', the authorization is performed as part of this final step, if the authentication was successful.
The transaction response contains a secure3dResponse object and the transaction is either approved or declined.
The secure3dResponse object will contain the following field: responseCode3dSecure
The following JSON document represents an example of a response you receive indicating that the authorization has been successful:
{
"clientRequestId": "30dd879c-ee2f-11db-8314-0800200c9a66",
"apiTraceId": "rrt-0c80a3403e2c2def0-d-ea-28805-6810951-2",
"ipgTransactionId": "838916029301",
"transactionType": "SALE",
"transactionTime": 1518811817,
"approvedAmount": {
"total": 122.04,
"currency": "USD"
},
"transactionStatus": "APPROVED",
"schemeTransactionId": "019078743804756",
"processor": {
"responseCode": "00",
"responseMessage": "APPROVED",
"authorizationCode": "OK7118"
},
"secure3dResponse": {
"responseCode3dSecure": "1"
}
}
The full list of available response codes you can find here: 3DS response codes
3DS Requestor Initiated Flow (3RI)
The main purpose of 3DS Requestor Initiated (3RI) flow is to provide additional information to the issuer on how to handle the request in situations where the cardholder is not present.
Typical use cases include:
• To add a card to Card-on-File without payment
• To refresh authentication value before expiration
• To provide additional information for subsequent recurring and MIT payments
As 3RI transactions are performed without a cardholder being in session, a frictionless flow without 3DSMethod is applied.
The authentication request is identified as "3RI" once it contains the following elements:
| Parameter | Values |
|---|---|
secure3DDeviceChannel | • 03 = 3RI |
secure3DThreeRIIndicator | • 01 = Recurring transaction • 02 = Instalment transaction • 03 = Add card • 04 = Maintain card information • 05 = Account verification • 06 = Split shipment • 07 = Top-up • 08 = Mail Order • 09 = Telephone Order • 10 = Trust List status check • 11 = Other payment • 12 = Billing Agreement • 13 = Device Binding status check • 14 = Card Security Code status check • 15 = Delayed shipment • 16 = Split payment *Note - in case you use the value 01-Recurring or 02-Installment, you must submit 2 additional parameters recurringFrequencyand recurringExpiryas per specification below |
*recurringFrequency | Indicates the minimum number of days between authorisations for a recurring or instalment transaction, numeric field with values between 1-9999 |
* recurringExpiry | Date after which no further authorisations for a recurring or installment are performed, if no fixed date is defined, please use the value: "99991231" Date format accepted: "YYYYMMDD" |
The following JSON documents represent the examples of 3RI request with minimum set of elements and API response:
{
"requestType": "PaymentCardSaleTransaction",
"transactionAmount": {
"total": "1.00",
"currency": "EUR"
},
"paymentMethod": {
"paymentCard": {
"number": "414746******0083",
"securityCode": "XXX",
"expiryDate": {
"month": "12",
"year": "25"
}
}
},
"authenticationRequest": {
"authenticationType": "Secure3DAuthenticationRequest",
"termURL": "https://test.ipg-online.com/webshop/simulator/secure3d/return",
"methodNotificationURL": "https://test.ipg-online.com/webshop/simulator/secure3d/return",
"browserJavaScriptEnabled": "true",
"challengeIndicator": "06",
"secure3DThreeRIIndicator":"04",
"secure3DDeviceChannel": "03"
}
}
{
"clientRequestId": "fd876084-d887-4b4d-a0f3-6b80f955f8bc",
"apiTraceId": "ZK0bpgEBwEpY-RJX2IUIjAAAAtw",
"ipgTransactionId": "84631281580",
"orderId": "R-6133fa1f-2e3e-4678-955d-060413a855ce",
"transactionType": "SALE",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "VISA",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "12",
"year": "2025"
},
"bin": "414746",
"last4": "0083",
"brand": "VISA"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "VISA"
},
"country": "Singapore",
"terminalId": "80000860",
"merchantId": "000102072004393",
"transactionTime": 1689066407,
"approvedAmount": {
"total": 1.00,
"currency": "EUR",
"components": {
"subtotal": 1.00
}
},
"transactionAmount": {
"total": 1.00,
"currency": "EUR",
"components": {
"subtotal": 1.00
}
},
"transactionStatus": "APPROVED",
"approvalCode": "Y:721185:4631281580:YYYM:970742",
"secure3dResponse": {
"responseCode3dSecure": "1"
},
"schemeTransactionId": "234567891234560",
"processor": {
"referenceNumber": "319209970742",
"authorizationCode": "721185",
"responseCode": "00",
"responseMessage": "Function performed error-free",
"avsResponse": {
"streetMatch": "Y",
"postalCodeMatch": "Y"
},
"securityCodeResponse": "MATCHED"
}
}
Decoupled Authentication
Decoupled authentication is an authentication method whereby authentication can occur independently from the cardholder’s experience with the 3DS Requestor. For Decoupled Authentication, instead of utilizing the "CReq" and "CRes "messages, the ACS authenticates the cardholder outside of the EMV 3DS protocol.
In case you wish to use this particular authentication method, you must include dedicated input parameters:
| decoupledAuthenticationParams | Description |
|---|---|
decMaxTime | Indicates the maximum amount of time that the 3DS Requestor will wait for an ACS to provide the results of a Decoupled Authentication transaction (in minutes). Numeric values between 00001 and 10080 are accepted. |
decReqInd | Indicates whether the 3DS Requestor requests the ACS to utilise Decoupled Authentication and agrees to utilise Decoupled Authentication if the ACS confirms its use. Note: if the element is not provided, the expected action is for the ACS to interpret as "N" • Y = Decoupled Authentication is supported and is preferred as a primary challenge method if a challenge is necessary • N = Do not use Decoupled Authentication |
The following JSON document represents an example of an authentication request to use Decoupled flow:
{
"requestType": "PaymentCardSaleTransaction",
"storeId": "540997003",
"transactionAmount": {
"total": "14.00",
"currency": "USD"
},
"transactionOrigin": "ECOM",
"paymentMethod": {
"paymentCard": {
"number": "49999*****90003",
"securityCode": "1009",
"cardFunction": "CREDIT",
"expiryDate": {
"month": "12",
"year": "25"
}
}
},
"authenticationRequest": {
"authenticationType": "Secure3DAuthenticationRequest",
"termURL": "https://test.ipg-online.com/webshop/simulator/secure3d/return",
"methodNotificationURL": "https://test.test/notify",
"decoupledAuthenticationParams": {
"decMaxTime": "10",
"decReqInd": "Y"
}
}
}
Once the issuers confirmed they support Decoupled Authentication, the Gateway returns a response in a "WAITING" status, until a confirmation about successful authentication is received:
{
"clientRequestId": "2838649",
"apiTraceId": "ZG8ilD1SH3lS2MWu8mcw-QAAAi4",
"ipgTransactionId": "84438343414",
"orderId": "R-95c8430a-2948-45f8-9583-093e3b3c04d8",
"transactionType": "SALE",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "VISA",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "12",
"year": "2025"
},
"cardFunction": "CREDIT",
"bin": "499999",
"last4": "0003",
"brand": "VISA"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "VISA"
},
"transactionTime": 1685004949,
"transactionAmount": {
"total": 14.00,
"currency": "USD",
"components": {
"subtotal": 14.00
}
},
"transactionStatus": "WAITING",
"approvalCode": "?:waiting 3dsecure Decoupled Authentication",
"authenticationResponse": {
"type": "3D_SECURE",
"version": "2.2"
}
}
After you received a confirmation from the issuer, that the authentication have been successful, you must generate a completion request with PATCHing "ipgTransactionId" you obtained in previous step:
{
"authenticationType": "Secure3DAuthenticationUpdateRequest",
"additionalStep": "COMPLETE_DECOUPLED_AUTHENTICATION"
}
Once our 3DSServer received a RReq message from the issuer confirming authentication status, you will receive a response as on example below:
{
"clientRequestId": "2838649",
"apiTraceId": "ZG8rJGIX2yqGEUomhImJWgAAADQ",
"ipgTransactionId": "84438344739",
"orderId": "R-77153b36-5ccc-4ff8-afef-7364226338cd",
"transactionType": "SALE",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "VISA",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "12",
"year": "2023"
},
"cardFunction": "CREDIT",
"bin": "499999",
"last4": "0003",
"brand": "VISA"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "VISA"
},
"terminalId": "1588390",
"merchantId": "939650001885",
"transactionTime": 1685006889,
"approvedAmount": {
"total": 14,
"currency": "USD",
"components": {
"subtotal": 14
}
},
"transactionAmount": {
"total": 14,
"currency": "USD",
"components": {
"subtotal": 14
}
},
"transactionStatus": "APPROVED",
"approvalCode": "Y:OK0074:4438344739:PPXX:970629",
"secure3dResponse": {
"responseCode3dSecure": "1"
},
"schemeTransactionId": "013145568916020",
"processor": {
"referenceNumber": "84438344739",
"authorizationCode": "OK0074",
"responseCode": "00",
"network": "VISA",
"associationResponseCode": "000",
"responseMessage": "APPROVAL",
"avsResponse": {
"streetMatch": "NO_INPUT_DATA",
"postalCodeMatch": "NO_INPUT_DATA"
},
"securityCodeResponse": "NOT_CHECKED"
},
"additionalDetails": {
"additionalResponseData": {
"cardProductID": "?",
"associationResponseCodeAdtl": "00",
"cardBrand": "V"
}
}
}
Authentication with external 3DS provider
In case you are using your own / external 3DS service provider and plan to send authorization request to the Gateway, you need to submit the authentication values obtained from your 3DS service provider.
| Field | Description |
|---|---|
authenticationType | Used for submitting authentication result performed by an external 3-D Secure service provider |
cavv | Authentication value obtained in the authentication response from external 3-D Secure service provider |
dsTransactionId | Authentication transaction reference ID, obtained from external 3-D Secure provider |
authenticationResponse | Represents the result of the authentication, allowed values are : Y = fully authenticated transaction, A = Successful Authentication Attempt; U = Unable to Authenticate by DS or ACS |
secure3DProtocolVersion | Represents the version of 3DS protocol used during authentication, values shall be submitted in a format i.e. 2.2.0, 2.1.0, 2.3.1 etc |
Only the following authentication results are eligible to be passed to the authorization host:
| Use case | authenticationResponse | cavv | responseCode3dSecure |
|---|---|---|---|
| Fully Authenticated transaction (ECI = 02 & 05) | Y | value | 1 |
| Successful Authentication Attempt (ECI = 01 & 06) | A | value | 4 |
| Unable to authenticate on DS or ACS side (ECI07) | U | field must not be submitted | 6 |
The following JSON document represents an example of a sale transaction submitted to our Gateway after being fully authenticated by an external service provider:
{
"requestType": "PaymentCardSaleTransaction",
"transactionAmount": {
"total": "12.00",
"currency": "EUR"
},
"paymentMethod": {
"paymentCard": {
"number": "401699XXXX0006",
"securityCode": "999",
"expiryDate": {
"month": "12",
"year": "24"
}
}
},
"authenticationResult": {
"authenticationType": "Secure3DAuthenticationResult",
"cavv": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
"dsTransactionId": "5a56fdc9-6d47-5fee-8000-000000296743",
"authenticationResponse": "Y",
"secure3DProtocolVersion": "2.2.0"
}
}
The following JSON document represents an example of a response you receive from the Gateway indicating, that the authorization has been successful and flagged as fully authenticated:
{
"clientRequestId": "97c67e8f-7c2d-421d-9d97-b749206aab06",
"apiTraceId": "YJPLezoO2XZa9K8QL10bvgAAA98",
"ipgTransactionId": "84411977859",
"orderId": "R-941fc643-adae-4468-bc48-26e5099f4367",
"transactionType": "SALE",
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "12",
"year": "2024"
},
"bin": "401699",
"last4": "0006",
"brand": "VISA"
},
"paymentMethodType": "PAYMENT_CARD"
},
"country": "USA",
"terminalId": "80000012",
"merchantId": "520334507229862",
"transactionTime": 1620298619,
"approvedAmount": {
"total": 12,
"currency": "EUR",
"components": {"subtotal": 12}
},
"transactionStatus": "APPROVED",
"secure3dResponse": {"responseCode3dSecure": "1"},
"schemeTransactionId": "234567891234560",
"processor": {
"referenceNumber": "112610940537",
"authorizationCode": "005042",
"responseCode": "00",
"responseMessage": "Function performed error-free",
"avsResponse": {
"streetMatch": "Y",
"postalCodeMatch": "Y"
},
"securityCodeResponse": "MATCHED"
}
}
Updated 3 months ago
