CAV USER GUIDE. Document Version 3.3. March 2016

Transcription

1 CAV USER GUIDE Document Version 3.3 March 2016 For further information contact Beanstream Customer Support: (888) or

2 1 TABLE OF CONTENTS 2 List of Tables and Figures Overview Getting Started Navigation The Canadian Address Verification Suite QuickMatch SafeScan SafeScanID Process Flows Stand-Alone Request via the CAV API Requests Made with a Credit Card Transaction Configuration & Administration Viewing CAV Transaction Details Reviewing CAV Summary Information Reviewing Status and Response Messages CAV Reporting Download Response Messages QuickMatch Response Messages SafeScan Response Messages SafeScan ID Response Messages CAV Integration Procedures Service Versions Submitting a Stand-Alone Request ASP Script Response Codes Submitting the Request With a Transaction Province Codes XML Message Definitions Input XML Message Response XML Message Transaction Message XML Schema Request Message Response Message CAV Batch Processing Creating a CAV Batch File Uploading a CAV Batch File Appendix: Test data Page 2 of 37

3 2 LIST OF TABLES AND FIGURES Table 1: Credit File Reason Codes... 7 Table 2: Credit Card Reason Codes... 8 Table 3: Address Reason Codes... 9 Table 4: Date of Birth Reason Codes... 9 Table 5: SafeScan Response Messages Table 6: SafeScan ID Response Messages Table 7: CAV Integration Procedures Table 11: Response Codes Table 12: CAV with Transaction -- Request Parameters Table 13: CAV Batch Files -- Required Fields Figure 1: Sample Transaction Report... 5 Figure 2: Sample Transaction Details Page... 6 Page 3 of 37

4 3 OVERVIEW In conjunction with Equifax, Beanstream Internet Commerce has initiated a credit card and address verification tool that can help reduce merchant losses due to fraudulent credit card use and identity theft. This is accomplished by verifying that the credit card account number and the home address information presented either during the transaction or on an application is correct. This document provides an overview of the QuickMatch Suite (QuickMatch, SafeScan and SafeScan ID) along with an outline of services, integration procedures and administration options. Merchants can also find a list of response codes used in CAV reporting. 3.1 GETTING STARTED You must have one of the CAV service options enabled before you can begin using the information in this document. Refer to The Canadian Address Verification Suite to determine which type of service best meets your needs. Once you have made your decision, contact Beanstream Customer Support at: support@beanstream.com 3.2 NAVIGATION Log onto the Membership area at: Go to administration account settings CAV. Page 4 of 37

5 4 THE CANADIAN ADDRESS VERIFICATION SUITE The Canadian Address Verification Suite is used to verify the identity and address of consumers who make credit card purchases through the Internet or by telephone. Customer credit card numbers are checked against consumer data stored at Equifax, allowing businesses to quickly identify potential portfolio risks and reduce the likelihood of losses due to fraud. The QuickMatch service is easy to use and can be deployed as part of a complete credit card processing solution or as a stand-alone product. Currently, only purchase (P) or pre-authorization (PA) transactions are supported by the Beanstream system. WebPOS is not yet supported. Businesses communicate with the Beanstream host systems through the Internet using a simple, secure HTTPS protocol web interface. Fees for the service are charged on a per use basis and results are provided in real-time. As an added security measure, Beanstream allows merchants to limit the number of times that a particular credit card number can access the service (i.e. attempt to make a purchase unsuccessfully) within a certain time period. There are three levels in the QuickMatch Suite: QuickMatch, SafeScan, and SafeScan ID. You can choose to use these services in any of these combinations. QuickMatch QuickMatch + SafeScan QuickMatch + SafeScanID You will be charged per transaction. Fees will vary depending on the option you choose. Each service that you select can be toggled on or off. This may be useful if there are a variety of products for sale. A merchant may want to perform CAV on more expensive items (i.e. a computer), and not for inexpensive items (i.e. a radio). Alternatively, a merchant may elect to perform CAV only when the total dollar volume of the transaction exceeds X. Note that when using any of the tools in the QuickMatch Suite, you must advise a customer that their credit file is going to be hit. 4.1 QuickMatch QuickMatch checks credit card numbers, first name and last name, and the full customer address including civic number, city name, postal code, and province. The following information must be validated before a transaction is approved by QuickMatch: consumer name home address credit card number Page 5 of 37

6 Based on this input, QuickMatch will: Locate the credit file based on input of name and address information. Match the credit card account number entered against the account number found on the credit file. Analyze the status of the account (closed, inactive, lost, stolen, written off etc.) Return an immediate verification message, based on your customer s data specifically credit card number and address and corresponding credit file information. 4.2 SafeScan In addition to the items featured in QuickMatch, SafeScan also detects fraud by spotting misuse or irregularities associated with SINs and telephone numbers. The following information is validated before a transaction is approved by SafeScan: consumer name home address credit card number date of birth (DOB) (optional) telephone number (optional) social insurance number (SIN) (optional) If a SIN is provided, SafeScan returns SIN-related response codes (Social Insurance Number reported misused and Social Insurance Number reported retired). If SIN is not provided, SafeScan will still return all other response codes not related to SIN. If a telephone number is provided, SafeScan will report if this number has been misused. Please note that SafeScan does not check to see if the telephone number matches the applicants name and address. For this service please see SafeScanID. 4.3 SafeScanID In addition to providing all the features available in QuickMatch and SafeScan, SafeScanID completes the picture by first checking the applicant s birth date, then by checking the applicant s name, address and telephone number against the listed telephone number in a separate info direct database. If the telephone number does not match the address, a warning is generated. The following information is validated provided before a transaction is approved by SafeScan ID: consumer name home address credit card number date of birth (DOB) (optional) social insurance number (SIN) (optional) telephone number Page 6 of 37

