Server Class

Properties   Methods   Events   Config Settings   Errors  

The Server class provides support for the 3DS Server role as defined in the EMV® 3-D Secure (EMV 3DS) specification.

Syntax

Server

Remarks

This class is designed to be used in a web server, or in a process used by a web server to facilitate EMV® 3-D Secure (EMV 3DS) functionality. The class is used primarily for the browser-based flow, but also for some operations in the app-based flow as detailed in other parts of the documentation.

Connecting with SSL Client Authentication

Many directory servers require client authentication via a client certificate. The SSLCert* properties are used to load the SSL client certificate. In order to properly authenticate to the directory server the entire certificate chain must be presented to the directory server during the initial SSL handshake. The sections below describe options for making sure the CA chain is included.

Option 1: PFX With CA Certs

The first option is to specify a PFX file which includes both the client certificate, and CA certificates. In this case the class will read the CA certificates from the PFX file and include them in the request.

Option 2: SSLCACerts Configuration Setting

Another option is to specify the CA certificates separately from the client certificate. To do this the SSLCACerts configuration setting may be set to a CrLf separated list of CA certificates. For instance:

PHP Example

$ca_int = <<<EOT -----BEGIN CERTIFICATE----- MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw ... eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w F0I1XhM+pKj7FjDr+XNj -----END CERTIFICATE----- EOT; $ca_root = <<<EOT -----BEGIN CERTIFICATE----- MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp ... 8ECs48NRSON+/Pqm9Hxw1H3/yz2qLG4zTI7xJVDESZGEXadLwCJXD6OReX2F/BtU d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA -----END CERTIFICATE----- EOT; $server->doConfig('SSLCACerts=' . $ca_int . '\n' . $ca_root);

Option 3: CA Certs in Windows Store

When running on Windows the CA certificates will also be included in the request if they are present in the Personal store of the user under which the application is running.

Card Ranges

The application using the 3DS Server class should maintain a cache of card range information that can be queried when a transaction is initiated. The RequestCardRanges method will retrieve card range information to be cached.

RequestCardRanges requests card ranges and additional information from the directory server.

When a transaction is initiated, the first step that should be taken is to find information about the card range to which the card number belongs. This includes the protocol version(s) supported by the ACS and DS, and if one exists, any corresponding Method URL (used in the browser flow).

Results of this method should be cached in order to quickly look up information when processing transactions. It is recommended to call this method once every 24 hours at a minimum, and once per hour as a maximum to refresh the cache. The class will not cache the returned values; it is up to the user to cache these values in an appropriate location.

The first time this method is called, SerialNumber will be empty, indicating that all results should be returned. This is an offset the server will use to return only new updates to the card ranges (if any) since the last request. The SerialNumber will be populated after this method returns, and this value should be saved to be used in subsequent calls.

When a response is received, the card ranges will be made available via the component events and properties.

When MessageVersion is set to 2.3.1, the CardRangeData event will fire for each card range data object received, and the Ranges and ACSProtocolInfos properties will be populated to be accessed within the event handler. Optionally, the DS may return a list of URLs that the 3DS Server can use for communication with the DS. If present, these will be available via both the DSURL event and the DSURLs property.

When MessageVersion is set to 2.2.0 or 2.1.0, the CardRange event will fire for each card range that is returned, and the results will also be held in the CardRanges property.

The following properties are applicable when calling this method:

• DirectoryServerURL (required)
• SerialNumber
• ServerTransactionId
• ServerOperatorId
• EnableDownloadCardRangeDataFile (2.3.1 only)

The following properties are populated after calling this method:

• CardRanges
• DSStartProtocolVersion
• DSEndProtocolVersion
• SerialNumber
• DSTransactionId
• ResendRequestCardRanges

When using MessageVersion 2.2.0 or 2.3.1, the returned ranges may include ACS Information Indicators. These are used to indicate additional functionality supported by the ACS for the card range(s). For 2.2.0, a ACSInformationIndicator field is exposed in both CardRanges collection and CardRange event. In version 2.3.1, this information is availalbe in the ACSProtocolInfos collection via the Indicator field. Possible values are:

• 01 - Authentication Available at ACS
• 02 - Attempts Supported by ACS or DS
• 03 - Decoupled Authentication Supported
• 04 - Whitelisting Supported
• 05 - Device Binding Supported (2.3.1 only)
• 06 - WebAuthn Authentication Supported (2.3.1 only)
• 07 - SPC Authentication Supported (2.3.1 only)
• 08 - Transaction Risk Analysis Exemption Supported (2.3.1 only)
• 09 - Trust List Exemption Supported (2.3.1 only)
• 10 - Low Value Exemption Supported (2.3.1 only)
• 11 - Secure Corporate Payments Exemption Supported (2.3.1 only)
• 80-99 - Reserved for DS Use

If an error is identified with the card range data received from the directory server when calling the RequestCardRanges method, the ResendRequestCardRanges configuration setting will be true, indicating that the request should be resent. When resending, if SerialNumber was specified for the initial request, it should be set to an empty string before calling RequestCardRanges again. Otherwise, the request can be sent without the serial number again, but the server may respond with an error due to multiple requests within an hour.

Note that retrieving card ranges can consume a lot of memory, especially when retrieving the initial set of ranges. The StoreCardRangeData and UseJsonDOM configuration settings can be set to help minimize the amount of memory used. A CardRangeTempPath setting can also be used to specify a temporary path to which the PRes packet will be temporarily written prior to parsing.

When using MessageVersion 2.3.1, if UseJsonDOM is false, the card ranges will need to be cached and processed after the RequestCardRanges method returns. The card ranges would then need to be processed in the order indicated by the CardRangeRecordsReadOrder configuration setting. A check will also need to be made for overlap of ranges. If issue(s) are found, the ReportCardRangeError configuration setting should be used to report the error to the directory server.

Method Invocation

The GetMethodData method prepares data to be transmitted to the ACS via the cardholder's browser.

When a transaction begins, the card range cache should be queried to find details about the card range to which the card number belongs. If a MethodURL is defined for the card range, this method should be used to prepare data to be sent via the cardholder's browser to the MethodURL.

If the MethodURL is not set for the specified card range, set MethodCompletionIndicator to U before calling SendAuthRequest.

The following properties are applicable when calling this method:

• MethodNotificationURL (required)

This method returns a string which contains encoded data to be sent to the ACS. This includes ServerTransactionId and MethodNotificationURL. After calling this method, the returned string can be transmitted to the ACS via the cardholder's browser.

As per the EMVCo specification, create a hidden iframe in the browser and send a form with the field name threeDSMethodData containing the return value from this method and post the form to the MethodURL.

The ACS will record information about the customer's environment and then POST back to the MethodNotificationURL. The page at this URL should expect a form variable with the name threeDSMethodData which will contain the original ServerTransactionId value in order to match the response with the request. The form variable value will be base64url encoded and may be passed directly to the CheckResponse method. The class will decode and parse the received value and populate ServerTransactionId with the value from the received data.

If the response from the ACS is not received within 10 seconds, set MethodCompletionIndicator to N before calling SendAuthRequest.

Sending the Authentication Request

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)
• MessageVersion (required)
• PurchaseAmount (required)
• PurchaseDate (required)
• RequestorId (required)
• RequestorName (required)
• RequestorURL (required)
• ResultsURL (required)
• AccountType
• AuthenticationIndicator
• BillingAddress*
• CardholderEmail
• CardholderHomePhone
• CardholderMobilePhone
• CardholderWorkPhone
• DecoupledMaxTimeout
• DecoupledRequestIndicator
• DeviceChannel
• MessageCategory
• PurchaseCurrency
• PurchaseExponent
• ServerOperatorId
• ServerTransactionId
• ShippingAddress*
• ThreeRIIndicator

App-Based Flow

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.

Browser-Based Flow

Before calling this method, first check the cached card-range data to determine if a MethodURL has been set by the ACS. Card range data may be retrieved by calling RequestCardRanges.

If no MethodURL is present for the given card, set MethodCompletionIndicator to U.

