RequestCardRanges Method
Requests card ranges from the directory server.
Syntax
server.requestCardRanges([callback])
Callback
The 'callback' parameter specifies a function which will be called when the operation completes (or an error is encountered). If the 'callback' parameter is not specified, then the method will block and will not return until the operation completes (or an error is encountered).
The callback for this method is defined as:
function(err){ }
'err' is the error that occurred. If there was no error, then 'err' is 'null'.
'err' has 2 properties which hold detailed information:
err.code err.message
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 include the protocol version number 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 for subsequent 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 first time this method is called, SerialNumber will be empty, indicating that all results should be returned. The CardRange event will fire for each result that is returned. The results will also be held in the CardRanges property.
The class will not cache the returned values; it is up to the user to cache these values in an appropriate location. The SerialNumber will be populated after this method returns. The SerialNumber should also be saved to be used in the next call to this method.
When making subsequent calls to this method, set SerialNumber to the value received from the last response. This is an offset the server will use to return only new updates (if any) to the card ranges since the last request.
The following properties are applicable when calling this method:
The following properties are populated after calling this method:
- CardRanges
- DSStartProtocolVersion
- DSEndProtocolVersion
- SerialNumber
- DSTransactionId
- ResendRequestCardRanges
When using ProtocolVersion 2.2.0, CardRanges may also include ACSInformationIndicator data. This provides additional information on the functionality that is supported for the card range. This field is a comma separate list of values returned from the server; possible values are:
- 01 - Authentication Available at ACS
- 02 - Attempts Supported by ACS or DS
- 03 - Decoupled Authentication Supported
- 04 - Whitelisting Supported
- 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.