7 5 PROCESS FLOWS 5.1 STAND-ALONE REQUEST VIA THE CAV API Merchant Website Website Proceed to Checkout Payment Form Transaction is complete Purchase Confirmation Page User shops on website Data is passed between Beanstream and the merchant for the Quickmatch portion of the tx 1 2 Data is passed between the merchant and the 3d party for the credit card processing portion of the tx Merchant displays an "approved" or "declined" message based on the results of the transaction Data is validated and passed to Equifax Beanstream Quickmatch Engine 3d Party Credit Card Processing Engine If Quickmatch is successful, the cc transaction is processed. Equifax Processing Partner & Bank Beanstream Quickmatch Service Third-Party Credit Card Processing Service To verify a customer s information without performing a monetary transaction (stand-alone CAV request), the merchant can post data directly to the CAV API. In this scenario, the steps are: The merchant passes data to Beanstream s CAV API. Beanstream passes data to Equifax. Equifax returns result set to Beanstream. Beanstream formats the result set and returns a response via the API to the merchant. The merchant determines the best method of handling/displaying the result set to the user. The merchant also has access to the detailed response message. The merchant determines, based on the response, whether to continue processing the credit card transaction or not. In all instances, the detailed response from Equifax will be logged in the database, and displayed in the transaction report details. Page 1 of 37

8 5.2 REQUESTS MADE WITH A CREDIT CARD TRANSACTION Merchant Website Website Proceed to Checkout Payment Form Transaction is complete Purchase Confirmation Page User shops on website Data is passed between Beanstream and the merchant Merchant displays an "approved" or "declined" message based on the results of the transaction Stop Response is reported back to merchant, and cc transaction is not processed Quickmatch Unsuccessful Data is validated and passed to Equifax Beanstream Quickmatch Engine Quickmatch Successful Beanstream Credit Card Processing Engine If Quickmatch is successful, the cc transaction is processed. Equifax Processing Partner & Bank Beanstream Quickmatch Service Beanstream Credit Card Processing Service Transactions that originate from the Payment Form, Shopping Cart, Process Transaction API, ecomrelay, or Server to Server, will follow this flow: The merchant passes data to Beanstream via the API Prior to submitting the transaction, Beanstream passes data to Equifax Equifax returns result set to Beanstream If the response is acceptable, the transaction is submitted for processing normally. If the response is unacceptable, the process is halted and an error message is returned to the merchant. In all instances, the detailed response from Equifax will be logged in the database, and displayed in the transaction report details. If a merchant does not want to perform CAV for every transaction, he or she can pass a flag to the Process Transaction API to tell it to omit CAV for a specific transaction. See Configuration & Administration for more information on how to implement this feature. Page 2 of 37

9 6 CONFIGURATION & ADMINISTRATION To configure CAV settings, go to administration account settings CAV in the left menu of the membership area. The following screen will appear: Page 3 of 37

10 All configuration options for the type of service you selected are displayed on this page. CAV-Enabled Flag Require CAV on all Transactions Limit CAV Attempts Access Pass Code Flags To turn your service on, check this box. To leave CAV services off, leave this area unselected. Check this box to CAV verify all transactions sent to the Process Transaction API. If left unselected transactions will not be CAV verified by default, however, merchants can still perform CAV by passing a parameter to the Process Transaction API called cavenabled (1 for enabled, 0 for disabled). In this case, one of the available order validation methods, such as password or referring host validation, must be enabled. This will prevent security from being compromised (the parameter cannot be changed by a third party). See Beanstream s Process Transaction API documentation for details on how to pass these parameters. Choose the number of times invalid card information can be entered before a user is shut out of the system. The number you enter will be the number of allowable attempts in a two week period. The ability to limit the number of tries a user may make before being shut out of the CAV service is configured globally. Enter a value here to create a CAV access passcode. CAV transactions will only be completed if a code matching the value entered here is passed with the transaction. If no value is entered then no pass code restriction is made. This section lists of a number of possible problems which Beanstream has identified as important information for each merchant to be aware of. You can select to have the system automatically pass or fail a transaction in each of these situations. Page 4 of 37

11 7 VIEWING CAV TRANSACTION DETAILS You can view detailed results for each CAV transaction using Beanstream s Transaction Report Module. 1. On the Member page, go to reporting analysis> transaction report in the left menu. 2. Use the dropdown menus (at the top) to set the reporting parameters. 3. Click the Refresh button at the bottom of the page 7.1 REVIEWING CAV SUMMARY INFORMATION Figure 1: Sample Transaction Report The Transaction Report has a checkmark if a transaction was processed using QuickMatch, SafeScan, or SafeScan ID. Credit card transactions processed with one of the services in the CAV suite will also have the abbreviation CAV attached in the Trans column of the report beside the normal transaction code (P for purchase, R for return, etc.). In the example shown above, the second transaction was processed as P+CAV, or Purchase with Canadian Address Verification. The first transaction listed in this example was not processed with CAV and the code in this column is just P. Note: For some merchants, CAV will be processed without a credit card transaction. In this case, the entry in the Trans line of this report will display CAV only without any associated type code. Page 5 of 37

