BGateway 3DSecure instructions

Before authorization

Before sending an authorization request (getAuthorization) a new request must be sent called get3DSAuthentication.

Example of a get3DSAuthentication request:

<?xml version="1.0" encoding="utf-8"?>
<get3DSAuthentication xmlns="http://tempuri.org/getAuthorization.xsd">
    <Version>1000</Version>
    <Processor>23</Processor>
    <MerchantID>23</MerchantID>
    <SaleDescription>Product Services</SaleDescription>
    <TrAmount>100</TrAmount>
    <TrCurrency>352</TrCurrency>
    <TrCurrencyExponent>0</TrCurrencyExponent>
    <PAN>520618******1111</PAN>
    <ExpDate>2101</ExpDate>
    <MerchantReturnURL>http://localhost/index.html</MerchantReturnURL>
</get3DSAuthentication>

Name	Value
Version Required	Same as in the authorization request. "1000"
Processor Required	Same as in the authorization request.
MerchantID Required	Same as in the authorization request.
SaleDescription Optional	Description of what is being purchased, some issuers will display this text on the 3DS cardholder authentication page.
TrAmount Required	Amount of purchase.
TrCurrency Required	Transaction currency ISO 4217 F.ex. 352 => ISK 978 => EUR
TrCurrencyExponent Required	Exponent of currency f.ex. if you want to authorize amount of 12.30 EUR and TrCurrencyExponent is 2 then TrAmount should be 12.30 * 10^2 = 1230. Please see Appendix for special case regarding ISK.
PAN Required	Cardnumber being authenticated. Card number can be a virtual card (see function getVirtualCard).
MerchantReturnURL Required	The URL the cardholder will be redirected to after authentication. The cardholder will be returned with result data from the issuer (PaRes or CRes) which must be provided in the authorization request.

Example of a get3DSAuthentication response:

<?xml version="1.0"?>
<get3DSAuthenticationReply>
    <Status>
        <ResultCode>0</ResultCode>
        <ResultText/>
    </Status>
    <Version>1000</Version>
    <Processor>23</Processor>
    <MerchantID>23</MerchantID>
    <ThreeDSMessageId>23_20201408041400003</ThreeDSMessageId>
    <ThreeDSStatus>9</ThreeDSStatus>
    <ThreeDSMessage>To be redirected to ACS</ThreeDSMessage>
    <EnrollmentStatus>Y</EnrollmentStatus>
    <RedirectToACSForm>3C21444F43545950452068746D6C2053595354454D202261626F75743A6C6567