If a MethodURL 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 in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• BrowserScreenWidth (required in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• BrowserTimeZone (required in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• BrowserUserAgent (required)
• BrowserIPAddress (conditional)
• BrowserJavaEnabledVal (required in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• BrowserJavaScriptEnabledVal (not valid in 2.1.0, required in 2.2.0 and 2.3.1)
• BrowserScreenColorDepth (required in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• AcceptLanguage (2.3.1 only)
• AcquirerCountryCode (2.3.1 only)

Response Handling

After calling this method the TransactionStatus property holds the result. Possible values are:

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, D or S), 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:

• AuthenticationECI
• AuthenticationValue
• TransactionStatus
• TransactionStatusReason
• CardholderInformation
• ACSURL (if challenge required)
• ACSChallengeMandatedIndicator (if challenge required)
• AuthenticationType (if challenge required)
• DecoupledConfirmationIndicator

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.

Note: The TransactionStatus is also populated in the 3DS Server class and may be inspected prior to transmitting ClientAuthResponse back to the 3DS SDK.

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.

SPC-Based Authentication

SPC (Secure Payment Confirmation) provides a method to perform a challenge using preestablished FIDO credentials when using a Browser. The SPC authentication can be initiated by the 3DS Requestor via an extra AReq/ARes message pair or by the ACS via a standard Browser Challenge Flow.

For an SPC authentication to execute correctly, the following prerequisites apply:

1. The ACS has an enrolled FIDO authenticator on the device for this Cardholder.
2. The 3DS Requestor and/or the ACS have detected that the Cardholder Browser supports the related SPC APIs (allow="payment *; publickey-credentialsget *"). For the ACS, this information can be obtained via the Browser User Agent data element or via data obtained via the 3DS Method.

SPC-based authentication can be enabled with the following additions:

Prior to sending the initial authentication request packet (AReq) using the SendAuthRequest method, the ThreeDSRequestorSpcSupport configuration setting should be set to True to indicate that SPC is supported by the 3DS Requestor.

If SPC is accepted by the ACS, the resulting TransactionStatus should be S. The response will also contain a list of enrolled FIDO (WebAuthn) credentials associated with the cardholder, and SPC transaction data. This data is available in the following configuration settings:

• WebAuthnCredentialListCount
• WebAuthnCredentialListWebAuthnCredential
• WebAuthnCredentialListRelyingPartyId
• SPCTransactionAdditionalData
• SPCTransactionChallenge
• SPCTransactionChallengeInfoText
• SPCTransactionCurrency
• SPCTransactionDisplayName
• SPCTransactionIcon
• SPCTransactionIssuerImage
• SPCTransactionIssuerImageDark
• SPCTransactionIssuerImageMonochrome
• SPCTransactionPayeeName
• SPCTransactionPayeeOrigin
• SPCTransactionPSImage
• SPCTransactionPSImageDark
• SPCTransactionPSImageMonochrome
• SPCTransactionTimeout
• SPCTransactionValue

This information is relayed to the 3DS Requestor implementation, and the 3DS Requestor invokes the SPC authentication (SPC API) against the WebAuthn Credential list. The cardholder authenticates using the FIDO authenticator on their device, and the 3DS Requestor retrieves the Assertion Data from the SPC API call.

The 3DS Server is then configured to includes this FIDO Assertion Data is then included in a new authentication request by setting the ReqAuthData[Index] and a ReqAuthMethod[Index] of 09. If the AuthenticationInformation value was saved earlier, it can be set via the same configuration setting. If the 3DS Requestor encounters an error during SPC API invokation, this can be indicated using the SPCIncompletionIndicator.

The SendAuthRequest method should then be called again to transmit this data to the ACS (by way of the DS) in a second AReq.

When SendAuthRequest returns, the 3DS Server proceed the same as the regular browser-based flow when the ARes is returned.

When SPC authentication is to be performed, the authenticaton must be completed within 9 minutes. The component will automatically start an internal timer that can be checked using the CheckSPCTimeout configuration setting. This will return the number of seconds left for SPC authentication to complete. If the time has expired before receiving the Assertion Data from the 3DS Requestor, checking this configuration setting will cause the component to automatically send the second AReq message with an SPCIncompletionIndicator value of 03, indicating that SPC authentication timed out.

Note that SPC-based authentication is only available when a MessageVersion of 2.3.1 is used.

Challenge Interaction

If the TransactionStatus is C, a challenge is required.

The GetChallengeRequest method is used to build the Challenge Request (CReq) which will be sent in a form post to the ACSURL property via the cardholder browser.

An iframe should be created in the cardholder's browser, which will be used to send the challenge request and allow the cardholder and ACS to interact directly.

The size of the challenge window (iframe) may be any of the sizes listed in ChallengeWindowSize. Before calling this method set ChallengeWindowSize to the appropriate value to let the ACS know the size of the window on the cardholder's browser.

Calling this method will return a string which should be placed in a creq form variable.

The SessionData setting may also be set with any data that may be helpful to continue processing the transaction after the final challenge response is received at the NotificationURL. To prepare the session data for submission, query EncodedSessionData. The encoded string may then be placed in the threeDSSessionData form variable.

Note: The maximum length of the threeDSSessionData form variable, after being encoded, is 1024 bytes.

Example Form

Response Handling

Once the challenge has been completed by the cardholder, the directory server will post a Results Request (RReq) to the ResultsURL specified when calling SendAuthRequest. See CheckResponse and GetResultsResponse for more details.

The ACS will also post the Challenge Response to the NotificationURL specified when calling SendAuthRequest. This post contains data which may be parsed to verify the challenge results. See CheckResponse for more details.

Response Handling

After a challenge is complete, the Directory Server and ACS will POST data back to the web server for additional processing. CheckResponse parses a variety of messages that are sent to the Server as part of the authentication process.

The following messages can be parsed using this method:

• The threeDSMethodData form variables received at the MethodNotificationURL
• The Results Request (RReq) message received at the ResultsURL
• The cres form variables received at the NotificationURL
• The Operation Request Message (OReq) sent from a DS.

When calling the method, pass the message to be parsed as the Response parameter. The properties which are populated after calling this method vary depending on the type of message being parsed. See below for additional information.

Method Data from MethodNotificationURL

After calling GetMethodData, a request is made to the MethodURL. After this, the ACS will make a POST to MethodNotificationURL to inform the requestor of completion. Retrieve the threeDSMethodData form variable value that was POSTed and pass it to this method. After calling this method, the following properties are populated:

• ServerTransactionId

Results Request message from ResultsURL

When a challenge is completed for both app-based and browser-based flows, a POST is made to the ResultsURL with a Results Request message.

Prior to checking this RReq message, the ServerTransactionId can be extracted using the ExtractRReqServerTransactionId configuration setting. This value can then be used to look up details on the transaction that were saved prior to starting the challenge process, including the messageVersion which must be set via the MessageVersion property prior to passing the RReq message to the CheckResponse method.

Pass the body of the HTTP request received at ResultsURL to this method. This contains information about the results, and asks for a Results Response to be sent back containing the ResultsStatus.

After calling this method, the following properties are populated:

• AuthenticationECI
• TransactionStatus
• TransactionStatusReason
• ChallengeCancellationIndicator
• AuthenticationType
• AuthenticationValue

To respond to the POST, set ResultsStatus to the appropriate value and call GetResultsResponse to build a response message to be sent back to the directory server. Use the value from GetResultsResponse in the application as the body of the HTTP response. Set the Content-Type header to application/JSON; charset=utf-8

If TransactionStatus is D and TransactionStatusReason is 29 or 30, this indicates that decoupled authentication should now be performed. When building the Results Response, a ResultsStatus value of 04 should be used. Then, within 60 seconds, a new 3RI authentication must be started with the following field requirements:

• ThreeRIIndicator set to 19, indicating Decoupled Authentication Fallback
• DecoupledRequestIndicator set to Y
• AuthenticationInformation set with threeDSReqPriorRef set to the ACS Transaction ID and threeDSReqPriorAuthMethod set to 02 (Cardholder challenge occurred by ACS).

Final Challenge Response from NotificationURL

In a browser-based flow, the challenge takes place directly between the cardholder and the ACS in a separate iframe or window. The ACS will POST the final challenge response to the NotificationURL after the challenge is complete. Retrieve the cres form variable value from the POST data and pass it to CheckResponse. After calling this method the following properties are populated:

• ServerTransactionId
• TransactionStatus

In addition to the cres variable, a threeDSSessionData variable will be present if SessionData was set before calling GetChallengeRequest. The threeDSSessionData value POSTed to NotificationURL may be passed to EncodedSessionData. Query SessionData to get the decoded session data.

Operation Request Message (OReq)

OReq messages are used to communicate operational information from a DS to the 3DS Server. This message is not part of the 3-D Secure authentication flow.

When an OReq message is received, CheckResponse should be called to validate the message. There may be more than one OReq message sent in a sequence, and CheckResponse should be called for each. The current instance of the Server object can be cached for the duration of the OReq sequence until the final OReq is received. The Operation.SequenceNumber should also be set prior to calling CheckResponse. The component will verify the sequence number of the received OReq to ensure it's not out of sequence.

After calling this method, details are made available in Operation.

If any OReq data element fails validation, Operation.MessageStatus will be set to "02". If the OReq is valid, Operation.MessageStatus will be empty.

If the OReq is valid, determine if the final OReq has been received (Operation.SequenceNumber equals Operation.SequenceTotal). If these values match, the final OReq in the sequence has been received, and GetOperationResponse can be used to generate the ORes message.

For valid OReq messages that are not the final OReq in the sequence, the response should be HTTP Status 200 (OK) with an empty HTTP body.

Logging Notes

Logging in the component is handled through the Log event. This will fire anytime a message is built or a response is parsed, including error messages.

When the Log event is fired, the message in question is made available via the Message event parameter. Properties such as EphemeralKey and DeviceParams are also available when they are gathered by the Client. The other event arguments are LogType and LogLevel:

The LogType parameter indicates the type of the log entry. Possible values are:

• "Info"
• "RequestHeaders"
• "ResponseHeaders"
• "RequestBody"
• "ResponseBody"
• "ProxyRequest"
• "ProxyResponse"
• "FirewallRequest"
• "FirewallResponse"
• "AReq"
• "ARes"
• "CReq"
• "CRes"
• "RReq"
• "RRes"
• "PReq"
• "PRes"
• "Erro"
• "EphemeralKey"
• "DeviceParams"

It is recommended to output all messages raised in this event to a file for record keeping purposes, or for later debugging issues that may have come up.

The Server and Client components also have DataPacketIn and DataPacketOut events that fire anytime a data packet is received or sent, respectively. The entire data packet is then accessible in the DataPacket event parameter. For encrypted packets, this would contain the full encrypted data. This parameter may be inspected for advanced troubleshooting.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

AcceptLanguage Property (Server Class)

HTTP accept language header value sent from the cardholder's browser.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAcceptLanguage();
int SetAcceptLanguage(const char* lpszAcceptLanguage);

Unicode (Windows)
LPWSTR GetAcceptLanguage();
INT SetAcceptLanguage(LPCWSTR lpszAcceptLanguage);

char* ipworks3ds_server_getacceptlanguage(void* lpObj);
int ipworks3ds_server_setacceptlanguage(void* lpObj, const char* lpszAcceptLanguage);

QString GetAcceptLanguage();
int SetAcceptLanguage(QString qsAcceptLanguage);

Default Value

""

Remarks

Value representing the browser language preference present in the HTTP header, as defined in IETF BCP 47.

This property accepts a comma separated list of language tags. For example: en,fr-FR

Valid for MessageVersion 2.3.1 only.

Data Type

String

AccountType Property (Server Class)

Indicates the type of account.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAccountType();
int SetAccountType(const char* lpszAccountType);

Unicode (Windows)
LPWSTR GetAccountType();
INT SetAccountType(LPCWSTR lpszAccountType);

char* ipworks3ds_server_getaccounttype(void* lpObj);
int ipworks3ds_server_setaccounttype(void* lpObj, const char* lpszAccountType);

QString GetAccountType();
int SetAccountType(QString qsAccountType);

Default Value

""

Remarks

This is included in the Authentication Request Message (AReq) sent to the directory server. Required if the 3-D Secure Requestor is asking the cardholder which account type they are using before making the purchase. Required in some markets (for example, for merchants in Brazil). Otherwise, this is optional.

Valid values are as follows:

Data Type

String

AcquirerBIN Property (Server Class)

Acquiring institution identification code.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAcquirerBIN();
int SetAcquirerBIN(const char* lpszAcquirerBIN);

Unicode (Windows)
LPWSTR GetAcquirerBIN();
INT SetAcquirerBIN(LPCWSTR lpszAcquirerBIN);

char* ipworks3ds_server_getacquirerbin(void* lpObj);
int ipworks3ds_server_setacquirerbin(void* lpObj, const char* lpszAcquirerBIN);

QString GetAcquirerBIN();
int SetAcquirerBIN(QString qsAcquirerBIN);

Default Value

""

Remarks

This value correlates to the Acquirer BIN as defined by each payment system or directory server. This field is required to be set for payment authentication.

Data Type

String

AcquirerCountryCode Property (Server Class)

Acquirer Country Code.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAcquirerCountryCode();
int SetAcquirerCountryCode(const char* lpszAcquirerCountryCode);

Unicode (Windows)
LPWSTR GetAcquirerCountryCode();
INT SetAcquirerCountryCode(LPCWSTR lpszAcquirerCountryCode);

char* ipworks3ds_server_getacquirercountrycode(void* lpObj);
int ipworks3ds_server_setacquirercountrycode(void* lpObj, const char* lpszAcquirerCountryCode);

QString GetAcquirerCountryCode();
int SetAcquirerCountryCode(QString qsAcquirerCountryCode);

Default Value

""

Remarks

The code of the country where the acquiring institution is located (in accordance with ISO 3166).

This value should be formatted as a ISO 3166-1 numeric three-digit country code.

Valid for MessageVersion 2.3.1 only.

Data Type

String

AcquirerMerchantId Property (Server Class)

Acquirer-assigned merchant identifier.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAcquirerMerchantId();
int SetAcquirerMerchantId(const char* lpszAcquirerMerchantId);

Unicode (Windows)
LPWSTR GetAcquirerMerchantId();
INT SetAcquirerMerchantId(LPCWSTR lpszAcquirerMerchantId);

char* ipworks3ds_server_getacquirermerchantid(void* lpObj);
int ipworks3ds_server_setacquirermerchantid(void* lpObj, const char* lpszAcquirerMerchantId);

QString GetAcquirerMerchantId();
int SetAcquirerMerchantId(QString qsAcquirerMerchantId);

Default Value

""

Remarks

This field contains the merchant identifier assigned by the acquirer. The merchant id is required to be set for payment authentication.

Data Type

String

ACSProtocolInfos Property (Server Class)

A collection of protocol versions and other associated information supported by the ACS for a card range.

Syntax

• C++
• C
• Qt

IPWorks3DSList<IPWorks3DSACSProtocolInfo>* GetACSProtocolInfos();

int ipworks3ds_server_getacsprotocolinfocount(void* lpObj);

char* ipworks3ds_server_getacsprotocolinfoindicator(void* lpObj, int acsprotocolinfoindex);

char* ipworks3ds_server_getacsprotocolinfoprotocolversion(void* lpObj, int acsprotocolinfoindex);

char* ipworks3ds_server_getacsprotocolinfosupportedmsgext(void* lpObj, int acsprotocolinfoindex);

char* ipworks3ds_server_getacsprotocolinfothreedsmethodurl(void* lpObj, int acsprotocolinfoindex);

int GetACSProtocolInfoCount();

QString GetACSProtocolInfoIndicator(int iACSProtocolInfoIndex);

QString GetACSProtocolInfoProtocolVersion(int iACSProtocolInfoIndex);

QString GetACSProtocolInfoSupportedMsgExt(int iACSProtocolInfoIndex);

QString GetACSProtocolInfoThreeDSMethodURL(int iACSProtocolInfoIndex);

Remarks

A list of information returned when retrieving card ranges using the RequestCardRanges method.

Each card range will include information including the Protocol Version supported by the ACS for the card range, the 3DS Method URL, supported extensions, and other additional information from the ACS.

This field is only applicable when MessageVersion is 2.3.1.

This property is read-only and not available at design time.

Data Type

IPWorks3DSACSProtocolInfo

ACSURL Property (Server Class)

URL of the ACS to be used for the challenge.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetACSURL();
int SetACSURL(const char* lpszACSURL);

Unicode (Windows)
LPWSTR GetACSURL();
INT SetACSURL(LPCWSTR lpszACSURL);

char* ipworks3ds_server_getacsurl(void* lpObj);
int ipworks3ds_server_setacsurl(void* lpObj, const char* lpszACSURL);

QString GetACSURL();
int SetACSURL(QString qsACSURL);

Default Value

""

Remarks

This field contains the fully qualified URL of the ACS to be used for the challenge. This will be populated after the call to SendAuthRequest method if the Authentication Response Message (ARes) indicates that a challenge is required.

Data Type

String

AuthenticationECI Property (Server Class)

Value to be passed in the authorization message.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAuthenticationECI();

Unicode (Windows)
LPWSTR GetAuthenticationECI();

char* ipworks3ds_server_getauthenticationeci(void* lpObj);

QString GetAuthenticationECI();

Default Value

""

Remarks

This property is determined by the Access Control Server (ACS), and is filled after the call to SendAuthRequest (for a frictionless flow), or when the Results Request Message (RReq) is parsed using CheckResponse (for a challenge flow).

This property contains the two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorization message. This value indicates to the processor that the customer data in the authorization message has been authenticated. The data contained within this property is only valid if the TransactionStatus is "Y" or "A".

This property is read-only.

Data Type

String

AuthenticationIndicator Property (Server Class)

3DS Requestor Authentication Indicator.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAuthenticationIndicator();
int SetAuthenticationIndicator(const char* lpszAuthenticationIndicator);

Unicode (Windows)
LPWSTR GetAuthenticationIndicator();
INT SetAuthenticationIndicator(LPCWSTR lpszAuthenticationIndicator);

char* ipworks3ds_server_getauthenticationindicator(void* lpObj);
int ipworks3ds_server_setauthenticationindicator(void* lpObj, const char* lpszAuthenticationIndicator);

QString GetAuthenticationIndicator();
int SetAuthenticationIndicator(QString qsAuthenticationIndicator);

Default Value

"01"

Remarks

Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handing an authentication request. Included in the Authorization Request Message (ARes) sent by the SendAuthRequest method. Possible values are:

Data Type

String

AuthenticationValue Property (Server Class)

Used to provide proof of authentication.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAuthenticationValue();

Unicode (Windows)
LPWSTR GetAuthenticationValue();

char* ipworks3ds_server_getauthenticationvalue(void* lpObj);

QString GetAuthenticationValue();

Default Value

""

Remarks

This property is determined by the Access Control Server (ACS), and is filled after the call to SendAuthRequest (for a frictionless flow), or when the Results Request Message (RReq) is parsed using CheckResponse (for a challenge flow).

This property will be valid if the TransactionStatus is "Y" or "A". The value may be used to provide proof of authentication.

This property is read-only.

Data Type

String

BillingAddress Property (Server Class)

The customer's billing address.

Syntax

• C++
• C
• Qt

IPWorks3DSAddressInfo* GetBillingAddress();
int SetBillingAddress(IPWorks3DSAddressInfo* val);

char* ipworks3ds_server_getbillingaddresscity(void* lpObj);
int ipworks3ds_server_setbillingaddresscity(void* lpObj, const char* lpszBillingAddressCity);

char* ipworks3ds_server_getbillingaddresscountry(void* lpObj);
int ipworks3ds_server_setbillingaddresscountry(void* lpObj, const char* lpszBillingAddressCountry);

char* ipworks3ds_server_getbillingaddressline1(void* lpObj);
int ipworks3ds_server_setbillingaddressline1(void* lpObj, const char* lpszBillingAddressLine1);

char* ipworks3ds_server_getbillingaddressline2(void* lpObj);
int ipworks3ds_server_setbillingaddressline2(void* lpObj, const char* lpszBillingAddressLine2);

char* ipworks3ds_server_getbillingaddressline3(void* lpObj);
int ipworks3ds_server_setbillingaddressline3(void* lpObj, const char* lpszBillingAddressLine3);

char* ipworks3ds_server_getbillingaddresspostalcode(void* lpObj);
int ipworks3ds_server_setbillingaddresspostalcode(void* lpObj, const char* lpszBillingAddressPostalCode);

char* ipworks3ds_server_getbillingaddressstate(void* lpObj);
int ipworks3ds_server_setbillingaddressstate(void* lpObj, const char* lpszBillingAddressState);

QString GetBillingAddressCity();
int SetBillingAddressCity(QString qsBillingAddressCity);

QString GetBillingAddressCountry();
int SetBillingAddressCountry(QString qsBillingAddressCountry);

QString GetBillingAddressLine1();
int SetBillingAddressLine1(QString qsBillingAddressLine1);

QString GetBillingAddressLine2();
int SetBillingAddressLine2(QString qsBillingAddressLine2);

QString GetBillingAddressLine3();
int SetBillingAddressLine3(QString qsBillingAddressLine3);

QString GetBillingAddressPostalCode();
int SetBillingAddressPostalCode(QString qsBillingAddressPostalCode);

QString GetBillingAddressState();
int SetBillingAddressState(QString qsBillingAddressState);

Remarks

This property specifies details about the customer's billing address. This should be set before calling SendAuthRequest.

Data Type

IPWorks3DSAddressInfo

BrowserAcceptHeader Property (Server Class)

HTTP accept header sent from the cardholder's browser.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetBrowserAcceptHeader();
int SetBrowserAcceptHeader(const char* lpszBrowserAcceptHeader);

Unicode (Windows)
LPWSTR GetBrowserAcceptHeader();
INT SetBrowserAcceptHeader(LPCWSTR lpszBrowserAcceptHeader);

char* ipworks3ds_server_getbrowseracceptheader(void* lpObj);
int ipworks3ds_server_setbrowseracceptheader(void* lpObj, const char* lpszBrowserAcceptHeader);

QString GetBrowserAcceptHeader();
int SetBrowserAcceptHeader(QString qsBrowserAcceptHeader);

Default Value

""

Remarks

This field contains the exact content of the HTTP accept header as sent to the merchant from the cardholder's user agent. This field is required only if the cardholder's user agent supplied a value.

Data Type

String

BrowserIPAddress Property (Server Class)

IP address of the cardholder's browser.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetBrowserIPAddress();
int SetBrowserIPAddress(const char* lpszBrowserIPAddress);

Unicode (Windows)
LPWSTR GetBrowserIPAddress();
INT SetBrowserIPAddress(LPCWSTR lpszBrowserIPAddress);

char* ipworks3ds_server_getbrowseripaddress(void* lpObj);
int ipworks3ds_server_setbrowseripaddress(void* lpObj, const char* lpszBrowserIPAddress);

QString GetBrowserIPAddress();
int SetBrowserIPAddress(QString qsBrowserIPAddress);

Default Value

""

Remarks

This field contains the IP address of the cardholder's browser as returned by the HTTP headers.

Data Type

String

BrowserJavaEnabledVal Property (Server Class)

Ability of the cardholder's browser to execute Java.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetBrowserJavaEnabledVal();
int SetBrowserJavaEnabledVal(int iBrowserJavaEnabledVal);

Unicode (Windows)
INT GetBrowserJavaEnabledVal();
INT SetBrowserJavaEnabledVal(INT iBrowserJavaEnabledVal);

JE_NOT_PRESENT(0), 
JE_TRUE(1), 
JE_FALSE(2)

int ipworks3ds_server_getbrowserjavaenabledval(void* lpObj);
int ipworks3ds_server_setbrowserjavaenabledval(void* lpObj, int iBrowserJavaEnabledVal);

int GetBrowserJavaEnabledVal();
int SetBrowserJavaEnabledVal(int iBrowserJavaEnabledVal);

Default Value

0

Remarks

This field contains a value representing the ability of the cardholder's browser to execute Java.

Possible values are as follows:

Data Type

Integer

BrowserJavaScriptEnabledVal Property (Server Class)

Ability of the cardholder's browser to execute JavaScript.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetBrowserJavaScriptEnabledVal();
int SetBrowserJavaScriptEnabledVal(int iBrowserJavaScriptEnabledVal);

Unicode (Windows)
INT GetBrowserJavaScriptEnabledVal();
INT SetBrowserJavaScriptEnabledVal(INT iBrowserJavaScriptEnabledVal);

BJE_NOT_PRESENT(0), 
BJE_TRUE(1), 
BJE_FALSE(2)

int ipworks3ds_server_getbrowserjavascriptenabledval(void* lpObj);
int ipworks3ds_server_setbrowserjavascriptenabledval(void* lpObj, int iBrowserJavaScriptEnabledVal);

int GetBrowserJavaScriptEnabledVal();
int SetBrowserJavaScriptEnabledVal(int iBrowserJavaScriptEnabledVal);

Default Value

0

Remarks

This field contains a value representing the ability of the cardholder's browser to execute JavaScript.

Possible values are as follows:

Data Type

Integer

BrowserLanguage Property (Server Class)

The cardholder's browser language.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetBrowserLanguage();
int SetBrowserLanguage(const char* lpszBrowserLanguage);

Unicode (Windows)
LPWSTR GetBrowserLanguage();
INT SetBrowserLanguage(LPCWSTR lpszBrowserLanguage);

char* ipworks3ds_server_getbrowserlanguage(void* lpObj);
int ipworks3ds_server_setbrowserlanguage(void* lpObj, const char* lpszBrowserLanguage);

QString GetBrowserLanguage();
int SetBrowserLanguage(QString qsBrowserLanguage);

Default Value

""

Remarks

This field contains the cardholder's browser language as defined in IETF BCP 47.

Data Type

String

BrowserScreenColorDepth Property (Server Class)

The screen color depth of the cardholder's browser.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetBrowserScreenColorDepth();
int SetBrowserScreenColorDepth(const char* lpszBrowserScreenColorDepth);

Unicode (Windows)
LPWSTR GetBrowserScreenColorDepth();
INT SetBrowserScreenColorDepth(LPCWSTR lpszBrowserScreenColorDepth);

char* ipworks3ds_server_getbrowserscreencolordepth(void* lpObj);
int ipworks3ds_server_setbrowserscreencolordepth(void* lpObj, const char* lpszBrowserScreenColorDepth);

QString GetBrowserScreenColorDepth();
int SetBrowserScreenColorDepth(QString qsBrowserScreenColorDepth);

Default Value

""

Remarks

This field contains a value representing the bit depth of the color palette, in bits per pixel, for displaying images.

For MessageVersion 2.1.0, this field is required. If BrowserJavaEnabledVal is False, a value of 1 can be used. When using MessageVersion of 2.2.0 or 2.3.1 and both BrowserJavaEnabledVal and BrowserJavaScriptEnabledVal are False, no value is required.

Data Type

String

BrowserScreenHeight Property (Server Class)

The screen height of the cardholder's browser.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetBrowserScreenHeight();
int SetBrowserScreenHeight(const char* lpszBrowserScreenHeight);

Unicode (Windows)
LPWSTR GetBrowserScreenHeight();
INT SetBrowserScreenHeight(LPCWSTR lpszBrowserScreenHeight);

char* ipworks3ds_server_getbrowserscreenheight(void* lpObj);
int ipworks3ds_server_setbrowserscreenheight(void* lpObj, const char* lpszBrowserScreenHeight);

QString GetBrowserScreenHeight();
int SetBrowserScreenHeight(QString qsBrowserScreenHeight);

Default Value

""

Remarks

This field contains the total height of the cardholder's screen in pixels.

For MessageVersion 2.1.0, this field is required. If BrowserJavaEnabledVal is False, a value of 0 can be used. When using MessageVersion of 2.2.0 or 2.3.1 and both BrowserJavaEnabledVal and BrowserJavaScriptEnabledVal are False, no value is required.

Data Type

String

BrowserScreenWidth Property (Server Class)

The screen width of the cardholder's browser.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetBrowserScreenWidth();
int SetBrowserScreenWidth(const char* lpszBrowserScreenWidth);

Unicode (Windows)
LPWSTR GetBrowserScreenWidth();
INT SetBrowserScreenWidth(LPCWSTR lpszBrowserScreenWidth);

char* ipworks3ds_server_getbrowserscreenwidth(void* lpObj);
int ipworks3ds_server_setbrowserscreenwidth(void* lpObj, const char* lpszBrowserScreenWidth);

QString GetBrowserScreenWidth();
int SetBrowserScreenWidth(QString qsBrowserScreenWidth);

Default Value

""

Remarks

This field contains the total width of the cardholder's screen in pixels.

For MessageVersion 2.1.0, this field is required. If BrowserJavaEnabledVal is False, a value of 0 can be used. When using MessageVersion of 2.2.0 or 2.3.1 and both BrowserJavaEnabledVal and BrowserJavaScriptEnabledVal are False, no value is required.

Data Type

String

BrowserTimeZone Property (Server Class)

The timezone offset of the cardholder's browser.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetBrowserTimeZone();
int SetBrowserTimeZone(const char* lpszBrowserTimeZone);

Unicode (Windows)
LPWSTR GetBrowserTimeZone();
INT SetBrowserTimeZone(LPCWSTR lpszBrowserTimeZone);

char* ipworks3ds_server_getbrowsertimezone(void* lpObj);
int ipworks3ds_server_setbrowsertimezone(void* lpObj, const char* lpszBrowserTimeZone);

QString GetBrowserTimeZone();
int SetBrowserTimeZone(QString qsBrowserTimeZone);

Default Value

""

Remarks

This field contains the difference between UTC time and the cardholder's browser local time in minutes.

For MessageVersion 2.1.0, this field is required. If BrowserJavaEnabledVal is False, a value of 0 can be used. When using MessageVersion of 2.2.0 or 2.3.1 and both BrowserJavaEnabledVal and BrowserJavaScriptEnabledVal are False, no value is required.

Data Type

String

BrowserUserAgent Property (Server Class)

The User-Agent provided by the cardholder's browser.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetBrowserUserAgent();
int SetBrowserUserAgent(const char* lpszBrowserUserAgent);

Unicode (Windows)
LPWSTR GetBrowserUserAgent();
INT SetBrowserUserAgent(LPCWSTR lpszBrowserUserAgent);

char* ipworks3ds_server_getbrowseruseragent(void* lpObj);
int ipworks3ds_server_setbrowseruseragent(void* lpObj, const char* lpszBrowserUserAgent);

QString GetBrowserUserAgent();
int SetBrowserUserAgent(QString qsBrowserUserAgent);

Default Value

""

Remarks

This field contains the exact content of the HTTP User-Agent header.

Data Type

String

CardExpDate Property (Server Class)

Expiration date of the PAN or Token.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetCardExpDate();
int SetCardExpDate(const char* lpszCardExpDate);

Unicode (Windows)
LPWSTR GetCardExpDate();
INT SetCardExpDate(LPCWSTR lpszCardExpDate);

char* ipworks3ds_server_getcardexpdate(void* lpObj);
int ipworks3ds_server_setcardexpdate(void* lpObj, const char* lpszCardExpDate);

QString GetCardExpDate();
int SetCardExpDate(QString qsCardExpDate);

Default Value

""

Remarks

This field contains the expiration date of the PAN or Token supplied in the CardNumber property. The format for this field is YYMM.

Data Type

String

CardholderEmail Property (Server Class)

The cardholder email address.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetCardholderEmail();
int SetCardholderEmail(const char* lpszCardholderEmail);

Unicode (Windows)
LPWSTR GetCardholderEmail();
INT SetCardholderEmail(LPCWSTR lpszCardholderEmail);

char* ipworks3ds_server_getcardholderemail(void* lpObj);
int ipworks3ds_server_setcardholderemail(void* lpObj, const char* lpszCardholderEmail);

QString GetCardholderEmail();
int SetCardholderEmail(QString qsCardholderEmail);

Default Value

""

Remarks

This field contains the cardholder email address to be sent to the directory server when calling SendAuthRequest.

Data Type

String

CardholderHomePhone Property (Server Class)

The cardholder home phone number.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetCardholderHomePhone();
int SetCardholderHomePhone(const char* lpszCardholderHomePhone);

Unicode (Windows)
LPWSTR GetCardholderHomePhone();
INT SetCardholderHomePhone(LPCWSTR lpszCardholderHomePhone);

char* ipworks3ds_server_getcardholderhomephone(void* lpObj);
int ipworks3ds_server_setcardholderhomephone(void* lpObj, const char* lpszCardholderHomePhone);

QString GetCardholderHomePhone();
int SetCardholderHomePhone(QString qsCardholderHomePhone);

Default Value

""

Remarks

This field contains the home phone number provided by the card holder.

Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899)

The "-" is used to separate the "Country Code" and "Subscriber" sections. The values are then formatted according to the EMVCo specification (a JSON object) in the request like so:

  "homePhone": {
    "cc": "1",
    "subscriber": "1234567899"
  }

Data Type

String

CardholderMobilePhone Property (Server Class)

The cardholder mobile phone number.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetCardholderMobilePhone();
int SetCardholderMobilePhone(const char* lpszCardholderMobilePhone);

Unicode (Windows)
LPWSTR GetCardholderMobilePhone();
INT SetCardholderMobilePhone(LPCWSTR lpszCardholderMobilePhone);

char* ipworks3ds_server_getcardholdermobilephone(void* lpObj);
int ipworks3ds_server_setcardholdermobilephone(void* lpObj, const char* lpszCardholderMobilePhone);

QString GetCardholderMobilePhone();
int SetCardholderMobilePhone(QString qsCardholderMobilePhone);

Default Value

""

Remarks

This field contains the mobile phone number provided by the cardholder.

Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899)

The "-" is used to separate the "Country Code" and "Subscriber" sections. The values are then formatted according to the EMVCo specification (a JSON object) in the request like so:

  "homePhone": {
    "cc": "1",
    "subscriber": "1234567899"
  }

Data Type

String

CardholderName Property (Server Class)

Name of the cardholder.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetCardholderName();
int SetCardholderName(const char* lpszCardholderName);

Unicode (Windows)
LPWSTR GetCardholderName();
INT SetCardholderName(LPCWSTR lpszCardholderName);

char* ipworks3ds_server_getcardholdername(void* lpObj);
int ipworks3ds_server_setcardholdername(void* lpObj, const char* lpszCardholderName);

QString GetCardholderName();
int SetCardholderName(QString qsCardholderName);

Default Value

""

Remarks

This property contains the name of the cardholder. Limited to the alphanumeric characters listed in EMV Book 4, Annex B. Required to be set unless market or regional mandates restricts sending this information.

Data Type

String

CardholderWorkPhone Property (Server Class)

The cardholder work phone number.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetCardholderWorkPhone();
int SetCardholderWorkPhone(const char* lpszCardholderWorkPhone);

Unicode (Windows)
LPWSTR GetCardholderWorkPhone();
INT SetCardholderWorkPhone(LPCWSTR lpszCardholderWorkPhone);

char* ipworks3ds_server_getcardholderworkphone(void* lpObj);
int ipworks3ds_server_setcardholderworkphone(void* lpObj, const char* lpszCardholderWorkPhone);

QString GetCardholderWorkPhone();
int SetCardholderWorkPhone(QString qsCardholderWorkPhone);

Default Value

""

Remarks

This field contains the work phone number provided by the cardholder.

Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899)