12 7.2 REVIEWING STATUS AND RESPONSE MESSAGES Click on a listing in your transaction report page (refer to the figure in Reviewing CAV Summary Information). This screen opens: Figure 2: Sample Transaction Details Page The AVS Result will indicate all CAV results. The AV Response line will indicate the level of CAV that was implemented. In the example shown above, only the customer s credit card number and address were verified. If additional information was checked, more items will appear in the AV Response line. 7.3 CAV REPORTING DOWNLOAD RESPONSE MESSAGES As with all other Beanstream services, you can download CAV transaction information via our reporting API. You can access this reporting interface at: The report download can be imported to other applications. CAV information will be retained in two columns, cav_type and cav_response. The following tables list the possible response codes that may appear in these columns. If you have subscribed to the SafeScan service, you will receive SafeScan responses as well as QuickMatch responses. If you have subscribed to the SafeScanID service, you will receive both SafeScan and SafeScanID responses. Page 6 of 37

13 7.3.1 QuickMatch RESPONSE MESSAGES Equifax Reason Code Condition Table 1: Credit File Reason Codes Definition Success / / 100 No Record Found (No - Hit) Unable to verify information complete more information on application and resubmit. 101 Subject Reported as Deceased Death Notice on File. 102 Contact Bureau for Manual File Unable to verify Information. You may get this message if a file is too long or under court-ordered review and monitoring. 110 Top Priority Locate Collection agency has tagged file for locate if a new address is updated on file. 111 BC/Alberta Locate Collection agency has tagged file for locate if a new address is updated on file. 112 Inquiry Alert Collection agency has tagged file for locate if a new address is updated on file. 113 Alert Service Collection agency has tagged file for locate if a new address is updated on file. 114 File Incomplete - Contact Bureau for Additional Information Unable to verify information. The file may be too long or under court ordered review and monitoring. 115 National Locate Collection agency has tagged file for locate if a new address is updated on file. 116 Local Locate Collection agency has tagged file for locate if a new address is updated on file. 117 Interbureau Locate Collection agency has tagged file for locate if a new address is updated on file. 118 Contact Bureau/Collection Department for Further Details An agency cannot locate person possible high risk of fraud 119 Lost or Stolen Wallet or Identification This person has reported their identification lost or stolen. 120 Returned Mail Locate Collection agency has tagged file for locate if a new address is updated on file. Page 7 of 37

14 Table 2: Credit Card Reason Codes Credit Card reason codes may be affected by the Service Version being implemented. Please refer to Service Versions for more information. Equifax Reason Code Condition Definition Success/ / 200 No Credit Card Given for Verification No credit card given for verification 201 No Match Found on Credit Card Equifax unable to match credit card. 204 Account Inactive Credit card not used for several months and flagged as inactive by the card issuer. 205 Lost or Stolen Card The bank has closed the credit card and deemed it stolen or lost i.e. card is no longer valid. 210 Included in Bankruptcy The credit card number provided is closed and included in a consumer bankruptcy; 211 Closed at Consumer Request The credit card number provided has been closed by the consumer. 212 Closed by Credit Grantor The credit card number provided has been closed by the credit grantor or bank; 213 Transferred Means credit card number provided is closed, as the card was transferred to a new credit card number. 214 Inactive Account The credit card number provided has been closed by the credit grantor or bank; i.e., card is not valid. 215 Written Off The credit card number provided has been closed by the credit grantor or bank and closed as bad debt; i.e., card is not valid Credit Card Number Mismatch Credit card type submitted for verification (Visa, M/C, etc.) matches the card type on file, but the number is different Credit Card Match Success Page 8 of 37

15 Table 3: Address Reason Codes Address reason codes may be affected by the Service Version being implemented. Please refer to Service Versions for more information. Equifax Reason Code Condition Definition Success / / 2300 Address Mismatch Address on file does not match address submitted for verification Address Match Success 1300 Score Based on Former Address 1301 * * *1306 Input Current Address matches Current Address on consumer File Input Former Address matches Current Address on consumer File Input Current Address matches Former Address on consumer file Input Former Address matches Former Address on consumer file Input Current Address matches Previous Former Address on file Input Former Address matches Previous Former Address on consumer file *Input Former address capability not yet available. The address provided for verification matches a former address on file. This code will not be returned by Service Version 1.0. Service version 1.1 and later will always return a 1300 code when a 2307 address match or a 9307 address comparison match is returned. These codes will not be returned by Service Version 1.0. Service version 1.1 and later will always return a 1300 code when a 2307 address match or a 9307 address comparison match is returned. Table 4: Date of Birth Reason Codes Success Success Success Success Success Success Date of Birth reason codes may be affected by the Service Version being implemented. Please refer to Service Versions for more information. Equifax Reason Code Condition Definition 9000 Date of Birth Mismatch Date of birth on file does not match date of birth submitted for verification Date of Birth Match Date of birth on file matches the date submitted for verification. This code is available through Service Version 1.2 only Date of Birth Not Returned No date of birth returned by Equifax. This code is available through Service Version 1.2 only. Success / / Success Page 9 of 37

16 Equifax Reason Code SafeScan RESPONSE MESSAGES Condition 0 Inquiry has been passed through SafeScan. No fraud indication was detected Table 5: SafeScan Response Messages Definition 1 Possible true name fraud Identity supplied on application has shown possible fraud has been detected, and verification is required. Success / / Success 2 Inquiry social insurance number has been associated with more than one name or address 3 Social Insurance Number reported retired 4 Inquiry Business Telephone Number reported misused 5 Social Insurance Number reported misused 6 Inquiry address has been associated with more than one name or Social Insurance Number 7 Inquiry address is detention centre 8 Inquiry address is a mail drop 9 Inquiry address reported misused Identifies Social Insurance Numbers that are associated with multiple names and addresses. Social Insurance Number belongs to a person who is deceased. Business telephone number entered has been used in possible fraud perpetration. SIN entered has been used in actual fraud perpetration. Identifies profiled addresses associated with multiple names and Social Insurance Numbers. Address entered is a federal or provincial prison or detention centre. Address entered is a mail drop location. Address entered has been used in possible fraud perpetration. A Inquiry address is a post office Address entered is a post office. Address is identified by actual post office location or unique post office box postal code. B Inquiry residential telephone number reported misused Residential telephone number entered has been used in possible fraud perpetration. C Inquiry residential telephone number is a public paytelephone Residential telephone number entered is a public pay telephone. D Inquiry business telephone number is a public paytelephone Business telephone number entered is a public pay telephone. E Inquiry address is high risk for fraud Page 10 of 37