6163792D636F6D706174223E0D0D0A3C68746D6C20636C6173733D226E6F2D6A7322206C616E673D22656
E2220786D6C6E733D22687474703A2F2F7777772E77332E6F72672F313939392F7868746D6C223E0D0D0A
3C686561643E0D0D0A3C6D65746120687474702D65717569763D22436F6E74656E742D547970652220636
F6E74656E743D22746578742F68746D6C3B20636861727365743D7574662D38222F3E0D0D0A3C6D657461
20636861727365743D227574662D38222F3E0D0D0A3C7469746C653E3344205365637572652050726F636
57373696E673C2F7469746C653E0D0D0A3C6C696E6B20687265663D2268747470733A2F2F6D70692E626F
7267756E2E69732F6D647061796D70692F7374617469632F6D70692E637373222072656C3D227374796C6
573686565742220747970653D22746578742F637373222F3E0D0D0A3C2F686561643E0D0D0A3C626F6479
3E0D0D0A3C6469762069643D226D61696E223E0D0D0A3C6469762069643D22636F6E74656E74223E0D0D0
A3C6469762069643D226F72646572223E0D0D0A3C68323E3344205365637572652050726F63657373696E
673C2F68323E0D0D0A3C696D67207372633D2268747470733A2F2F6D70692E626F7267756E2E69732F6D6
47061796D70692F7374617469632F7072656C6F616465722E6769662220616C743D22506C656173652077
6169742E2E222F3E0D0D0A3C696D67207372633D2268747470733A2F2F6D70692E626F7267756E2E69732
F6D647061796D70692F7374617469632F6D635F6964636865636B5F68727A5F6C74645F706F735F313033
70782E706E672220616C743D224D61737465724361726420494420436865636B222F3E0D0D0A3C6469762
069643D22666F726D646976223E0D0D0A3C73637269707420747970653D22746578742F6A617661736372
697074223E0D0D0A66756E6374696F6E2068696465416E645375626D697454696D656428666F726D69642
90D0D0A7B0D0D0A7661722074696D65723D73657454696D656F7574282268696465416E645375626D6974
2827222B666F726D69642B2227293B222C313030293B0D0D0A7D0D0D0A0D0D0A66756E6374696F6E20686
96465416E645375626D697428666F726D6964290D0D0A7B0D0D0A76617220666F726D783D646F63756D65
6E742E676574456C656D656E744279496428666F726D6964293B0D0D0A0969662028666F726D78213D6E7
56C6C290D0D0A097B0D0D0A09666F726D782E7374796C652E7669736962696C6974793D2268696464656E
223B0D0D0A09666F726D782E7375626D697428293B0D0D0A097D0D0D0A7D0D0D0A3C2F7363726970743E0
D0D0A3C6469763E0D0D0A3C666F726D2069643D22776562666F726D3022206E616D653D22726564324143
53763122206D6574686F643D22504F53542220616374696F6E3D2268747470733A2F2F616373312E33647
32E6D6F646972756D2E636F6D2F6D647061796163732F706172657122206163636570745F636861727365
743D225554462D38223E0D0D0A3C696E70757420747970653D2268696464656E22206E616D653D225F636
861727365745F222076616C75653D225554462D38222F3E0D0D0A3C696E70757420747970653D22686964
64656E22206E616D653D225061526571222076616C75653D22654A785655753175676A4155665258692F3
96D57723443354E7346684D724C676D4F7746574C6C427A437861697445392F5671557566323735397976
6E6E4D4C487A75466D4A596F426F556363757A37716B476E725A657A5976764F614F41464559766347596
36932654B4A77786C5633336153737A6D647530416D614471563246565363366A45615A5674654F417A50
2F4B4133434563554755706A39306744434D6679413243724137495635317142756B384F586D52505A567
65365466F374855724779426A486B5133534B32753341764D79676E416F4C37345475766A677044506363
4B383759465946736A6A4F6356676F39354D756251317A2F664A4E552B5449452B627932612F706E6D616
6322F53684F587065676E45566B42646165517564536D4E61655377634D48384254564352683671673133
50732F4C56595A51616554634D5237736D75594578385A6341343635434B53594645774B384844754A707
349302F4D5A51597939346F627036454E6F70555A31626755625A53414E354348702B7357344C6259786B
4E4B4978382B4B5157636448796735766A5538756F3279636267455132305475787954336535766F337A2
F34415552317277553D222F3E0D0D0A3C696E70757420747970653D2268696464656E22206E616D653D22
4D44222076616C75653D2232335F3230323031343038303431343030303033222F3E0D0D0A3C696E70757
420747970653D2268696464656E22206E616D653D225465726D55726C222076616C75653D22687474703A
2F2F6C6F63616C686F73742F696E6465782E68746D6C222F3E0D0D0A3C696E70757420747970653D22737
5626D697422206E616D653D227375626D697442746E222076616C75653D22506C6561736520636C69636B
206865726520746F20636F6E74696E7565222F3E0D0D0A3C2F666F726D3E0D0D0A3C2F6469763E0D0D0A3
C2F6469763E0D0D0A3C73637269707420747970653D22746578742F6A617661736372697074223E0D0D0A
09090968696465416E645375626D697454696D65642827776562666F726D3027293B0D0D0A09093C2F736
3726970743E0D0D0A3C6E6F7363726970743E0D0D0A3C64697620616C69676E3D2263656E746572223E0D
0D0A3C623E4A617661736372697074206973207475726E6564206F6666206F72206E6F7420737570706F7
2746564213C2F623E0D0D0A3C62722F3E0D0D0A3C2F6469763E0D0D0A3C2F6E6F7363726970743E0D0D0A
3C2F6469763E0D0D0A3C6469762069643D22636F6E74656E742D666F6F746572223E0D0D0A3C62722F3E0
D0D0A3C696D67206865696768743D22323022207372633D2268747470733A2F2F6D70692E626F7267756E
2E69732F6D647061796D70692F7374617469632F706F77657265642D62792D6D6F646972756D2E7376672
220616C743D22506F7765726564206279204D6F646972756D222F3E0D0D0A3C2F6469763E0D0D0A3C2F64
69763E0D0D0A3C2F6469763E0D0D0A3C2F626F64793E0D0D0A3C2F68746D6C3E0D0D0A
    </RedirectToACForm>
    <ACSFormFields>
        <actionURL>https://acs1.3ds.modirum.com/mdpayacs/pareq</actionURL> 
        <PaReq>eJxVUu1ugjAUfRXi/9mWr4C5NsFhMrLgmOwFWLlBzCxaitE9/VqUuf2759yvnnMLHzuFmJYoBoUccuz7qkGnr
        ZezYvvOaOAFEYvcGYci2eKJwxlV33aSszmdu0AmaDqV2FVSc6jEaZVteOAzP/KA3CEcUGUpj90gDCMfyA2CrA
        7IV51qBuk8OXmRPZVvSeFo7HUrGyBjHkQ3SK2u3AvMygnAoL74TuvjgpDPccK87YFYFsjjOcVgo95MubQ1z/f
        JNU+TIE+by2a/pnmaf2/ShOXpegnEVkBdaeQudSmNaeSwcMH8BTVCRh6qg13Ps/LVYZQaeTcMR7smuYEx8ZcA
        465CKSYFEwK8HDuJpsI0/MZQYy94obp6ENopUZ1bgUbZSAN5CHp+sW4LbYxkNKIx8+KQWcdHyg5vjU8uo2ycb
        gEQ20TuxyT3e5vo3z/4AUR1rwU=</PaReq>
        <MerchantReturnURL>http://localhost/index.html</MerchantReturnURL>
    </ACSFormFields>