The "-" is used to separate the "Country Code" and "Subscriber" sections. The values are then formatted according to the EMVCo specification (a JSON object) in the request like so:

  "homePhone": {
    "cc": "1",
    "subscriber": "1234567899"
  }

Data Type

String

CardNumber Property (Server Class)

Customer's account number that will be authenticated.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetCardNumber();
int SetCardNumber(const char* lpszCardNumber);

Unicode (Windows)
LPWSTR GetCardNumber();
INT SetCardNumber(LPCWSTR lpszCardNumber);

char* ipworks3ds_server_getcardnumber(void* lpObj);
int ipworks3ds_server_setcardnumber(void* lpObj, const char* lpszCardNumber);

QString GetCardNumber();
int SetCardNumber(QString qsCardNumber);

Default Value

""

Remarks

This property contains the customer's credit card number (PAN) or token that will be used in the authorization request for payment transactions. This property is 13-19 characters long.

Data Type

String

CardRanges Property (Server Class)

A collection of card ranges to be added to or removed from the cache.

Syntax

• C++
• C
• Qt

IPWorks3DSList<IPWorks3DSCardRangeInfo>* GetCardRanges();

int ipworks3ds_server_getcardrangecount(void* lpObj);

char* ipworks3ds_server_getcardrangeacsendprotocolversion(void* lpObj, int cardrangeindex);