17 Equifax Reason Code Condition Definition Success / / F Inquiry social insurance number has been reported lost or stolen G Inquiry telephone number has been associated with more than one name or address Identifies telephone numbers that are associated with multiple names and addresses. H Inquiry address reported misused confirmed true name fraud I Inquiry social insurance number reported misused confirmed true name fraud J Inquiry address does not match the credit file address K Inquiry/credit file address is new within 30 days L Inquiry residential telephone number reported misused confirmed true name fraud M Confirmed true name fraud N P Q R T U V Inquiry social insurance number is invalid Inquiry residential telephone number is a cellular Inquiry social insurance number has not yet been issued Inquiry telephone number is a hotel/motel Identification reported lost or stolen Inquiry address is a hotel/motel Inquiry business telephone number is a cellular Inquiry credit card account has been reported lost or stolen Page 11 of 37

18 7.3.3 SafeScan ID RESPONSE MESSAGES Table 6: SafeScan ID Response Messages Equifax Reason Code Condition Definition Success / / 0 Inquiry has been passed through SafeScan ID. No fraud indication was detected A Match 2 out of 3 address components Match on name, address, residential telephone number Telephone is listed as residential and name and address match but only 2 of 3 (Civic, Street, City) match Success C Residential Address/Telephone Match; Telephone Listed As Business Address provided matches with telephone listing but telephone is listed as business D Mismatch - Residential Address/Telephone; Telephone Listed As Business Telephone is listed as business phone and address provided does not match telephone-listing address E Mismatch - Residential Address/Telephone; Telephone Listed As Residential Telephone is listed as residential and name provided matches with listing but address provided does not match telephone address listing F Residential Telephone Cannot Be Verified Unable to verify and cross reference with telephone listing H Mismatch name, telephone listed as residential Telephone is listed as residential and address matches BUT name does not match I Mismatch - Residential Address/Telephone, Name/Telephone, Year of Birth; Telephone Listed as Residential Telephone is residential - Address provided does not match telephone-listing address, name provided does not match with Telephone listing, Year of birth provided does not match. J Mismatch - Residential Address/Telephone, Name/Telephone; Telephone Listed as Residential Telephone is residential but address provided does not match telephone-listing address, name provided does not match with Telephone listing K Mismatch - Residential Address/Telephone, Year of Birth; Telephone Listed as Residential Telephone is residential and name matches with phone listing but address provided does not match telephone-listing address, Year of birth provided does not match Page 12 of 37

19 Equifax Reason Code Condition Definition Success / / L Mismatch - Residential Name/Telephone, Year of Birth; Telephone Listed as Residential Telephone is residential and address provided matches with listing, but name provided does not match with Telephone listing, Year of birth provided does not match N Mismatch - Residential Address/Telephone, Year of Birth; Telephone Listed as Business Telephone is listed as business but address provided does not match telephone-listing address, and Year of birth provided does not match O Mismatch - Year of Birth; Residential Telephone Cannot Be Verified Year of birth does not match and the phone number provided can not be verified P Match - res tel exchange/postal code, telephone number not found Phone number can not be verified but phone number provided does match the postal code High Q Match - res tel exchange/postal code, telephone number not found mismatch - year of birth Phone number can not be verified but phone number provided does match the postal code R Mismatch - Residential Telephone Number/Postal Code Telephone is listed as residential, name provided matches with listing, but address does not fall within geographical location S Mismatch - Year of Birth, Residential Telephone Number/Postal Code Year of birth does not match and residential telephone number provided does not match or fall with in the same geographical location T Mismatch - Year of Birth Everything matches except year of birth Page 13 of 37

20 8 CAV INTEGRATION PROCEDURES You must include the following information in your integration: Table 7: CAV Integration Procedures Service Quick Match SafeScan SafeScanID Required Variables Credit card number Customer name Billing address: civic number, street name, city, province, country, postal code Credit Card number Customer name Billing address: civic number, street name, city, province, country, postal code Date of birth SIN number (optional customers cannot be required by law to provide a SIN) Credit Card number Customer name Billing address: civic number, street name, city, province, country, postal code Date of birth SIN number (optional customers cannot be required by law to provide a SIN) Customer telephone number Note: Although QuickMatch does not require date of birth, billing phone number, or SIN validation, these variables must be included in the XML message even if empty (e.g. <month></month>). 8.1 SERVICE VERSIONS Beanstream currently provides three CAV Service Versions. If no Service Version tag is passed the system will assume a version of 1.0. To obtain the most recent enhancements to our system, we advise all merchants to integrate using the highest Service Version. Version 1.0 Only one credit card and address response code will be returned. Once a customer s credit card and address have been validated, a date of birth comparison will be performed. If all three validations are performed successfully, an address match code will be returned. If the date of birth comparison fails, the address match code will be replaced with a date of birth mismatch code. Please refer to the following sample response message: Page 14 of 37