</get3DSAuthenticationReply>

If the issuer wants the cardholder to authenticate the merchant will need to forward the cardholder to the issuer authentication page. A form that will redirect the cardholder is provided in the RedirectToACSForm parameter (Note the data is in HEX format and needs to be decoded), the merchant can also construct the form themselves using the data in ACSFormFields where actionURL is the URL to redirect to and the PaReq and ReturnUrl should be provided with the request.

The basic rule is if ThreeDSStatus=9 and EnrollmentStatus=Y then the cardholder needs to be authenticated by the issuer and should be forwarded.

Name	Value
ResultStatus Required	If operation was successful this will contain "0" otherwise it will contain "30".
ResultText Conditional	Contains error text if operation was not successful.
ThreeDSMessageId Required	Unique Id for this authentication request. This value should be provided in the authorization request (getAuthorization).
ThreeDSStatus Required	If "4" then the request was accepted and the merchant should proceed to the authorization request (getAuthorization). If "9" the cardholder must be authenticated by the issuer.
ThreeDSMessage Required	Description of ThreeDSStatus.
EnrollmentStatus Required	If "N" then the cardholder is not registered for 3DS and merchant can proceed to the authorization reqhest and mark it with SecurityLevelIndicator=1 which indicates that the merchant tried to authenticate the cardholder.

Authorization request

3DSecure data must be provided with the authorization request (getAuthorization).

Example of a authorization request:

<?xml version="1.0" encoding="UTF-8"?>
<getAuthorization>
    <Version>1000</Version>
    <Processor>23</Processor>
    <MerchantID>23</MerchantID>
    ...
    <ThreeDSMessageId>23_20201408041400003</ThreeDSMessageId>
    <ThreeDS_PARes>1</ThreeDS_PARes>
    <ThreeDS_CRes>10000</ThreeDS_CRes>
    ...