char* ipworks3ds_server_getcardrangeacsinformationindicator(void* lpObj, int cardrangeindex);

char* ipworks3ds_server_getcardrangeacsstartprotocolversion(void* lpObj, int cardrangeindex);

char* ipworks3ds_server_getcardrangeaction(void* lpObj, int cardrangeindex);

char* ipworks3ds_server_getcardrangedsendprotocolversion(void* lpObj, int cardrangeindex);

char* ipworks3ds_server_getcardrangedsstartprotocolversion(void* lpObj, int cardrangeindex);

char* ipworks3ds_server_getcardrangeend(void* lpObj, int cardrangeindex);

char* ipworks3ds_server_getcardrangemethodurl(void* lpObj, int cardrangeindex);

char* ipworks3ds_server_getcardrangestart(void* lpObj, int cardrangeindex);

int GetCardRangeCount();

QString GetCardRangeACSEndProtocolVersion(int iCardRangeIndex);

QString GetCardRangeACSInformationIndicator(int iCardRangeIndex);

QString GetCardRangeACSStartProtocolVersion(int iCardRangeIndex);

QString GetCardRangeAction(int iCardRangeIndex);

QString GetCardRangeDSEndProtocolVersion(int iCardRangeIndex);

QString GetCardRangeDSStartProtocolVersion(int iCardRangeIndex);

QString GetCardRangeEnd(int iCardRangeIndex);

QString GetCardRangeMethodURL(int iCardRangeIndex);

QString GetCardRangeStart(int iCardRangeIndex);

Remarks

Card ranges may be returned from the directory server in the Preparation Response Message when the RequestCardRanges method is called. This collection will contain this information.

This property is read-only and not available at design time.

Data Type

IPWorks3DSCardRangeInfo

ChallengeWindowSize Property (Server Class)

Challenge window size.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetChallengeWindowSize();
int SetChallengeWindowSize(int iChallengeWindowSize);

Unicode (Windows)
INT GetChallengeWindowSize();
INT SetChallengeWindowSize(INT iChallengeWindowSize);

int ipworks3ds_server_getchallengewindowsize(void* lpObj);
int ipworks3ds_server_setchallengewindowsize(void* lpObj, int iChallengeWindowSize);

int GetChallengeWindowSize();
int SetChallengeWindowSize(int iChallengeWindowSize);

Default Value

1

Remarks

This field indicates the dimensions of the challenge window that has been displayed to the cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience.

Preconfigured sizes are width x height in pixels of the window displayed in the cardholder browser. Possible values are:

This value is included in the Challenge Request Message (CReq) generated by the component when the GetChallengeRequest methods are called.

Data Type

Integer

ClientAuthRequest Property (Server Class)

The data received by the class to be sent in the authentication request.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetClientAuthRequest();
int SetClientAuthRequest(const char* lpszClientAuthRequest);

Unicode (Windows)
LPWSTR GetClientAuthRequest();
INT SetClientAuthRequest(LPCWSTR lpszClientAuthRequest);

char* ipworks3ds_server_getclientauthrequest(void* lpObj);
int ipworks3ds_server_setclientauthrequest(void* lpObj, const char* lpszClientAuthRequest);

QString GetClientAuthRequest();
int SetClientAuthRequest(QString qsClientAuthRequest);

Default Value

""

Remarks

The 3DS SDK should prepare data to be sent by the 3DS Server class. Set ClientAuthRequest to the data received from the 3DS SDK before calling SendAuthRequest.

See the 3DS SDK documentation for details on preparing this data.

Data Type

String

ClientAuthResponse Property (Server Class)

The authentication response for an app-based flow.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetClientAuthResponse();

Unicode (Windows)
LPWSTR GetClientAuthResponse();

char* ipworks3ds_server_getclientauthresponse(void* lpObj);

QString GetClientAuthResponse();

Default Value

""

Remarks

This property is populated after calling SendAuthRequest, and is only applicable for the app-based flow. If a challenge is required, this data should be sent back to the 3DS SDK over the secure channel.

See SendAuthRequest for more details about handling the response.

This property is read-only.

Data Type

String

DataPacketOut Property (Server Class)

Contains the data packet sent to the server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetDataPacketOut();

Unicode (Windows)
LPWSTR GetDataPacketOut();

char* ipworks3ds_server_getdatapacketout(void* lpObj);

QString GetDataPacketOut();

Default Value

""

Remarks

After calling either the RequestCardRanges, or SendAuthRequest methods, this property will contain the entire data packet that was sent. Also, after calling the GetChallengeRequest or GetResultsResponse method, this property will contain the constructed messages. The contents of this property should be logged for each transaction.

This property is read-only and not available at design time.

Data Type

String

DeviceChannel Property (Server Class)

Device channel.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetDeviceChannel();
int SetDeviceChannel(const char* lpszDeviceChannel);

Unicode (Windows)
LPWSTR GetDeviceChannel();
INT SetDeviceChannel(LPCWSTR lpszDeviceChannel);

char* ipworks3ds_server_getdevicechannel(void* lpObj);
int ipworks3ds_server_setdevicechannel(void* lpObj, const char* lpszDeviceChannel);

QString GetDeviceChannel();
int SetDeviceChannel(QString qsDeviceChannel);

Default Value

"02"

Remarks

This field indicates the type of channel interface being used to initiate the transaction.

Possible values include:

Data Type

String

DirectoryServerURL Property (Server Class)

The address of the Directory Server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetDirectoryServerURL();
int SetDirectoryServerURL(const char* lpszDirectoryServerURL);

Unicode (Windows)
LPWSTR GetDirectoryServerURL();
INT SetDirectoryServerURL(LPCWSTR lpszDirectoryServerURL);

char* ipworks3ds_server_getdirectoryserverurl(void* lpObj);
int ipworks3ds_server_setdirectoryserverurl(void* lpObj, const char* lpszDirectoryServerURL);

QString GetDirectoryServerURL();
int SetDirectoryServerURL(QString qsDirectoryServerURL);

Default Value

""

Remarks

This is the URL to which the RequestCardRanges and SendAuthRequest methods post.

Data Type

String

DSSupportedProtocols Property (Server Class)

Protocol Versions supported by the DS.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetDSSupportedProtocols();
int SetDSSupportedProtocols(int iDSSupportedProtocols);

Unicode (Windows)
INT GetDSSupportedProtocols();
INT SetDSSupportedProtocols(INT iDSSupportedProtocols);

int ipworks3ds_server_getdssupportedprotocols(void* lpObj);
int ipworks3ds_server_setdssupportedprotocols(void* lpObj, int iDSSupportedProtocols);

int GetDSSupportedProtocols();
int SetDSSupportedProtocols(int iDSSupportedProtocols);

Default Value

0

Remarks

The active protocol versions supported by the Directory Server. A bitwise OR of the following values:

Data Type

Integer

DSURLs Property (Server Class)

A collection of Directory Server URLs to which the 3DS Server will send the AReq message.

Syntax

• C++
• C
• Qt

IPWorks3DSList<IPWorks3DSDSURL>* GetDSURLs();

int ipworks3ds_server_getdsurlcount(void* lpObj);

char* ipworks3ds_server_getdsurlcountrycode(void* lpObj, int dsurlindex);

char* ipworks3ds_server_getdsurlthreedsservertodsurl(void* lpObj, int dsurlindex);

int GetDSURLCount();

QString GetDSURLCountryCode(int iDSURLIndex);

QString GetDSURLThreeDSServerToDsUrl(int iDSURLIndex);

Remarks

A list of Directory Server URLs that may be returend when retrieving card ranges using the RequestCardRanges method. These URLs may optionally be provided in case there are preferred DS URLs for some countries.

This field is only applicable when MessageVersion is 2.3.1.

This property is read-only and not available at design time.

Data Type

IPWorks3DSDSURL

ErrorPacket Property (Server Class)

The error packet.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetErrorPacket();

Unicode (Windows)
LPWSTR GetErrorPacket();

char* ipworks3ds_server_geterrorpacket(void* lpObj);

QString GetErrorPacket();

Default Value

""

Remarks

If an error is encountered while parsing a received packet using the CheckResponse method, this field will be populated with an error packet to be sent back to the server.

If the message being parsed is an error, this field will be populated with the received error packet itself.

This property is read-only.

Data Type

String

Extensions Property (Server Class)

Extensions to be included in the next outgoing packet.

Syntax

• C++
• C
• Qt

IPWorks3DSList<IPWorks3DSExtension>* GetExtensions();
int SetExtensions(IPWorks3DSList<IPWorks3DSExtension>* val);

int ipworks3ds_server_getextensioncount(void* lpObj);
int ipworks3ds_server_setextensioncount(void* lpObj, int iExtensionCount);

int ipworks3ds_server_getextensioncritical(void* lpObj, int extensionindex);
int ipworks3ds_server_setextensioncritical(void* lpObj, int extensionindex, int bExtensionCritical);

char* ipworks3ds_server_getextensiondata(void* lpObj, int extensionindex);
int ipworks3ds_server_setextensiondata(void* lpObj, int extensionindex, const char* lpszExtensionData);

char* ipworks3ds_server_getextensionid(void* lpObj, int extensionindex);
int ipworks3ds_server_setextensionid(void* lpObj, int extensionindex, const char* lpszExtensionId);

char* ipworks3ds_server_getextensionname(void* lpObj, int extensionindex);
int ipworks3ds_server_setextensionname(void* lpObj, int extensionindex, const char* lpszExtensionName);

int GetExtensionCount();
int SetExtensionCount(int iExtensionCount);

bool GetExtensionCritical(int iExtensionIndex);
int SetExtensionCritical(int iExtensionIndex, bool bExtensionCritical);

QString GetExtensionData(int iExtensionIndex);
int SetExtensionData(int iExtensionIndex, QString qsExtensionData);

QString GetExtensionId(int iExtensionIndex);
int SetExtensionId(int iExtensionIndex, QString qsExtensionId);

QString GetExtensionName(int iExtensionIndex);
int SetExtensionName(int iExtensionIndex, QString qsExtensionName);

Remarks

Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in Message Extensions. This collection contains extension data to be included in the next outgoing request. Extensions can be added manually or using the AddExtension method.

Note: The maximum number of extensions is 10.

Data Type

IPWorks3DSExtension

MerchantCategoryCode Property (Server Class)

Merchant category code.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMerchantCategoryCode();
int SetMerchantCategoryCode(const char* lpszMerchantCategoryCode);

Unicode (Windows)
LPWSTR GetMerchantCategoryCode();
INT SetMerchantCategoryCode(LPCWSTR lpszMerchantCategoryCode);

char* ipworks3ds_server_getmerchantcategorycode(void* lpObj);
int ipworks3ds_server_setmerchantcategorycode(void* lpObj, const char* lpszMerchantCategoryCode);

QString GetMerchantCategoryCode();
int SetMerchantCategoryCode(QString qsMerchantCategoryCode);

Default Value

""

Remarks

DS-specific code describing the Merchant's type of business, product, or service. Required to be set prior to calling SendAuthRequest.

Data Type

String

MerchantCountryCode Property (Server Class)

Country code of the merchant.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMerchantCountryCode();
int SetMerchantCountryCode(const char* lpszMerchantCountryCode);

Unicode (Windows)
LPWSTR GetMerchantCountryCode();
INT SetMerchantCountryCode(LPCWSTR lpszMerchantCountryCode);

char* ipworks3ds_server_getmerchantcountrycode(void* lpObj);
int ipworks3ds_server_setmerchantcountrycode(void* lpObj, const char* lpszMerchantCountryCode);

QString GetMerchantCountryCode();
int SetMerchantCountryCode(QString qsMerchantCountryCode);

Default Value

""

Remarks

This field contains the country code of the merchant. This value correlates to the Merchant Country Code as defined by each Payment System or DS. Required to be set prior to calling SendAuthRequest.

Data Type

String

MerchantName Property (Server Class)

Merchant name.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMerchantName();
int SetMerchantName(const char* lpszMerchantName);

Unicode (Windows)
LPWSTR GetMerchantName();
INT SetMerchantName(LPCWSTR lpszMerchantName);

char* ipworks3ds_server_getmerchantname(void* lpObj);
int ipworks3ds_server_setmerchantname(void* lpObj, const char* lpszMerchantName);

QString GetMerchantName();
int SetMerchantName(QString qsMerchantName);