21 <cavresponse> <responsecode>1</responsecode> <transactionid> </transactionid> <result>failed</result> <creditcardcode>2299</creditcardcode> <addresscode>2307</addresscode> <sscode> <sscode1>0</sscode1> </sscode> <ssidcode>r</ssidcode> <status></status> </cavresponse> Version 1.1 Up to four credit card and address responses will be returned. Once a customer s credit card and address have been validated, a date of birth comparison will be performed. If the date of birth comparison fails, the address match code will be replaced with a date of birth mismatch code. Please refer to the following sample response message: <cavresponse> <responsecode>1</responsecode> <transactionid> </transactionid> <result>failed</result> <creditcardcode> <creditcardcode1>2299</creditcardcode1> </creditcardcode> <addresscode> <addresscode1>2307</addresscode1> <addresscode2>1301</addresscode2> </addresscode> <sscode> <sscode1>0</sscode1> </sscode> <ssidcode>r</ssidcode> <status></status> </cavresponse> Version 1.2 Up to four credit card and address response codes will be returned. A date of birth response code will be included as a separate response code and will not replace the credit card and address match response code. Individual response codes are used to indicate if there is a DOB match, or mismatch. A third code is used when Equifax does not return a date of birth. Please refer to the following sample response message: Page 15 of 37

22 <cavresponse> <responsecode>1</responsecode> <transactionid> </transactionid> <result>failed</result> <birthdatecode>9001</birthdatecode> <creditcardcode> <creditcardcode1>2299</creditcardcode1> </creditcardcode> <addresscode> <addresscode1>2307</addresscode1> <addresscode2>1301</addresscode2> </addresscode> <sscode> <sscode1>0</sscode1> </sscode> <ssidcode>r</ssidcode> </cavresponse> 8.2 SUBMITTING A STAND-ALONE REQUEST You can interface with the CAV API using ASP Script querystring variables ASP SCRIPT The ASP script can be passed to this URL: Customer information is passed via an XML message, which is then passed into the ASP script through a querystring or form variable called input_xml. Example of the requesting XML message: Page 16 of 37

23 <?xml version="1.0"?> <cavrequest> <serviceversion>1.2</serviceversion> <merchantid> </merchantid> <passcode>8g35v47gc6tn9k2exgtgsqlhh9uj9dc7</passcode> <name> <first>rheal</first> <middle></middle> <last>dumont</last> </name> <phone></phone> <address> <number>1545</number> <street>delia Cres</street> <city>orleans</city> <province>on</province> <postal>k4a2y1</postal> </address> <creditcard> </creditcard> <dob> <month>02</month> <day>19</day> <year>1957</year> </dob> <sin> </sin> </cavrequest> The <merchantid> tag must contain your Beanstream merchant ID. The province must be a two-letter province code. The ASP script will return an XML message that contains: The response code. This will be 1 if the CAV was processed, or a negative value if CAV could not be processed. The transaction ID in the <transactionid> tag. This is used as a debugging reference only. The result (Passed or Failed) in the <result> tag Details from Equifax: the QuickMatch response codes in the <creditcardcode> and <addresscode> tags, and SafeScan/SafeScanID response codes in the <sscode> and <ssidcode> tags, respectively. The HTTP status code in the <status> tag. This code should always be 200, which indicates that the connection with the Equifax server was successful. The file number of the cardholder s credit report with Equifax will also be returned if this feature has been enabled on your account. The file number is 13 characters in length and is alpha numeric with two dash separators. Example To add this feature, please contact: support@beanstream.com Page 17 of 37

24 The following is an example of the response XML message: <?xml version="1.0"?> <cavresponse> <responsecode>1</responsecode> <transactionid> </transactionid> <result>failed</result> <birthdatecode>9001</birthdatecode> <creditcardcode> <creditcardcode1>2299</creditcardcode1> </creditcardcode> <addresscode> <addresscode1>2307</addresscode1> <addresscode2>1301</addresscode2> </addresscode> <sscode> <sscode1>0</sscode1> </sscode> <ssidcode>r</ssidcode> </cavresponse> Refer to Response XML Message for a document type declaration of the response XML message. Beanstream added a new feature: the option to send a secondary Canadian Address Verification (CAV) request for a failed eidcompare. This new option contains the following features: works only in the XML interface a new response code: -17 for Invalid eid transaction id (see Table 11: Response Codes) a new request parameter named eidtransaction which must be the numerical transaction ID from a valid eidverify or eidcompare transaction If you pass eidtransaction in the request, then: o o o All required consumer information for the CAV request is pulled from the associated eid transaction and anything else that may have been passed in the request is ignored. The response will only include the following parameters (all others are suppressed): responsecode transactionid provincematch The new provincematch parameter will be returned populated with a 1 if there is a province match between the province that was submitted in the original eid transaction and the address returned from the CAV request. Otherwise, this parameter is set to 0. Page 18 of 37