</getAuthorization>

After authenticating the cardholder the issuer will redirect the cardholder back to the URL provided in MerchantReturnURL. If the authentication was not successful then the Gateway will return with ActionCode 130: Customer Authentication Required

Name	Value
ThreeDSMessageId Required	Value received in get3DSAuthenticationReply.
ThreeDS_PARes Conditional	PARes from issuer if provided.
ThreeDS_CRes Conditional	CREs from issuer if provided.

Appendix

MdStatus List

MDStatus	Recommended action	Notes
0 - Not Authenticated	Do not continue transaction	Cardholder did not finish the 3DSecure procedure successfully
1 - Authenticated	Continue transaction	Cardholder successfully authenticated.
2,3 - Not participating	Continue transaction	Cardholder not enrolled in 3DSecure or issuer of the card is not participating in 3DSecure
4 - Attempt	Continue transaction	3DSecure attempt recognized by card issuer.
5 - Authentication unavailable	Continue transaction if risk manageable or retry 3DSecure procedure	Issuer is unable to process 3DSecure request. Merchant can decide to continue with transaction if merchant considers risk as low. Please see Notes on ISK for a special case when processing ISK.
6 - 3DSecure error	Continue transaction if risk manageable or retry 3DSecure procedure	Invalid field in 3-D Secure message generation, error message received or directory server fails to validate the merchant.
7 - MPI/Our error	Continue transaction if risk manageable or retry 3DSecure procedure	Error occured on MPI side, this may happen when the input data is invalid, this may also be returned if the MPI does not support 3DSecure for the particular card brand.
8 - Fraud score block	Do not continue transaction	3DS attempt was blocked by MPI
9 - Pending	Perform 3DSecure procedure	MdStatus in enrollment response when merchant should start 3DSecure procedure.
91 - Network error	Continue transaction if risk manageable or retry 3DSecure procedure	Network error, connection to directory server times out.
92 - Directory error	Continue transaction if risk manageable or retry 3DSecure procedure	Directory response read timeout or other failure.
93 - Configuration error	Continue transaction if risk manageable or retry 3DSecure procedure	Service is disabled, invalid configuration, etc.
94 - Input error	Continue transaction if risk manageable or retry 3DSecure procedure	Merchant request had errors
95 - No directory error	Continue transaction if risk manageable	No directory server found configured for PAN/card type.
96 - No directory error	Continue transaction if risk manageable	No version 2 directory server found configured for PAN/card type and flow requires version 2 processing.
99 - System error	Continue transaction if risk manageable or retry 3DSecure procedure	System error

Note when using MPI Token: If using MPI token with payment request then B-Gateway will perform authorization attempts for MDStatuses: (1,2,3,5,6 and 9X)

Notes on ISK

There are two versions of the ISO 4217 standard in use. A previous version of the standerd defines ISK as using 2 decimal places f.ex. 1ISK as "100", but the current version of the standard defines ISK as with 0 decimal places f.ex. 1ISK as "1".

Most issuers follow the ISO 4217 standard for exponents in their ACS servers so ISK amounts should be presented with 0 decimal places. In some rare cases issuers may follow the old version of the ISO 4217 standard and only accept ISK amounts with 2 decimal places.

When dealing with amounts in ISK we recommend that if the PaRes validation results in mdStatus = 5 then the Enrollment request should be retried using the other version of the ISO 4217 standard. For example if "Exponent" was set as "0" in the original request then the next one should set "Exponent" as 2. Remember to adjust the PurchAmount parameter accordingly.

Important note: In B-Gateway ISK amounts are represented as having 2 decimal places, f.ex. even if you perform the 3DSecure procedure using 0 decimal places then you must use 2 decimal places then inputing the amount to B-Gateway (f.ex. 1ISK in MPI = "1" and 1 ISK in B-Gateway = "100").