Default Value

""

Remarks

The name of the merchant as assigned by the acquirer or payment system. Required to be set prior to calling SendAuthRequest.

Data Type

String

MessageCategory Property (Server Class)

The category of the message.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMessageCategory();
int SetMessageCategory(const char* lpszMessageCategory);

Unicode (Windows)
LPWSTR GetMessageCategory();
INT SetMessageCategory(LPCWSTR lpszMessageCategory);

char* ipworks3ds_server_getmessagecategory(void* lpObj);
int ipworks3ds_server_setmessagecategory(void* lpObj, const char* lpszMessageCategory);

QString GetMessageCategory();
int SetMessageCategory(QString qsMessageCategory);

Default Value

""

Remarks

This field identifies the category of the message (Payment Authentication or Non-Payment Authentication). This will be sent in the Authentication Request Message (AReq) sent by the component when SendAuthRequest is called, and in the Results Request Message (RReq) received from the directory server (populated after calling CheckResponse.

Possible values include:

Data Type

String

MessageVersion Property (Server Class)

Protocol version identifier.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMessageVersion();
int SetMessageVersion(const char* lpszMessageVersion);

Unicode (Windows)
LPWSTR GetMessageVersion();
INT SetMessageVersion(LPCWSTR lpszMessageVersion);

char* ipworks3ds_server_getmessageversion(void* lpObj);
int ipworks3ds_server_setmessageversion(void* lpObj, const char* lpszMessageVersion);

QString GetMessageVersion();
int SetMessageVersion(QString qsMessageVersion);

Default Value

"2.1.0"

Remarks

The protocol version number of the specification used by the system creating this message.

Possible values are:

Data Type

String

MethodNotificationURL Property (Server Class)

The URL to which the method notification will be posted.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMethodNotificationURL();
int SetMethodNotificationURL(const char* lpszMethodNotificationURL);

Unicode (Windows)
LPWSTR GetMethodNotificationURL();
INT SetMethodNotificationURL(LPCWSTR lpszMethodNotificationURL);

char* ipworks3ds_server_getmethodnotificationurl(void* lpObj);
int ipworks3ds_server_setmethodnotificationurl(void* lpObj, const char* lpszMethodNotificationURL);

QString GetMethodNotificationURL();
int SetMethodNotificationURL(QString qsMethodNotificationURL);

Default Value

""

Remarks

This property specifies the URL to which the ACS will post when the method execution has completed. This must be set before calling GetMethodData. See GetMethodData for more details.

Data Type

String

NotificationURL Property (Server Class)

The notification URL to which the challenge response is sent.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetNotificationURL();
int SetNotificationURL(const char* lpszNotificationURL);

Unicode (Windows)
LPWSTR GetNotificationURL();
INT SetNotificationURL(LPCWSTR lpszNotificationURL);

char* ipworks3ds_server_getnotificationurl(void* lpObj);
int ipworks3ds_server_setnotificationurl(void* lpObj, const char* lpszNotificationURL);

QString GetNotificationURL();
int SetNotificationURL(QString qsNotificationURL);

Default Value

""

Remarks

This property specifies the URL to which the final challenge response is POSTed in a browser-based flow. This must be set before calling SendAuthRequest.

After the challenge interaction is complete the ACS will post data to the URL specified in this property to notify the application that the challenge is complete. The data received at this URL can be processed by calling CheckResponse. See GetChallengeRequest and CheckResponse for more details.

Data Type

String

Operation Property (Server Class)

Contains details received from an Operation Request Message sent from a Directory Server.

Syntax

• C++
• C
• Qt

IPWorks3DSOperationInfo* GetOperation();
int SetOperation(IPWorks3DSOperationInfo* val);

char* ipworks3ds_server_getoperationinfocategory(void* lpObj);

char* ipworks3ds_server_getoperationinfodescription(void* lpObj);

char* ipworks3ds_server_getoperationinfoexpirationdate(void* lpObj);

char* ipworks3ds_server_getoperationinfomessagestatus(void* lpObj);
int ipworks3ds_server_setoperationinfomessagestatus(void* lpObj, const char* lpszOperationInfoMessageStatus);

char* ipworks3ds_server_getoperationinfopriortransactionid(void* lpObj);

int ipworks3ds_server_getoperationinfopriortransactionidtype(void* lpObj);

char* ipworks3ds_server_getoperationinfosequenceid(void* lpObj);

int ipworks3ds_server_getoperationinfosequencenumber(void* lpObj);
int ipworks3ds_server_setoperationinfosequencenumber(void* lpObj, int iOperationInfoSequenceNumber);

int ipworks3ds_server_getoperationinfosequencetotal(void* lpObj);

char* ipworks3ds_server_getoperationinfoseverity(void* lpObj);

QString GetOperationInfoCategory();

QString GetOperationInfoDescription();

QString GetOperationInfoExpirationDate();

QString GetOperationInfoMessageStatus();
int SetOperationInfoMessageStatus(QString qsOperationInfoMessageStatus);

QString GetOperationInfoPriorTransactionId();

int GetOperationInfoPriorTransactionIdType();

QString GetOperationInfoSequenceId();

int GetOperationInfoSequenceNumber();
int SetOperationInfoSequenceNumber(int iOperationInfoSequenceNumber);

int GetOperationInfoSequenceTotal();

QString GetOperationInfoSeverity();

Remarks

This type contains details received from an Operation Request Message sent from a Directory Server after parsing with CheckResponse. See CheckResponse and GetOperationResponse for details on how to process a received OReq message.

Data Type

IPWorks3DSOperationInfo

Proxy Property (Server Class)

A set of properties related to proxy access.

Syntax

• C++
• C
• Qt

IPWorks3DSProxy* GetProxy();
int SetProxy(IPWorks3DSProxy* val);

int ipworks3ds_server_getproxyauthscheme(void* lpObj);
int ipworks3ds_server_setproxyauthscheme(void* lpObj, int iProxyAuthScheme);

int ipworks3ds_server_getproxyautodetect(void* lpObj);
int ipworks3ds_server_setproxyautodetect(void* lpObj, int bProxyAutoDetect);

char* ipworks3ds_server_getproxypassword(void* lpObj);
int ipworks3ds_server_setproxypassword(void* lpObj, const char* lpszProxyPassword);

int ipworks3ds_server_getproxyport(void* lpObj);
int ipworks3ds_server_setproxyport(void* lpObj, int iProxyPort);

char* ipworks3ds_server_getproxyserver(void* lpObj);
int ipworks3ds_server_setproxyserver(void* lpObj, const char* lpszProxyServer);

int ipworks3ds_server_getproxyssl(void* lpObj);
int ipworks3ds_server_setproxyssl(void* lpObj, int iProxySSL);

char* ipworks3ds_server_getproxyuser(void* lpObj);
int ipworks3ds_server_setproxyuser(void* lpObj, const char* lpszProxyUser);

int GetProxyAuthScheme();
int SetProxyAuthScheme(int iProxyAuthScheme);

bool GetProxyAutoDetect();
int SetProxyAutoDetect(bool bProxyAutoDetect);

QString GetProxyPassword();
int SetProxyPassword(QString qsProxyPassword);

int GetProxyPort();
int SetProxyPort(int iProxyPort);

QString GetProxyServer();
int SetProxyServer(QString qsProxyServer);

int GetProxySSL();
int SetProxySSL(int iProxySSL);

QString GetProxyUser();
int SetProxyUser(QString qsProxyUser);

Remarks

This property contains fields describing the proxy through which the class will attempt to connect.

Data Type

IPWorks3DSProxy

PurchaseAmount Property (Server Class)

Purchase amount to be authorized.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetPurchaseAmount();
int SetPurchaseAmount(const char* lpszPurchaseAmount);

Unicode (Windows)
LPWSTR GetPurchaseAmount();
INT SetPurchaseAmount(LPCWSTR lpszPurchaseAmount);

char* ipworks3ds_server_getpurchaseamount(void* lpObj);
int ipworks3ds_server_setpurchaseamount(void* lpObj, const char* lpszPurchaseAmount);

QString GetPurchaseAmount();
int SetPurchaseAmount(QString qsPurchaseAmount);

Default Value

""

Remarks

This field contains the purchase amount to be authorized. The transaction amount is to be presented with an implied decimal point. For example, US $10.00 must be represented as 1000, and $0.10 is likewise simply 10. The allowable number of significant digits as well as the positioning of any implied decimal point is dictated by the designated PurchaseExponent. This field may not contain a negative number.

Data Type

String

PurchaseCurrency Property (Server Class)

Identifies the type of currency used by the merchant.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetPurchaseCurrency();
int SetPurchaseCurrency(const char* lpszPurchaseCurrency);

Unicode (Windows)
LPWSTR GetPurchaseCurrency();
INT SetPurchaseCurrency(LPCWSTR lpszPurchaseCurrency);

char* ipworks3ds_server_getpurchasecurrency(void* lpObj);
int ipworks3ds_server_setpurchasecurrency(void* lpObj, const char* lpszPurchaseCurrency);

QString GetPurchaseCurrency();
int SetPurchaseCurrency(QString qsPurchaseCurrency);

Default Value

"840"

Remarks

This field contains the three digit number assigned by the signing member or processor to identify the currency in which PurchaseCurrency is expressed. This property should contain the ISO-4217 numeric code. For example, the ISO code for US Dollars is "840".

Data Type

String

PurchaseDate Property (Server Class)

The date of the transaction.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetPurchaseDate();
int SetPurchaseDate(const char* lpszPurchaseDate);

Unicode (Windows)
LPWSTR GetPurchaseDate();
INT SetPurchaseDate(LPCWSTR lpszPurchaseDate);

char* ipworks3ds_server_getpurchasedate(void* lpObj);
int ipworks3ds_server_setpurchasedate(void* lpObj, const char* lpszPurchaseDate);

QString GetPurchaseDate();
int SetPurchaseDate(QString qsPurchaseDate);

Default Value

""

Remarks

This field contains the date and time of the purchase, expressed in UTC. The format of this field must be: YYYYMMDDHHMMSS

Data Type

String

PurchaseExponent Property (Server Class)

Minor units of currency.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetPurchaseExponent();
int SetPurchaseExponent(const char* lpszPurchaseExponent);

Unicode (Windows)
LPWSTR GetPurchaseExponent();
INT SetPurchaseExponent(LPCWSTR lpszPurchaseExponent);

char* ipworks3ds_server_getpurchaseexponent(void* lpObj);
int ipworks3ds_server_setpurchaseexponent(void* lpObj, const char* lpszPurchaseExponent);

QString GetPurchaseExponent();
int SetPurchaseExponent(QString qsPurchaseExponent);

Default Value

"2"

Remarks

This field indicates the minor units, or number of decimal places, of the currency specified in the PurchaseCurrency property. For instance, the Japanese Yen has a value of "0", the US Dollar a value of "2", and the Kuwati Dinar a value of "3".

Data Type

String

Ranges Property (Server Class)

A collection of card ranges associated with the CardRangeData event.

Syntax

• C++
• C
• Qt

IPWorks3DSList<IPWorks3DSRange>* GetRanges();

int ipworks3ds_server_getrangecount(void* lpObj);

char* ipworks3ds_server_getrangeend(void* lpObj, int rangeindex);

char* ipworks3ds_server_getrangestart(void* lpObj, int rangeindex);

int GetRangeCount();

QString GetRangeEnd(int iRangeIndex);

QString GetRangeStart(int iRangeIndex);

Remarks

When card ranges are requested using MessageVersion 2.3.1, the CardRangeData event will fire for each card data object received in the Preparation Response Message (PRes). When the event fires, this property will contain the ranges for which the event information applies. Additional ACS information for the ranges will be contained in the ACSProtocolInfos property.

Each Range object includes a Start and End. Multiple card ranges can be associated with the data contained in the CardRangeData event.

This field is only applicable when MessageVersion is 2.3.1.

This property is read-only and not available at design time.

Data Type

IPWorks3DSRange

RecurringExpDate Property (Server Class)

Recurring expiration date.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetRecurringExpDate();
int SetRecurringExpDate(const char* lpszRecurringExpDate);

Unicode (Windows)
LPWSTR GetRecurringExpDate();
INT SetRecurringExpDate(LPCWSTR lpszRecurringExpDate);

char* ipworks3ds_server_getrecurringexpdate(void* lpObj);
int ipworks3ds_server_setrecurringexpdate(void* lpObj, const char* lpszRecurringExpDate);

QString GetRecurringExpDate();
int SetRecurringExpDate(QString qsRecurringExpDate);

Default Value

""

Remarks

This field contains the date after which no further authorizations shall be performed. The format of this field must be: YYYYMMDD

Required when AuthenticationIndicator is 02 or 03, or when ThreeRIIndicator is 01 or 02.

Data Type

String

RecurringFrequency Property (Server Class)

The number of days between recurring payments.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetRecurringFrequency();
int SetRecurringFrequency(const char* lpszRecurringFrequency);

Unicode (Windows)
LPWSTR GetRecurringFrequency();
INT SetRecurringFrequency(LPCWSTR lpszRecurringFrequency);

char* ipworks3ds_server_getrecurringfrequency(void* lpObj);
int ipworks3ds_server_setrecurringfrequency(void* lpObj, const char* lpszRecurringFrequency);

QString GetRecurringFrequency();
int SetRecurringFrequency(QString qsRecurringFrequency);

Default Value

""

Remarks

This field indicates the minimum number of days between authorizations.

Required when AuthenticationIndicator is 02 or 03, or when ThreeRIIndicator is 01 or 02.

Data Type

String

RequestorId Property (Server Class)

Directory server assigned 3DS Requestor identifier.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetRequestorId();
int SetRequestorId(const char* lpszRequestorId);

Unicode (Windows)
LPWSTR GetRequestorId();
INT SetRequestorId(LPCWSTR lpszRequestorId);

char* ipworks3ds_server_getrequestorid(void* lpObj);
int ipworks3ds_server_setrequestorid(void* lpObj, const char* lpszRequestorId);

QString GetRequestorId();
int SetRequestorId(QString qsRequestorId);

Default Value

""

Remarks

This field contains the 3DS Requestor identifier as assigned by the directory server. This is sent in the Authentication Request Message (AReq) sent by the component in the SendAuthRequest method.

Data Type

String

RequestorName Property (Server Class)

Directory server assigned 3DS Requestor name.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetRequestorName();
int SetRequestorName(const char* lpszRequestorName);

Unicode (Windows)
LPWSTR GetRequestorName();
INT SetRequestorName(LPCWSTR lpszRequestorName);

char* ipworks3ds_server_getrequestorname(void* lpObj);
int ipworks3ds_server_setrequestorname(void* lpObj, const char* lpszRequestorName);

QString GetRequestorName();
int SetRequestorName(QString qsRequestorName);

Default Value

""

Remarks

This field contains the 3DS Requestor name as assigned by the directory server. This is sent in the Authentication Request Message (AReq) sent by the component in the SendAuthRequest method.

Data Type

String

RequestorURL Property (Server Class)

3DS Requestor website or customer care site.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetRequestorURL();
int SetRequestorURL(const char* lpszRequestorURL);

Unicode (Windows)
LPWSTR GetRequestorURL();
INT SetRequestorURL(LPCWSTR lpszRequestorURL);

char* ipworks3ds_server_getrequestorurl(void* lpObj);
int ipworks3ds_server_setrequestorurl(void* lpObj, const char* lpszRequestorURL);

QString GetRequestorURL();
int SetRequestorURL(QString qsRequestorURL);

Default Value

""

Remarks

This field contains the fully qualified URL of the 3DS Requestor website or customer care site. This is sent in the Authentication Request Message (AReq) sent by the component in the SendAuthRequest method.

Data Type

String

ResultsStatus Property (Server Class)

The status of the Results Request.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetResultsStatus();
int SetResultsStatus(int iResultsStatus);

Unicode (Windows)
INT GetResultsStatus();
INT SetResultsStatus(INT iResultsStatus);

int ipworks3ds_server_getresultsstatus(void* lpObj);
int ipworks3ds_server_setresultsstatus(void* lpObj, int iResultsStatus);

int GetResultsStatus();
int SetResultsStatus(int iResultsStatus);

Default Value

0

Remarks

This field contains the status of the results request and is used when generating the Results Response Message (RRes) via the GetResultsResponse method. This will indicate if the message was successfully received for further processing or provide more detail to the ACS on why the challenge could not be completed.

Possible values include:

Before calling GetResultsResponse, the Server can use the value of the RequestorChallengeInd to determine whether or not a value of 02 is appropriate. It must use the necessary error handling logic when processing ARes messages to determine whether or not a value of 03 is appropriate.

If the TransactionStatus is D and a DecoupledRequestIndicator value of F or B was used, ResultsStatus should be set to 04 and a separate 3RI authentication should be initiated within 60 seconds.

Data Type

Integer

ResultsURL Property (Server Class)

3DS Server URL.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetResultsURL();
int SetResultsURL(const char* lpszResultsURL);

Unicode (Windows)
LPWSTR GetResultsURL();
INT SetResultsURL(LPCWSTR lpszResultsURL);

char* ipworks3ds_server_getresultsurl(void* lpObj);
int ipworks3ds_server_setresultsurl(void* lpObj, const char* lpszResultsURL);

QString GetResultsURL();
int SetResultsURL(QString qsResultsURL);

Default Value

""

Remarks

Full qualified URL of the 3DS Server to which the directory server will send the Results Request Message (RReq) after the challenge has completed. This is sent to the directory server when calling the SendAuthRequest method.

Data Type

String

SDKType Property (Server Class)

Type of the 3DS SDK used for the app-based flow.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSDKType();
int SetSDKType(const char* lpszSDKType);

Unicode (Windows)
LPWSTR GetSDKType();
INT SetSDKType(LPCWSTR lpszSDKType);

char* ipworks3ds_server_getsdktype(void* lpObj);
int ipworks3ds_server_setsdktype(void* lpObj, const char* lpszSDKType);

QString GetSDKType();
int SetSDKType(QString qsSDKType);

Default Value

"01"

Remarks

Indicates the type of 3DS SDK. This provides additional information to the DS and ACS to determine the best approach for handling the transaction.

Valid values are:

When Split-SDK is selected (02), SplitSDKVariant will indicate the implementation charactistics of the Split-SDK client, and SplitSDKLimited can be used to indicate if the Split-SDK client has limited capabilities.

This property is valid for MessageVersion 2.3.1 only.

Data Type

String

SerialNumber Property (Server Class)

Serial number indicating the state of the current card range cache.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSerialNumber();
int SetSerialNumber(const char* lpszSerialNumber);

Unicode (Windows)
LPWSTR GetSerialNumber();
INT SetSerialNumber(LPCWSTR lpszSerialNumber);

char* ipworks3ds_server_getserialnumber(void* lpObj);
int ipworks3ds_server_setserialnumber(void* lpObj, const char* lpszSerialNumber);

QString GetSerialNumber();
int SetSerialNumber(QString qsSerialNumber);

Default Value

""

Remarks

If this element is present when submitting a Preparation Request Message (PReq) with the RequestCardRanges method, the directory server returns card ranges that have been updated since the time of the response which returned this serial number. If this element is not present, the directory server returns all card ranges. This field is updated with a new serial number after each call to RequestCardRanges.

Data Type

String

ServerTransactionId Property (Server Class)

Server transaction identifier.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetServerTransactionId();
int SetServerTransactionId(const char* lpszServerTransactionId);

Unicode (Windows)
LPWSTR GetServerTransactionId();
INT SetServerTransactionId(LPCWSTR lpszServerTransactionId);

char* ipworks3ds_server_getservertransactionid(void* lpObj);
int ipworks3ds_server_setservertransactionid(void* lpObj, const char* lpszServerTransactionId);

QString GetServerTransactionId();
int SetServerTransactionId(QString qsServerTransactionId);

Default Value

""

Remarks

Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. This value is generated by the class when GetMethodData or SendAuthRequest is called.

Data Type

String

ShippingAddress Property (Server Class)

The customer's shipping address.

Syntax

• C++
• C
• Qt

IPWorks3DSAddressInfo* GetShippingAddress();
int SetShippingAddress(IPWorks3DSAddressInfo* val);

char* ipworks3ds_server_getshippingaddresscity(void* lpObj);
int ipworks3ds_server_setshippingaddresscity(void* lpObj, const char* lpszShippingAddressCity);

char* ipworks3ds_server_getshippingaddresscountry(void* lpObj);
int ipworks3ds_server_setshippingaddresscountry(void* lpObj, const char* lpszShippingAddressCountry);

char* ipworks3ds_server_getshippingaddressline1(void* lpObj);
int ipworks3ds_server_setshippingaddressline1(void* lpObj, const char* lpszShippingAddressLine1);

char* ipworks3ds_server_getshippingaddressline2(void* lpObj);
int ipworks3ds_server_setshippingaddressline2(void* lpObj, const char* lpszShippingAddressLine2);

char* ipworks3ds_server_getshippingaddressline3(void* lpObj);
int ipworks3ds_server_setshippingaddressline3(void* lpObj, const char* lpszShippingAddressLine3);

char* ipworks3ds_server_getshippingaddresspostalcode(void* lpObj);
int ipworks3ds_server_setshippingaddresspostalcode(void* lpObj, const char* lpszShippingAddressPostalCode);

char* ipworks3ds_server_getshippingaddressstate(void* lpObj);
int ipworks3ds_server_setshippingaddressstate(void* lpObj, const char* lpszShippingAddressState);

QString GetShippingAddressCity();
int SetShippingAddressCity(QString qsShippingAddressCity);

QString GetShippingAddressCountry();
int SetShippingAddressCountry(QString qsShippingAddressCountry);

QString GetShippingAddressLine1();
int SetShippingAddressLine1(QString qsShippingAddressLine1);

QString GetShippingAddressLine2();
int SetShippingAddressLine2(QString qsShippingAddressLine2);

QString GetShippingAddressLine3();
int SetShippingAddressLine3(QString qsShippingAddressLine3);

QString GetShippingAddressPostalCode();
int SetShippingAddressPostalCode(QString qsShippingAddressPostalCode);

QString GetShippingAddressState();
int SetShippingAddressState(QString qsShippingAddressState);

Remarks

This property specifies details about the customer's shipping address. This should be set before calling SendAuthRequest.

Data Type

IPWorks3DSAddressInfo

SSLAcceptServerCert Property (Server Class)

Instructs the class to unconditionally accept the server certificate that matches the supplied certificate.

Syntax

• C++
• C
• Qt

IPWorks3DSCertificate* GetSSLAcceptServerCert();
int SetSSLAcceptServerCert(IPWorks3DSCertificate* val);

char* ipworks3ds_server_getsslacceptservercerteffectivedate(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertexpirationdate(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertextendedkeyusage(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertfingerprint(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertfingerprintsha1(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertfingerprintsha256(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertissuer(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertprivatekey(void* lpObj);

int ipworks3ds_server_getsslacceptservercertprivatekeyavailable(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertprivatekeycontainer(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertpublickey(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertpublickeyalgorithm(void* lpObj);

int ipworks3ds_server_getsslacceptservercertpublickeylength(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertserialnumber(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertsignaturealgorithm(void* lpObj);

int ipworks3ds_server_getsslacceptservercertstore(void* lpObj, char** lpSSLAcceptServerCertStore, int* lenSSLAcceptServerCertStore);
int ipworks3ds_server_setsslacceptservercertstore(void* lpObj, const char* lpSSLAcceptServerCertStore, int lenSSLAcceptServerCertStore);

char* ipworks3ds_server_getsslacceptservercertstorepassword(void* lpObj);
int ipworks3ds_server_setsslacceptservercertstorepassword(void* lpObj, const char* lpszSSLAcceptServerCertStorePassword);

int ipworks3ds_server_getsslacceptservercertstoretype(void* lpObj);
int ipworks3ds_server_setsslacceptservercertstoretype(void* lpObj, int iSSLAcceptServerCertStoreType);

char* ipworks3ds_server_getsslacceptservercertsubjectaltnames(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertthumbprintmd5(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertthumbprintsha1(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertthumbprintsha256(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertusage(void* lpObj);

int ipworks3ds_server_getsslacceptservercertusageflags(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertversion(void* lpObj);

char* ipworks3ds_server_getsslacceptservercertsubject(void* lpObj);
int ipworks3ds_server_setsslacceptservercertsubject(void* lpObj, const char* lpszSSLAcceptServerCertSubject);

int ipworks3ds_server_getsslacceptservercertencoded(void* lpObj, char** lpSSLAcceptServerCertEncoded, int* lenSSLAcceptServerCertEncoded);
int ipworks3ds_server_setsslacceptservercertencoded(void* lpObj, const char* lpSSLAcceptServerCertEncoded, int lenSSLAcceptServerCertEncoded);

QString GetSSLAcceptServerCertEffectiveDate();

QString GetSSLAcceptServerCertExpirationDate();

QString GetSSLAcceptServerCertExtendedKeyUsage();

QString GetSSLAcceptServerCertFingerprint();

QString GetSSLAcceptServerCertFingerprintSHA1();

QString GetSSLAcceptServerCertFingerprintSHA256();

QString GetSSLAcceptServerCertIssuer();

QString GetSSLAcceptServerCertPrivateKey();

bool GetSSLAcceptServerCertPrivateKeyAvailable();

QString GetSSLAcceptServerCertPrivateKeyContainer();

QString GetSSLAcceptServerCertPublicKey();

QString GetSSLAcceptServerCertPublicKeyAlgorithm();

int GetSSLAcceptServerCertPublicKeyLength();

QString GetSSLAcceptServerCertSerialNumber();

QString GetSSLAcceptServerCertSignatureAlgorithm();

QByteArray GetSSLAcceptServerCertStore();
int SetSSLAcceptServerCertStore(QByteArray qbaSSLAcceptServerCertStore);

QString GetSSLAcceptServerCertStorePassword();
int SetSSLAcceptServerCertStorePassword(QString qsSSLAcceptServerCertStorePassword);

int GetSSLAcceptServerCertStoreType();
int SetSSLAcceptServerCertStoreType(int iSSLAcceptServerCertStoreType);

QString GetSSLAcceptServerCertSubjectAltNames();

QString GetSSLAcceptServerCertThumbprintMD5();

QString GetSSLAcceptServerCertThumbprintSHA1();

QString GetSSLAcceptServerCertThumbprintSHA256();

QString GetSSLAcceptServerCertUsage();

int GetSSLAcceptServerCertUsageFlags();

QString GetSSLAcceptServerCertVersion();

QString GetSSLAcceptServerCertSubject();
int SetSSLAcceptServerCertSubject(QString qsSSLAcceptServerCertSubject);

QByteArray GetSSLAcceptServerCertEncoded();
int SetSSLAcceptServerCertEncoded(QByteArray qbaSSLAcceptServerCertEncoded);

Remarks

If it finds any issues with the certificate presented by the server, the class will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Note: This functionality is provided only for cases in which you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

Data Type

IPWorks3DSCertificate

SSLCert Property (Server Class)

The certificate to be used during Secure Sockets Layer (SSL) negotiation.

Syntax

• C++
• C
• Qt

IPWorks3DSCertificate* GetSSLCert();
int SetSSLCert(IPWorks3DSCertificate* val);

char* ipworks3ds_server_getsslcerteffectivedate(void* lpObj);

char* ipworks3ds_server_getsslcertexpirationdate(void* lpObj);

char* ipworks3ds_server_getsslcertextendedkeyusage(void* lpObj);

char* ipworks3ds_server_getsslcertfingerprint(void* lpObj);

char* ipworks3ds_server_getsslcertfingerprintsha1(void* lpObj);

char* ipworks3ds_server_getsslcertfingerprintsha256(void* lpObj);

char* ipworks3ds_server_getsslcertissuer(void* lpObj);

char* ipworks3ds_server_getsslcertprivatekey(void* lpObj);

int ipworks3ds_server_getsslcertprivatekeyavailable(void* lpObj);

char* ipworks3ds_server_getsslcertprivatekeycontainer(void* lpObj);

char* ipworks3ds_server_getsslcertpublickey(void* lpObj);

char* ipworks3ds_server_getsslcertpublickeyalgorithm(void* lpObj);

int ipworks3ds_server_getsslcertpublickeylength(void* lpObj);

char* ipworks3ds_server_getsslcertserialnumber(void* lpObj);

char* ipworks3ds_server_getsslcertsignaturealgorithm(void* lpObj);

int ipworks3ds_server_getsslcertstore(void* lpObj, char** lpSSLCertStore, int* lenSSLCertStore);
int ipworks3ds_server_setsslcertstore(void* lpObj, const char* lpSSLCertStore, int lenSSLCertStore);

char* ipworks3ds_server_getsslcertstorepassword(void* lpObj);
int ipworks3ds_server_setsslcertstorepassword(void* lpObj, const char* lpszSSLCertStorePassword);

int ipworks3ds_server_getsslcertstoretype(void* lpObj);
int ipworks3ds_server_setsslcertstoretype(void* lpObj, int iSSLCertStoreType);

char* ipworks3ds_server_getsslcertsubjectaltnames(void* lpObj);

char* ipworks3ds_server_getsslcertthumbprintmd5(void* lpObj);

char* ipworks3ds_server_getsslcertthumbprintsha1(void* lpObj);

char* ipworks3ds_server_getsslcertthumbprintsha256(void* lpObj);

char* ipworks3ds_server_getsslcertusage(void* lpObj);

int ipworks3ds_server_getsslcertusageflags(void* lpObj);

char* ipworks3ds_server_getsslcertversion(void* lpObj);

char* ipworks3ds_server_getsslcertsubject(void* lpObj);
int ipworks3ds_server_setsslcertsubject(void* lpObj, const char* lpszSSLCertSubject);

int ipworks3ds_server_getsslcertencoded(void* lpObj, char** lpSSLCertEncoded, int* lenSSLCertEncoded);
int ipworks3ds_server_setsslcertencoded(void* lpObj, const char* lpSSLCertEncoded, int lenSSLCertEncoded);

QString GetSSLCertEffectiveDate();

QString GetSSLCertExpirationDate();

QString GetSSLCertExtendedKeyUsage();

QString GetSSLCertFingerprint();

QString GetSSLCertFingerprintSHA1();

QString GetSSLCertFingerprintSHA256();

QString GetSSLCertIssuer();

QString GetSSLCertPrivateKey();

bool GetSSLCertPrivateKeyAvailable();

QString GetSSLCertPrivateKeyContainer();

QString GetSSLCertPublicKey();

QString GetSSLCertPublicKeyAlgorithm();

int GetSSLCertPublicKeyLength();

QString GetSSLCertSerialNumber();

QString GetSSLCertSignatureAlgorithm();

QByteArray GetSSLCertStore();
int SetSSLCertStore(QByteArray qbaSSLCertStore);

QString GetSSLCertStorePassword();
int SetSSLCertStorePassword(QString qsSSLCertStorePassword);

int GetSSLCertStoreType();
int SetSSLCertStoreType(int iSSLCertStoreType);

QString GetSSLCertSubjectAltNames();

QString GetSSLCertThumbprintMD5();

QString GetSSLCertThumbprintSHA1();

QString GetSSLCertThumbprintSHA256();

QString GetSSLCertUsage();

int GetSSLCertUsageFlags();

QString GetSSLCertVersion();

QString GetSSLCertSubject();
int SetSSLCertSubject(QString qsSSLCertSubject);

QByteArray GetSSLCertEncoded();
int SetSSLCertEncoded(QByteArray qbaSSLCertEncoded);

Remarks

This property includes the digital certificate that the class will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

Data Type

IPWorks3DSCertificate

SSLServerCert Property (Server Class)

The server certificate for the last established connection.

Syntax

• C++
• C
• Qt

IPWorks3DSCertificate* GetSSLServerCert();

char* ipworks3ds_server_getsslservercerteffectivedate(void* lpObj);

char* ipworks3ds_server_getsslservercertexpirationdate(void* lpObj);

char* ipworks3ds_server_getsslservercertextendedkeyusage(void* lpObj);

char* ipworks3ds_server_getsslservercertfingerprint(void* lpObj);

char* ipworks3ds_server_getsslservercertfingerprintsha1(void* lpObj);

char* ipworks3ds_server_getsslservercertfingerprintsha256(void* lpObj);

char* ipworks3ds_server_getsslservercertissuer(void* lpObj);

char* ipworks3ds_server_getsslservercertprivatekey(void* lpObj);

int ipworks3ds_server_getsslservercertprivatekeyavailable(void* lpObj);

char* ipworks3ds_server_getsslservercertprivatekeycontainer(void* lpObj);

char* ipworks3ds_server_getsslservercertpublickey(void* lpObj);

char* ipworks3ds_server_getsslservercertpublickeyalgorithm(void* lpObj);

int ipworks3ds_server_getsslservercertpublickeylength(void* lpObj);

char* ipworks3ds_server_getsslservercertserialnumber(void* lpObj);

char* ipworks3ds_server_getsslservercertsignaturealgorithm(void* lpObj);

int ipworks3ds_server_getsslservercertstore(void* lpObj, char** lpSSLServerCertStore, int* lenSSLServerCertStore);

char* ipworks3ds_server_getsslservercertstorepassword(void* lpObj);

int ipworks3ds_server_getsslservercertstoretype(void* lpObj);

char* ipworks3ds_server_getsslservercertsubjectaltnames(void* lpObj);

char* ipworks3ds_server_getsslservercertthumbprintmd5(void* lpObj);

char* ipworks3ds_server_getsslservercertthumbprintsha1(void* lpObj);

char* ipworks3ds_server_getsslservercertthumbprintsha256(void* lpObj);

char* ipworks3ds_server_getsslservercertusage(void* lpObj);

int ipworks3ds_server_getsslservercertusageflags(void* lpObj);

char* ipworks3ds_server_getsslservercertversion(void* lpObj);

char* ipworks3ds_server_getsslservercertsubject(void* lpObj);

int ipworks3ds_server_getsslservercertencoded(void* lpObj, char** lpSSLServerCertEncoded, int* lenSSLServerCertEncoded);

QString GetSSLServerCertEffectiveDate();

QString GetSSLServerCertExpirationDate();

QString GetSSLServerCertExtendedKeyUsage();

QString GetSSLServerCertFingerprint();

QString GetSSLServerCertFingerprintSHA1();

QString GetSSLServerCertFingerprintSHA256();

QString GetSSLServerCertIssuer();

QString GetSSLServerCertPrivateKey();

bool GetSSLServerCertPrivateKeyAvailable();

QString GetSSLServerCertPrivateKeyContainer();

QString GetSSLServerCertPublicKey();

QString GetSSLServerCertPublicKeyAlgorithm();

int GetSSLServerCertPublicKeyLength();

QString GetSSLServerCertSerialNumber();

QString GetSSLServerCertSignatureAlgorithm();

QByteArray GetSSLServerCertStore();

QString GetSSLServerCertStorePassword();

int GetSSLServerCertStoreType();

QString GetSSLServerCertSubjectAltNames();

QString GetSSLServerCertThumbprintMD5();

QString GetSSLServerCertThumbprintSHA1();

QString GetSSLServerCertThumbprintSHA256();

QString GetSSLServerCertUsage();

int GetSSLServerCertUsageFlags();

QString GetSSLServerCertVersion();

QString GetSSLServerCertSubject();

QByteArray GetSSLServerCertEncoded();

Remarks

This property contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

Data Type

IPWorks3DSCertificate

Timeout Property (Server Class)

A timeout for the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTimeout();
int SetTimeout(int iTimeout);

Unicode (Windows)
INT GetTimeout();
INT SetTimeout(INT iTimeout);

int ipworks3ds_server_gettimeout(void* lpObj);
int ipworks3ds_server_settimeout(void* lpObj, int iTimeout);

int GetTimeout();
int SetTimeout(int iTimeout);

Default Value

30

Remarks

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If Timeout is set to a positive value, the class will wait for the operation to complete before returning control.

The class will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not freeze and remains responsive.

If Timeout expires, and the operation is not yet complete, the class fails with an error.

Note: By default, all timeouts are inactivity timeouts, that is, the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received.

The default value for the Timeout property is 30 seconds.

Data Type

Integer

TransactionStatus Property (Server Class)

The transaction status from the last parsed message (ARes, RReq, or CRes).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetTransactionStatus();

Unicode (Windows)
LPWSTR GetTransactionStatus();

char* ipworks3ds_server_gettransactionstatus(void* lpObj);

QString GetTransactionStatus();

Default Value

""

Remarks

Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:

Note: The CRes message can contain only a value of Y or N. Values of D and I are only applicable for 3DS version 2.2.0.

This property is read-only.

Data Type

String

AddExtension Method (Server Class)

Adds an extension to the collection.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddExtension(const char* lpszId, const char* lpszName, int bCritical, const char* lpszData);

Unicode (Windows)
INT AddExtension(LPCWSTR lpszId, LPCWSTR lpszName, BOOL bCritical, LPCWSTR lpszData);

int ipworks3ds_server_addextension(void* lpObj, const char* lpszId, const char* lpszName, int bCritical, const char* lpszData);

int AddExtension(const QString& qsId, const QString& qsName, bool bCritical, const QString& qsData);

Remarks

Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in Message Extensions. AddExtension adds a new extension to the Extensions collection.

Note: The maximum number of extensions is 10.

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

AddRequestField Method (Server Class)

Adds a field to the data in the request.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddRequestField(const char* lpszName, const char* lpszValue, int iValueType);

Unicode (Windows)
INT AddRequestField(LPCWSTR lpszName, LPCWSTR lpszValue, INT iValueType);

int ipworks3ds_server_addrequestfield(void* lpObj, const char* lpszName, const char* lpszValue, int iValueType);

int AddRequestField(const QString& qsName, const QString& qsValue, int iValueType);

Remarks

This method can be used to extend the requests constructed by the class. When this method is called, the component will add the specified field to the end of the request.

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

CheckResponse Method (Server Class)

Parses the specified message.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CheckResponse(const char* lpszresponse);

Unicode (Windows)
INT CheckResponse(LPCWSTR lpszresponse);

int ipworks3ds_server_checkresponse(void* lpObj, const char* lpszresponse);

int CheckResponse(const QString& qsresponse);

Remarks

CheckResponse parses a variety of messages that are sent to the Server as part of the authentication process.

The following messages can be parsed using this method:

• The threeDSMethodData form variables received at the MethodNotificationURL
• The Results Request (RReq) message received at the ResultsURL
• The cres form variables received at the NotificationURL
• The Operation Request Message (OReq) sent from a DS.

When calling the method, pass the message to be parsed as the Response parameter. The properties which are populated after calling this method vary depending on the type of message being parsed. See below for additional information.

Method Data from MethodNotificationURL

After calling GetMethodData, a request is made to the MethodURL. After this, the ACS will make a POST to MethodNotificationURL to inform the requestor of completion. Retrieve the threeDSMethodData form variable value that was POSTed and pass it to this method. After calling this method, the following properties are populated:

• ServerTransactionId

Results Request message from ResultsURL

When a challenge is completed for both app-based and browser-based flows, a POST is made to the ResultsURL with a Results Request message.

Prior to checking this RReq message, the ServerTransactionId can be extracted using the ExtractRReqServerTransactionId configuration setting. This value can then be used to look up details on the transaction that were saved prior to starting the challenge process, including the messageVersion which must be set via the MessageVersion property prior to passing the RReq message to the CheckResponse method.

Pass the body of the HTTP request received at ResultsURL to this method. This contains information about the results, and asks for a Results Response to be sent back containing the ResultsStatus.

After calling this method, the following properties are populated:

• AuthenticationECI
• TransactionStatus
• TransactionStatusReason
• ChallengeCancellationIndicator
• AuthenticationType
• AuthenticationValue

To respond to the POST, set ResultsStatus to the appropriate value and call GetResultsResponse to build a response message to be sent back to the directory server. Use the value from GetResultsResponse in the application as the body of the HTTP response. Set the Content-Type header to application/JSON; charset=utf-8

If TransactionStatus is D and TransactionStatusReason is 29 or 30, this indicates that decoupled authentication should now be performed. When building the Results Response, a ResultsStatus value of 04 should be used. Then, within 60 seconds, a new 3RI authentication must be started with the following field requirements:

• ThreeRIIndicator set to 19, indicating Decoupled Authentication Fallback
• DecoupledRequestIndicator set to Y
• AuthenticationInformation set with threeDSReqPriorRef set to the ACS Transaction ID and threeDSReqPriorAuthMethod set to 02 (Cardholder challenge occurred by ACS).

Final Challenge Response from NotificationURL

In a browser-based flow, the challenge takes place directly between the cardholder and the ACS in a separate iframe or window. The ACS will POST the final challenge response to the NotificationURL after the challenge is complete. Retrieve the cres form variable value from the POST data and pass it to CheckResponse. After calling this method the following properties are populated:

• ServerTransactionId
• TransactionStatus

In addition to the cres variable, a threeDSSessionData variable will be present if SessionData was set before calling GetChallengeRequest. The threeDSSessionData value POSTed to NotificationURL may be passed to EncodedSessionData. Query SessionData to get the decoded session data.

Operation Request Message (OReq)

OReq messages are used to communicate operational information from a DS to the 3DS Server. This message is not part of the 3-D Secure authentication flow.

When an OReq message is received, CheckResponse should be called to validate the message. There may be more than one OReq message sent in a sequence, and CheckResponse should be called for each. The current instance of the Server object can be cached for the duration of the OReq sequence until the final OReq is received. The Operation.SequenceNumber should also be set prior to calling CheckResponse. The component will verify the sequence number of the received OReq to ensure it's not out of sequence.

After calling this method, details are made available in Operation.

If any OReq data element fails validation, Operation.MessageStatus will be set to "02". If the OReq is valid, Operation.MessageStatus will be empty.

If the OReq is valid, determine if the final OReq has been received (Operation.SequenceNumber equals Operation.SequenceTotal). If these values match, the final OReq in the sequence has been received, and GetOperationResponse can be used to generate the ORes message.

For valid OReq messages that are not the final OReq in the sequence, the response should be HTTP Status 200 (OK) with an empty HTTP body.

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

Config Method (Server Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* ipworks3ds_server_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its 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.

GetChallengeRequest Method (Server Class)

Builds the Challenge Request (CReq) for browser-based flow.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetChallengeRequest();

Unicode (Windows)
LPWSTR GetChallengeRequest();

char* ipworks3ds_server_getchallengerequest(void* lpObj);

QString GetChallengeRequest();

Remarks

The GetChallengeRequest method is used to build the Challenge Request (CReq) which will be sent in a form post to the ACSURL property via the cardholder browser.

An iframe should be created in the cardholder's browser, which will be used to send the challenge request and allow the cardholder and ACS to interact directly.

The size of the challenge window (iframe) may be any of the sizes listed in ChallengeWindowSize. Before calling this method set ChallengeWindowSize to the appropriate value to let the ACS know the size of the window on the cardholder's browser.

Calling this method will return a string which should be placed in a creq form variable.

The SessionData setting may also be set with any data that may be helpful to continue processing the transaction after the final challenge response is received at the NotificationURL. To prepare the session data for submission, query EncodedSessionData. The encoded string may then be placed in the threeDSSessionData form variable.

Note: The maximum length of the threeDSSessionData form variable, after being encoded, is 1024 bytes.

Example Form

Response Handling

Once the challenge has been completed by the cardholder, the directory server will post a Results Request (RReq) to the ResultsURL specified when calling SendAuthRequest. See CheckResponse and GetResultsResponse for more details.

The ACS will also post the Challenge Response to the NotificationURL specified when calling SendAuthRequest. This post contains data which may be parsed to verify the challenge results. See CheckResponse for more details.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its 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.

GetMethodData Method (Server Class)

Prepares method data to be sent to the ACS before the authentication request is sent.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMethodData();

Unicode (Windows)
LPWSTR GetMethodData();

char* ipworks3ds_server_getmethoddata(void* lpObj);

QString GetMethodData();

Remarks

The GetMethodData method prepares data to be transmitted to the ACS via the cardholder's browser.

When a transaction begins, the card range cache should be queried to find details about the card range to which the card number belongs. If a MethodURL is defined for the card range, this method should be used to prepare data to be sent via the cardholder's browser to the MethodURL.

If the MethodURL is not set for the specified card range, set MethodCompletionIndicator to U before calling SendAuthRequest.

The following properties are applicable when calling this method:

• MethodNotificationURL (required)

This method returns a string which contains encoded data to be sent to the ACS. This includes ServerTransactionId and MethodNotificationURL. After calling this method, the returned string can be transmitted to the ACS via the cardholder's browser.

As per the EMVCo specification, create a hidden iframe in the browser and send a form with the field name threeDSMethodData containing the return value from this method and post the form to the MethodURL.

The ACS will record information about the customer's environment and then POST back to the MethodNotificationURL. The page at this URL should expect a form variable with the name threeDSMethodData which will contain the original ServerTransactionId value in order to match the response with the request. The form variable value will be base64url encoded and may be passed directly to the CheckResponse method. The class will decode and parse the received value and populate ServerTransactionId with the value from the received data.

If the response from the ACS is not received within 10 seconds, set MethodCompletionIndicator to N before calling SendAuthRequest.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its 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.

GetOperationResponse Method (Server Class)

Builds and returns the Operation Response Message (ORes) to be sent back to the Directory Server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOperationResponse();

Unicode (Windows)
LPWSTR GetOperationResponse();

char* ipworks3ds_server_getoperationresponse(void* lpObj);

QString GetOperationResponse();

Remarks

This method builds the Operation Response Message (ORes) to be sent back to the Directory Server in an HTTP reply to the final Operation Request (OReq) message. It returns a JSON object containing the fields required for the ORes.

When an OReq message is received, CheckResponse should be called to validate the message. There may be more than one OReq message sent in a sequence, and CheckResponse should be called for each. While several OReq messages may be received in a sequence (totalling Operation.SequenceTotal), the ORes message is only expected to be generated using GetOperationResponse after the final OReq. For valid intermediate OReq messages the response should be HTTP Status 200 (OK) with an empty HTTP body.

After passing the final received OReq message to the CheckResponse method, all the properties required to be set before building the ORes will have been populated except for Operation.MessageStatus, which indicates whether or not the message was successfully received for further processing, or provides more detail to the DS on why the requested action could not be completed.

Possible values include:

If any OReq data element fails validation from CheckResponse, Operation.MessageStatus will be set to "02". The ErrorPacket can be queried and should be returned to the DS.

For valid OReq messages, Operation.MessageStatus will be empty. Next, determine if the final OReq has been received (Operation.SequenceNumber equals Operation.SequenceTotal). If these values match, the final OReq in the sequence has been received, and GetOperationResponse can be used to generate the ORes message.

Once Operation.MessageStatus has been set, GetOperationResponse can be called and will return a string containing the reply to be sent in the response. In the HTTP server, use the string returned from this method as the body of the reply and set the Content-Type header to application/JSON; charset=utf-8

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its 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.

GetResultsResponse Method (Server Class)

Builds and returns the Results Response Message (RRes) to be sent back to the directory server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetResultsResponse();

Unicode (Windows)
LPWSTR GetResultsResponse();

char* ipworks3ds_server_getresultsresponse(void* lpObj);

QString GetResultsResponse();

Remarks

This method builds the Results Response Message (RRes) to be sent back to the directory server in the HTTP reply to the Results Request (RReq). It returns a JSON object containing the fields required for the RRes.

After passing the received RReq message to the CheckResponse method, all the properties required to be set before building the RRes will have been populated except for ResultsStatus, which indicates whether or not the message was successfully received for further processing, or provides more detail to the ACS on why the challenge could not be completed.

Possible values include:

The Server can use the value of the RequestorChallengeInd to determine whether or not a value of 02 is appropriate. It must use the necessary error handling logic when processing ARes messages to determine whether or not a value of 03 is appropriate.

Once ResultsStatus has been set, GetResultsResponse can be called and will return a string containing the reply to be sent in the response. In the HTTP server, use the string returned from this method as the body of the reply and set the Content-Type header to application/JSON; charset=utf-8

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its 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.

Interrupt Method (Server Class)

Interrupts the current action.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Interrupt();

Unicode (Windows)
INT Interrupt();

int ipworks3ds_server_interrupt(void* lpObj);

int Interrupt();

Remarks

This method interrupts any processing that the class is currently executing.

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

RequestCardRanges Method (Server Class)

Requests card ranges from the directory server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RequestCardRanges();

Unicode (Windows)
INT RequestCardRanges();

int ipworks3ds_server_requestcardranges(void* lpObj);

int RequestCardRanges();

Remarks

RequestCardRanges requests card ranges and additional information from the directory server.

When a transaction is initiated, the first step that should be taken is to find information about the card range to which the card number belongs. This includes the protocol version(s) supported by the ACS and DS, and if one exists, any corresponding Method URL (used in the browser flow).

Results of this method should be cached in order to quickly look up information when processing transactions. It is recommended to call this method once every 24 hours at a minimum, and once per hour as a maximum to refresh the cache. The class will not cache the returned values; it is up to the user to cache these values in an appropriate location.

The first time this method is called, SerialNumber will be empty, indicating that all results should be returned. This is an offset the server will use to return only new updates to the card ranges (if any) since the last request. The SerialNumber will be populated after this method returns, and this value should be saved to be used in subsequent calls.

When a response is received, the card ranges will be made available via the component events and properties.

When MessageVersion is set to 2.3.1, the CardRangeData event will fire for each card range data object received, and the Ranges and ACSProtocolInfos properties will be populated to be accessed within the event handler. Optionally, the DS may return a list of URLs that the 3DS Server can use for communication with the DS. If present, these will be available via both the DSURL event and the DSURLs property.

When MessageVersion is set to 2.2.0 or 2.1.0, the CardRange event will fire for each card range that is returned, and the results will also be held in the CardRanges property.

The following properties are applicable when calling this method:

• DirectoryServerURL (required)
• SerialNumber
• ServerTransactionId
• ServerOperatorId
• EnableDownloadCardRangeDataFile (2.3.1 only)

The following properties are populated after calling this method:

• CardRanges
• DSStartProtocolVersion
• DSEndProtocolVersion
• SerialNumber
• DSTransactionId
• ResendRequestCardRanges

When using MessageVersion 2.2.0 or 2.3.1, the returned ranges may include ACS Information Indicators. These are used to indicate additional functionality supported by the ACS for the card range(s). For 2.2.0, a ACSInformationIndicator field is exposed in both CardRanges collection and CardRange event. In version 2.3.1, this information is availalbe in the ACSProtocolInfos collection via the Indicator field. Possible values are:

• 01 - Authentication Available at ACS
• 02 - Attempts Supported by ACS or DS
• 03 - Decoupled Authentication Supported
• 04 - Whitelisting Supported
• 05 - Device Binding Supported (2.3.1 only)
• 06 - WebAuthn Authentication Supported (2.3.1 only)
• 07 - SPC Authentication Supported (2.3.1 only)
• 08 - Transaction Risk Analysis Exemption Supported (2.3.1 only)
• 09 - Trust List Exemption Supported (2.3.1 only)
• 10 - Low Value Exemption Supported (2.3.1 only)
• 11 - Secure Corporate Payments Exemption Supported (2.3.1 only)
• 80-99 - Reserved for DS Use

If an error is identified with the card range data received from the directory server when calling the RequestCardRanges method, the ResendRequestCardRanges configuration setting will be true, indicating that the request should be resent. When resending, if SerialNumber was specified for the initial request, it should be set to an empty string before calling RequestCardRanges again. Otherwise, the request can be sent without the serial number again, but the server may respond with an error due to multiple requests within an hour.

Note that retrieving card ranges can consume a lot of memory, especially when retrieving the initial set of ranges. The StoreCardRangeData and UseJsonDOM configuration settings can be set to help minimize the amount of memory used. A CardRangeTempPath setting can also be used to specify a temporary path to which the PRes packet will be temporarily written prior to parsing.

When using MessageVersion 2.3.1, if UseJsonDOM is false, the card ranges will need to be cached and processed after the RequestCardRanges method returns. The card ranges would then need to be processed in the order indicated by the CardRangeRecordsReadOrder configuration setting. A check will also need to be made for overlap of ranges. If issue(s) are found, the ReportCardRangeError configuration setting should be used to report the error to the directory server.

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

Reset Method (Server Class)

Clears all properties to their default values.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int ipworks3ds_server_reset(void* lpObj);

int Reset();

Remarks

This method clears all properties to their default values.

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

ResetTransactionInfo Method (Server Class)

Resets transaction specific information.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ResetTransactionInfo();

Unicode (Windows)
INT ResetTransactionInfo();

int ipworks3ds_server_resettransactioninfo(void* lpObj);

int ResetTransactionInfo();

Remarks

This method must be called between transactions when using the same class instance.

Each transaction that is attempted uses transaction specific values that should not be re-used in subsequent transactions. Call this method to make sure that any transaction specific information is cleared between transactions.

This method resets only the transaction specific information without resetting any other values which have been configured. This allows re-use of the same component instance.

In a Browser-Based flow the following are reset:

• Internal ephemeral encryption keys
• Values added by AddRequestField
• AccountType
• ACSURL
• AppIP
• AppURLIndicator
• AuthenticationECI
• AuthenticationValue
• BillingAddress
• BrowserAcceptHeader
• BrowserIPAddress
• BrowserJavaEnabledVal
• BrowserJavaScriptEnabledVal
• BrowserLanguage
• BrowserScreenColorDepth
• BrowserScreenHeight
• BrowserTimeZone
• BrowserUserAgent
• BrowserUserDeviceId
• BrowserUserId
• CardExpDate
• CardholderEmail
• CardholderHomePhone
• CardholderMobilePhone
• CardholderName
• CardholderWorkPhone
• CardNumber
• ClientAuthRequest
• ClientAuthResponse
• DataPacketOut
• ErrorPacket
• Operation
• PurchaseAmount
• PurchaseDate
• RecurringExpDate
• RecurringFrequency
• ResultsStatus
• ServerTransactionId
• ShippingAddress
• TransactionStatus
• AccountAgeIndicator
• AccountChangeDate
• AccountChangeIndicator
• AccountDate
• AccountDayTransactions
• AccountId
• AccountPasswordChangeDate
• AccountPasswordChangeIndicator
• AccountProvisioningAttempts
• AccountPurchaseCount
• AccountYearTransactions
• ACSChallengeMandatedIndicator
• ACSReferenceNumber
• ACSTransactionId
• AddressMatch
• AuthenticationType
• CardholderInformation
• ChallengeCancellationIndicator
• DecoupledRequestIndicator
• DeliveryEmailAddress
• DeliveryTimeframe
• DSReferenceNumber
• DSTransactionId
• EncodedSessionData
• IncomingRawExtensions
• OutgoingRawExtensions
• Extensions
• IncomingExtensionCount
• IncomingExtensionId
• IncomingExtensionName
• IncomingExtensionCritical
• IncomingExtensionData
• GiftCardAmount
• GiftCardCount
• GiftCardCurrency
• InstalmentPaymentData
• InteractionCounter
• MethodCompletionIndicator
• PaymentAccountAge
• PaymentAccountAge
• PaymentAccountAgeIndicator
• PaymentAccountAgeIndicator
• PreOrderDate
• PreOrderPurchaseIndicator
• AuthenticationInformation
• ReorderItemsIndicator
• ReqAuthCount
• ReqAuthData[Index]
• ReqAuthMethod[Index]
• ReqAuthTimestamp[Index]
• SessionData
• ShipAddressUsageDate
• ShipAddressUsageIndicator
• ShipIndicator
• ShipNameIndicator
• SuspiciousAccountActivity
• ThreeRIIndicator
• TransactionStatusReason
• TransactionType
• WhitelistStatus
• WhitelistStatusSource
• EMVPaymentTokenSource

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

SendAuthRequest Method (Server Class)

Sends the authentication request to the directory server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SendAuthRequest();

Unicode (Windows)
INT SendAuthRequest();

int ipworks3ds_server_sendauthrequest(void* lpObj);

int SendAuthRequest();

Remarks

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)
• MessageVersion (required)
• PurchaseAmount (required)
• PurchaseDate (required)
• RequestorId (required)
• RequestorName (required)
• RequestorURL (required)
• ResultsURL (required)
• AccountType
• AuthenticationIndicator
• BillingAddress*
• CardholderEmail
• CardholderHomePhone
• CardholderMobilePhone
• CardholderWorkPhone
• DecoupledMaxTimeout
• DecoupledRequestIndicator
• DeviceChannel
• MessageCategory
• PurchaseCurrency
• PurchaseExponent
• ServerOperatorId
• ServerTransactionId
• ShippingAddress*
• ThreeRIIndicator