25 Example of a successful XML request, using the new parameter: <?xml version="1.0" encoding="us-ascii" standalone="yes"?> <cavrequest> <serviceversion>1.1</serviceversion> <merchantid> </merchantid> <eidtransaction> </eidtransaction> </cavrequest> Example of a successful XML response message: <cavresponse> <responsecode>1</responsecode> <transactionid> </transactionid> <provincematch>1</provincematch> </cavresponse> Example of a failed XML request message: <?xml version="1.0" encoding="us-ascii" standalone="yes"?> <cavrequest> <serviceversion>1.1</serviceversion> <merchantid> </merchantid> <eidtransaction> </eidtransaction> </cavrequest> Example of a failed XML response message that includes the new response code: <cavresponse> <responsecode>-17</responsecode> <transactionid>0</transactionid> <provincematch>0</provincematch> </cavresponse> 8.3 RESPONSE CODES If an error occurs that prevents CAV from querying the Equifax server, the <responsecode> tag will contain a number other than 1. In this case, no entry will be written to the transaction log. Additional response codes may be added without notification and the merchant system must expect this. Table 8: Response Codes Response Code Explanation 1 The CAV request has successfully processed. -1 Service not configured for this merchant ID. Ensure that the merchant ID passed in the request XML message is correct. -2 Settings not configured for the passed merchant ID. Ensure that the merchant ID passed in the request XML message is correct. -3 Incorrectly formatted card number (e.g., insufficient number of digits in the credit card number). Ensure that the credit card number passed in the request XML message is correct. -4 Incorrectly formatted postal code. Ensure that the postal code passed in the request XML message is correct. Page 19 of 37

26 Response Code Explanation -5 Incorrectly formatted social insurance number. Ensure that the SIN passed in the request XML message is correct. -6 Incorrectly formatted date of birth. Ensure that the DOB passed in the request XML message is correct. -7 Incorrectly formatted phone number (e.g. incorrect number of digits). Ensure that the phone number passed in the request XML message is correct. -8 Internal application error -9 Invalid merchant ID. Ensure that the merchant ID passed in the request XML message is correct. -10 Request has reached the limit on the number of CAV attempts against the card number. This CAV transaction limit is set in the Beanstream membership area. See Configuration & Administration for details. -11 The CAV service is unavailable due to a communication failure to Equifax or due to Equifax temporarily declining CAV requests. The user should be requested to try their request again later. -12 Invalid passcode. Ensure the correct passcode passed in the request XML message. -13 Incorrectly formatted last name. This error occurs if the last name passed in the request XML message is missing or is less than 2 characters. -14 Missing XML message. Ensure that an XML request message was passed. -15 Could not parse the XML message. Ensure the XML request message is valid. -17 Invalid eid transaction ID. -18 Invalid merchant account status. If the number of CAV attempts for a credit card has exceeded the merchant-defined limit, the response XML message will return a response code of -10, but the <result> tag will contain Failed and all of the response codes will be 0. The following is an example of this: <?xml version="1.0" encoding="us-ascii" standalone="yes"?> <cavresponse> <responsecode>-10</responsecode> <transactionid> </transactionid> <result>failed</result> <creditcardcode> <creditcardcode1>0</creditcardcode1> <creditcardcode> <addresscode> <addresscode1>0</addresscode1> <addresscode> <sscode> <sscode1>0</sscode1> </sscode> <ssidcode>0</ssidcode> </cavrequest> Page 20 of 37

27 8.4 SUBMITTING THE REQUEST WITH A TRANSACTION All transactions submitted through the Process Transaction API will automatically perform CAV when processing a monetary transaction if this option is enabled. To enable CAV, use the CAV Enabled option and Require CAV On All Transactions option as described in Configuration & Administration. If the Require CAV On All Transactions option is off, then the Process Transaction API will not perform CAV by default. To make the Process Transaction API perform CAV for a particular transaction, a parameter called enablecav=1 needs to be passed. For example, the sample transaction request script (found in the Process Transaction API document) would be modified to the following (note the enablecav variable at the end of the string): es%2forder_form.asp&merchant_id= &trncardowner=paul+randal&trncardnum ber= &trnexpmonth=09&trnexpyear=05&trnordernumber=2232&trnamou nt=10.00&ord address=prandal@mydomain.net&ordname=paul+randal&ordphonenum ber= &ordaddress1=1045+main+street&ordaddress2=&ordcity=vancouver&ordpr ovince=bc&ordpostalcode=v8r+1j6&ordcountry=ca&enablecav=1 If the CAV passes, the transaction will proceed as usual. The return parameter messageid will return a response code indicating that the credit card has been approved or declined. If CAV fails, the transaction is not processed. The return parameter messageid returns a response code of 215, which maps to the messagetext Address Validation Failed. These CAV specific response parameters will be returned in addition to the standard response parameters passed to the approve/decline page. For a list of standard parameters, refer to the document titled Process Transaction API. Table 9: CAV with Transaction -- Request Parameters Variable Name Data Type Description spcodecav Numeric This parameter will contain one of the response codes detailed in Response Codes. rspcavresult Numeric Set to 1 if address validation has passed. Set to 0 if address validation has failed. rspcodecredit Numeric Status of the credit card number matching against the cardholder credit record. See Response Codes. rspcodeaddr Numeric Status of the cardholder name and address matching against a credit record. See Response Codes. rspcodesafescan String SafeScan verification response. One to twenty response codes may be returned in this parameter. Multiple codes are appended with no separator. See Response Codes. rspcodesafescanid String SafeScanId verification response. See Response Codes. Page 21 of 37

28 9 PROVINCE CODES This table lists the valid province codes that CAV accepts: Two-letter Code Province AB BC MB NB NL NT NS NU ON PE QC SK YT Alberta British Columbia Manitoba New Brunswick Newfoundland and Labrador Northwest Territories Nova Scotia Nunavut Ontario Prince Edward Island Quebec Saskatchewan Yukon Page 22 of 37

