Sends the authentication request to the directory server.
public func sendAuthRequest() throws -> Void
SendAuthRequest begins the 3-D Secure transaction flow by sending an authentication request to the DirectoryServerURL.
After calling this method, check TransactionStatus to determine if the cardholder is authenticated (frictionless flow) or further cardholder interaction is required to complete the authentication (challenge flow).
Prior to calling SendAuthRequest, data must to be collected to facilitate fraud checks by the ACS. The following properties are applicable for both app-based and browser-based flows:
- AcquirerBIN (required)
- AcquirerMerchantId (required)
- CardholderName (required)
- CardNumber (required)
- DirectoryServerURL (required)
- MerchantCategoryCode (required)
- MerchantCountryCode (required)
- MerchantName (required)
- PurchaseAmount (required)
- PurchaseDate (required)
- RequestorId (required)
- RequestorName (required)
- RequestorURL (required)
- ResultsURL (required)
In the app-based flow, device specific information is prepared by the 3DS SDK on the customer's device. This is transmitted to the 3DS Server class via a secure channel, the specifics of which are outside the scope of the classs. Set ClientAuthRequest to this data prepared by the 3DS SDK.
If a CardRangeMethodURL has been specified by the ACS for the card number, the URL must be loaded in the cardholder's browser to allow the ACS to collect additional browser information for risk-based decision making. See the GetMethodData for further details.
Once the method URL invocation is complete, the authentication request may be sent. If the method URL invocation failed, set MethodCompletionIndicator to N before calling SendAuthRequest.
The following additional properties are applicable in browser-based flow:
- NotificationURL (required)
- BrowserAcceptHeader (required)
- BrowserLanguage (required)
- BrowserScreenHeight (required)
- BrowserScreenWidth (required)
- BrowserTimeZone (required)
- BrowserUserAgent (required)
After calling this method the TransactionStatus property holds the result. Possible values are:
|C||Cardholder challenge required|
|A||Not authenticated, but a proof of authentication attempt was generated in AuthenticationValue|
|U||Not authenticated due to technical or other issue|
|R||Not authenticated because the issuer is rejecting authentication|
|D||Challenge required; decoupled authentication confirmed|
|I||Informational only; 3DS Requestor challenge preference acknowledged|
If the transaction is authenticated (Y or A), no further steps are required. The flow is considered frictionless and the 3-D Secure processing is complete. If processing a payment, the AuthenticationValue and AuthenticationECI values can be included as proof of 3-D Secure authentication.
If the transaction requires a cardholder challenge (C or D), further steps are required.
If the transaction is not authenticated, TransactionStatusReason may contain details about the reason.
The following properties are applicable after calling this method:
- ACSURL (if challenge required)
- ACSChallengeMandatedIndicator (if challenge required)
- AuthenticationType (if challenge required)
Response Handling - App-Based Flow
After calling this method, ClientAuthResponse is populated with data to be transmitted back to the 3DS SDK. If a challenge is required, the ClientAuthResponse data is used by the 3DS SDK to start when initiating the challenge process.
The 3DS Server is responsible for indicating to the 3DS SDK the results of the SendAuthRequest process, and whether or not a challenge is required. Exactly how this is done is outside the scope of the classs themselves. The response to the 3DS SDK over the secure channel should include information on what to do next.
Response Handling - Browser-Based Flow
If TransactionStatus is C, then additional steps are required to complete the authentication. The GetChallengeRequest method should be called next to obtain data to be sent to the ACSURL in an authentication window in the customer's browser. Once authentication is complete, the ACS will post the results to the ResultsURL value that was specified when calling SendAuthRequest.
See the GetChallengeRequest method for more details.
If TransactionStatus is D, then decoupled authentication has been accepted by the ACS. DecoupledConfirmationIndicator will have a value of Y as well. Authentication will happen outside of the 3-D Secure flow and, when complete, the ACS will post the results to the ResultsURL that was specified when calling SendAuthRequest.
The DecoupledTimeRemaining value, which is calculated based on the DecoupledMaxTimeout value sent in the initial authentication request, can be checked to see the amount of time remaining before decoupled authentication must be completed. If the ACS does not post the results before this value runs out, it can be assumed that decoupled authentication was not successful.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)