29 10 XML MESSAGE DEFINITIONS 10.1 INPUT XML MESSAGE The following is the document type declaration of the input XML message that is passed to the stand-alone API: <!DOCTYPE cavrequest [ <!ELEMENT cavrequest (serviceversion,merchantid,name,phone,address,creditcard,dob,sin)> <!ELEMENT serviceversion (#PCDATA)> <!ELEMENT merchantid (#PCDATA)> <!ELEMENT passcode (#PCDATA)?> <!ELEMENT name (first,middle,last)> <!ELEMENT phone (#PCDATA)?> <!ELEMENT address (number,street,city,province,postal)> <!ELEMENT creditcard (#PCDATA)> <!ELEMENT dob (month,day,year)?> <!ELEMENT sin (#PCDATA)?> <!ELEMENT first (#PCDATA)> <!ELEMENT middle EMPTY> <!ELEMENT last (#PCDATA)> <!ELEMENT number (#PCDATA)> <!ELEMENT street (#PCDATA)> <!ELEMENT city (#PCDATA)> <!ELEMENT province (#PCDATA)> <!ELEMENT postal (#PCDATA)> <!ELEMENT month (#PCDATA)> <!ELEMENT day (#PCDATA)> <!ELEMENT year (#PCDATA)> ]> Page 23 of 37

30 10.2 RESPONSE XML MESSAGE The following is the document type declaration of the response XML message that the stand-alone API will return: <!DOCTYPE cavresponse [ <!ELEMENT cavresponse (responsecode,transactionid,result,birthdatecode,creditcardcode,addresscode,s scode,ssidcode)> <!ELEMENT responsecode (#PCDATA)> <!ELEMENT transactionid (#PCDATA)> <!ELEMENT result (#PCDATA)> <!ELEMENT birthdatecode (#PCDATA)> <!ELEMENT creditcardcode (creditcardcode1,creditcardcode2?,creditcardcode3?,creditcardcode4?)> <!ELEMENT creditcardcode1 (#PCDATA)> <!ELEMENT creditcardcode2 (#PCDATA)> <!ELEMENT creditcardcode3 (#PCDATA)> <!ELEMENT creditcardcode4 (#PCDATA)> <!ELEMENT addresscode (addresscode1,addresscode2?,addresscode3?,addresscode4?)> <!ELEMENT addresscode1 (#PCDATA)> <!ELEMENT addresscode2 (#PCDATA)> <!ELEMENT addresscode3 (#PCDATA)> <!ELEMENT addresscode4 (#PCDATA)> <!ELEMENT sscode (sscode1?,sscode2?,sscode3?,sscode4?,sscode5?,sscode6?,sscode7?,sscode8?,ssco de9?,sscode10?,sscode11?,sscode12?,sscode13?,sscode14?,sscode15?,sscode16?,ss code17?,sscode18?,sscode19?,sscode20?)> <!ELEMENT sscode1 (#PCDATA)> <!ELEMENT sscode2 (#PCDATA)> <!ELEMENT sscode3 (#PCDATA)> <!ELEMENT sscode4 (#PCDATA)> <!ELEMENT sscode5 (#PCDATA)> <!ELEMENT sscode6 (#PCDATA)> <!ELEMENT sscode7 (#PCDATA)> <!ELEMENT sscode8 (#PCDATA)> <!ELEMENT sscode9 (#PCDATA)> <!ELEMENT sscode10 (#PCDATA)> <!ELEMENT sscode11 (#PCDATA)> <!ELEMENT sscode12 (#PCDATA)> <!ELEMENT sscode13 (#PCDATA)> <!ELEMENT sscode14 (#PCDATA)> <!ELEMENT sscode15 (#PCDATA)> <!ELEMENT sscode16 (#PCDATA)> <!ELEMENT sscode17 (#PCDATA)> <!ELEMENT sscode18 (#PCDATA)> <!ELEMENT sscode19 (#PCDATA)> <!ELEMENT sscode20 (#PCDATA)> <!ELEMENT ssidcode (#PCDATA)> <!ELEMENT status ( #PCDATA ) > ]> Page 24 of 37

31 11 TRANSACTION MESSAGE XML SCHEMA 11.1 REQUEST MESSAGE <?xml version="1.0" encoding="utf-16"?> <xsd:schema attributeformdefault="unqualified" elementformdefault="qualified" version="1.0" xmlns:xsd=" <xsd:element name="cavrequest"> <xsd:complextype> <xsd:sequence> <xsd:element name="serviceversion" type="xsd:decimal" /> <xsd:element name="merchantid" type="xsd:int" /> <xsd:element name="passcode" type="xsd:string" /> <xsd:element name="name"> <xsd:complextype> <xsd:sequence> <xsd:element name="first" type="xsd:string" /> <xsd:element name="middle" type="xsd:string" /> <xsd:element name="last" type="xsd:string" /> </xsd:sequence> </xsd:complextype> </xsd:element> <xsd:element name="phone" type="xsd:string" /> <xsd:element name="address"> <xsd:complextype> <xsd:sequence> <xsd:element name="number" type="xsd:string" /> <xsd:element name="street" type="xsd:string" /> <xsd:element name="city" type="xsd:string" /> <xsd:element name="province" type="xsd:string" /> <xsd:element name="postal" type="xsd:string" /> </xsd:sequence> </xsd:complextype> </xsd:element> <xsd:element name="creditcard" type="xsd:string" /> <xsd:element name="dob"> <xsd:complextype> <xsd:sequence> <xsd:element name="month" type="xsd:int" /> <xsd:element name="day" type="xsd:int" /> <xsd:element name="year" type="xsd:int" /> </xsd:sequence> </xsd:complextype> </xsd:element> <xsd:element name="sin" type="xsd:string" /> </xsd:sequence> </xsd:complextype> </xsd:element> </xsd:schema> Page 25 of 37

32 11.2 RESPONSE MESSAGE <?xml version="1.0" encoding="utf-16"?> <xsd:schema attributeformdefault="unqualified" elementformdefault="qualified" version="1.0" xmlns:xsd=" <xsd:element name="cavresponse"> <xsd:complextype> <xsd:sequence> <xsd:element name="responsecode" type="xsd:int" /> <xsd:element name="transactionid" type="xsd:int" /> <xsd:element name="result" type="xsd:string" /> <xsd:element name="birthdatecode" type="xsd:int" /> <xsd:element name="creditcardcode"> <xsd:complextype> <xsd:sequence> <xsd:element name="creditcardcode1" type="xsd:int" /> <xsd:element name="creditcardcode2" type="xsd:int" /> <xsd:element name="creditcardcode3" type="xsd:int" /> <xsd:element name="creditcardcode4" type="xsd:int" /> </xsd:sequence> </xsd:complextype> </xsd:element> <xsd:element name="addresscode"> <xsd:complextype> <xsd:sequence> <xsd:element name="addresscode1" type="xsd:int" /> <xsd:element name="addresscode2" type="xsd:int" /> <xsd:element name="addresscode3" type="xsd:int" /> <xsd:element name="addresscode4" type="xsd:int" /> </xsd:sequence> </xsd:complextype> </xsd:element> <xsd:element name="sscode"> <xsd:complextype> <xsd:sequence> <xsd:element name="sscode1" type="xsd:int" /> <xsd:element name="sscode2" type="xsd:int" /> <xsd:element name="sscode3" type="xsd:int" /> <xsd:element name="sscode4" type="xsd:int" /> <xsd:element name="sscode5" type="xsd:int" /> <xsd:element name="sscode6" type="xsd:int" /> <xsd:element name="sscode7" type="xsd:int" /> <xsd:element name="sscode8" type="xsd:int" /> <xsd:element name="sscode9" type="xsd:int" /> <xsd:element name="sscode10" type="xsd:int" /> <xsd:element name="sscode11" type="xsd:int" /> <xsd:element name="sscode12" type="xsd:int" /> <xsd:element name="sscode13" type="xsd:int" /> <xsd:element name="sscode14" type="xsd:int" /> <xsd:element name="sscode15" type="xsd:int" /> <xsd:element name="sscode16" type="xsd:int" /> <xsd:element name="sscode17" type="xsd:int" /> <xsd:element name="sscode18" type="xsd:int" /> <xsd:element name="sscode19" type="xsd:int" /> <xsd:element name="sscode20" type="xsd:int" /> </xsd:sequence> </xsd:complextype> </xsd:element> <xsd:element name="ssidcode" type="xsd:string" /> Page 26 of 37

33 12 CAV BATCH PROCESSING CAV requests can be submitted via Beanstream's batch processing service. Files containing consumer address and personal information can be submitted through the batch processing interface for validation. Consumer information is then validated against their credit file. Files are uploaded to the CAV Batch Service where they are they processed and recorded to the account where results can be downloaded for analysis. All file processing will occur after end of day (11:59 pm PST) on the day the file was submitted. Results of the file will be available for viewing next day by 10:00 am PST CREATING A CAV BATCH FILE The following table describes the fields required to create a CAV batch file. Please ensure that you use the fields which pertain to the service you have enabled. Field Name Data Type Max Size QM SS SSID The name of the field in the batch file A=Alphanumeric N=Numeric The maximum number of characters or digits permitted in the field O=optional for QuickMatch, R=required for QuickMatch O=optional for SafeScan, R=required for SafeScan O=optional for SafeScan ID, R=required for SafeScan ID Table 10: CAV Batch Files -- Required Fields Field Name Data Type Max Length QM SS SSID Description Reference Number A 10 O O O Merchant reference number First Name A 15 R R R Consumer first name Middle Name A 15 O O O Consumer middle name Last Name A 25 R R R Consumer last name Card Number A 16 R R R Credit card number House Number N 10 O O O Street Name A 25 R R R House number of the consumer s home address. If the house number is not provided the system will try to parse the house number and street from the street name field. The street name of the consumer s home address. Page 27 of 37

34 Field Name Data Type Max Length City A 20 R R R Province A 2 R R R Postal Code A 6 R R R Phone Number A 10 O R R QM SS SSID Description The city of the consumer s home address. The province of the consumer s home address. The postal code of consumer s home address. The consumer s home phone number. Birth Date N 8 O R R The consumer s birth date. Formatted as MMDDYYYY. Example: March 27th, 1964 would be formatted as SIN N 9 - O O The consumer s social insurance number UPLOADING A CAV BATCH FILE Go to processing> batch CAV in the left menu. The following screen will appear with a list of all of the batch files you have created in the past. 1. Use the Browse button to locate the file you have created. When you have selected the correct file, click Open. 2. Click the Upload button to send your batch file to the Beanstream server and schedule your request 3. Once the file has finished uploading, a green checkmark will appear in the State column. This indicates that the file has uploaded successfully. Page 28 of 37

35 APPENDIX: TEST DATA Test Case A Test Case B Test Case C Test Case D First Name Gary William Chantal Clifford Last Name Cyr Gladish Lanteigne Ely Phone Number House Number Street Name GERTRUDE AV APT 311 Macro Ln Langbrae Dr Apt 118 Hincks City Winnipeg Ottawa Halifax Goderich Province MB ON NS ON Postal Code R3L0M5 K1S5A1 B3M4L2 N7A3A5 Credit Card Number Birth Date (mm/dd/yy) /02/1959 3/28/1955 9/23/ /22/1975 SIN QuickMatch Credit Card QuickMatch Address SafeScan 0 B - B A SafeScanId R E - Page 29 of 37