CAV USER GUIDE. Document Version 3.1. November 2013

Transcription

1 CAV USER GUIDE Document Version 3.1 November 2013 For further information please contact Beanstream customer support at (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 SOAP 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 Sample SOAP Client Script -- CAV_XML Method Sample SOAP Client Script CAV Method Page 2 of 51 11/29/2013

3 14 CAV Batch Processing Creating a CAV Batch File Uploading a CAV Batch File Appendix: Test data Page 3 of 51 11/29/2013

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

5 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 5 of 51 11/29/2013

6 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 also 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 may choose to use these services in any of the following 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. Please 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. Page 6 of 51 11/29/2013

7 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 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 will be able to return SIN-related response codes, such as Social Insurance Number reported misused and Social Insurance Number reported retired. If SIN is not provided, SafeScan will still return all of the 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 Page 7 of 51 11/29/2013

8 telephone number matches the applicants name and address. For this service please see SafeScanID below. 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 8 of 51 11/29/2013

9 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 (a standalone CAV request) the merchant can post data directly to the CAV API. In this scenario, the steps are as follows: 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 Page 9 of 51 11/29/2013

10 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. 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, Server to Server or SOAP 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. Page 10 of 51 11/29/2013

11 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 11 of 51 11/29/2013

12 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 12 of 51 11/29/2013

13 All configuration options for the type of service you have selected are displayed on this page. CAV-Enabled Flag 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. Require CAV on all Transactions 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. Limit CAV Attempts Access Pass Code Warning Flags 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 13 of 51 11/29/2013

14 7 VIEWING CAV TRANSACTION DETAILS You can view detailed results for each CAV transaction using Beanstream s Transaction Report Module. 1. Go to Reporting Analysis Transaction Report in the left menu of the membership page. 2. Use the dropdown menus at the top of the page to set the reporting parameters of your choice. 3. Select the Refresh button at the bottom of the page 7.1 REVIEWING CAV SUMMARY INFORMATION Figure 1: Sample Transaction Report The Transaction Report will contain a checkmark if a transaction has been processed using QuickMatch, SafeScan or SafeScan ID. Credit card transactions that have been 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 Page 14 of 51 11/29/2013

15 Canadian Address Verification. On the other hand, the first transaction listed in this example was not processed with CAV therefore the code in this column is just P. Please note that 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. 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). The following screen will appear: 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 Page 15 of 51 11/29/2013

16 well as QuickMatch responses. If you have subscribed to the SafeScanID service, you will receive both SafeScan and SafeScanID responses QuickMatch RESPONSE MESSAGES Table 1: Credit File Reason Codes Equifax Reason Code Condition Definition Success / / Warning 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. Warning Warning Warning Warning Page 16 of 51 11/29/2013

17 Equifax Reason Code Condition Definition Success / / Warning 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. Warning Warning Warning 118 Contact Bureau/Collection Department for Further Details An agency can not 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. Warning Warning 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. Page 17 of 51 11/29/2013

18 Equifax Reason Code Condition Definition Success / / Warning 200 No Credit Card Given for Verification No credit card given for verification 201 No Match Found on Credit Card Equifax was unable to match credit card. 204 Account Inactive The credit card has not been used for several months and has been 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. Page 18 of 51 11/29/2013

19 Equifax Reason Code Condition Definition Success / / Warning 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 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 / / Warning 2300 Address Mismatch Address on file does not match address submitted for verification Address Match Success 1300 Score Based on Former Address 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 in the case where a 2307 address match or a 9307 address comparison match is returned. Warning Page 19 of 51 11/29/2013

20 Equifax Reason Code Condition Definition Success / / Warning 1301 Input Current Address matches Current Address on consumer File *1302 Input Former Address matches Current Address on consumer File 1303 Input Current Address matches Former Address on consumer file *1304 Input Former Address matches Former Address on consumer file 1305 Input Current Address matches Previous Former Address on file These codes will not be returned by Service Version 1.0. Service version 1.1 and later will always return a 1300 code in the case where a 2307 address match or a 9307 address comparison match is returned. Success Success Success Success Success *1306 Input Former Address matches Previous Former Address on consumer file Success *Input Former address capability not yet available. Table 4: Date of Birth Reason Codes 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 Success / / Warning 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 information submitted for verification. This code is available through Service Version 1.2 only. Success Page 20 of 51 11/29/2013

21 Equifax Reason Code Condition Definition Success / / Warning 9002 Date of Birth Not Returned No date of birth returned by Equifax. This code is available through Service Version 1.2 only. Warning SafeScan RESPONSE MESSAGES Table 5: SafeScan Response Messages Equifax Reason Code Condition Definition Success / / Warning 0 Inquiry has been passed through SafeScan. No fraud indication was detected 1 Possible true name fraud Identity supplied on application has shown possible fraud has been detected, and verification is required. 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 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 Page 21 of 51 11/29/2013

22 Equifax Reason Code Condition Definition Social Insurance Numbers. Success / / Warning 7 Inquiry address is detention centre Address entered is a federal or provincial prison or detention centre. 8 Inquiry address is a mail drop Address entered is a mail drop location. Warning 9 Inquiry address reported misused 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. Warning B Inquiry residential telephone number reported misused Residential telephone number entered has been used in possible fraud perpetration. C D Inquiry residential telephone number is a public paytelephone Inquiry business telephone number is a public paytelephone Residential telephone number entered is a public pay telephone.. Business telephone number entered is a public pay telephone. E Inquiry address is high risk for fraud 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. Warning Page 22 of 51 11/29/2013

23 Equifax Reason Code H Condition Inquiry address reported misused confirmed true name fraud Definition Success / / Warning I Inquiry social insurance number reported misused confirmed true name fraud J Inquiry address does not match the credit file address Warning K Inquiry/credit file address is new within 30 days Warning L Inquiry residential telephone number reported misused confirmed true name fraud M Confirmed true name fraud N Inquiry social insurance number is invalid P Inquiry residential telephone number is a cellular Warning Q Inquiry social insurance number has not yet been issued R Inquiry telephone number is a hotel/motel Identification reported lost or stolen T Inquiry address is a hotel/motel U Inquiry business telephone number is a cellular Warning V Inquiry credit card account has been reported lost or stolen Page 23 of 51 11/29/2013

24 7.3.3 SafeScan ID RESPONSE MESSAGES Table 6: SafeScan ID Response Messages Equifax Reason Code Condition Definition Success / / Warning 0 Inquiry has been passed through SafeScan ID. No fraud indication was detected Match on name, address, residential telephone number Success A Match 2 out of 3 address components Telephone is listed as residential and name and address match but only 2 of 3 (Civic, Street, City) match Warning 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 telephonelisting address Warning 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 Warning 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 Page 24 of 51 11/29/2013

25 Equifax Reason Code Condition Definition Success / / Warning 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 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 Warning Page 25 of 51 11/29/2013

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

27 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 Please note, that 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 they are 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 Page 27 of 51 11/29/2013

28 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>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 28 of 51 11/29/2013

29 <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 There are two ways of interfacing with the CAV API: ASP Script with querystring variables With SOAP 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. The following is an example of the requesting XML message: Page 29 of 51 11/29/2013

30 <?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 Page 30 of 51 11/29/2013

31 To add this feature, please contact: 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 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 Page 31 of 51 11/29/2013

32 o 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. The following is an 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> The following is an example of a successful XML response message: <cavresponse> <responsecode>1</responsecode> <transactionid> </transactionid> <provincematch>1</provincematch> </cavresponse> The following is an 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> The following is an 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 SOAP The Beanstream server also provides a SOAP web service so that merchants with SOAP capabilities can more easily integrate directly to the CAV service. It is located at: Page 32 of 51 11/29/2013

33 There are two methods of calling the SOAP Service to process a CAV transaction: the CAV method and the CAV_XML method. Both calling methods perform the same processing logic, with the only difference being the format in which the request is submitted and returned. The CAV_XML SOAP Method The CAV_XML method accepts an XML formatted request and returns an XML formatted response. The format of the XML request and response is the same as that detailed in XML Message Definitions. Function declaration and parameter description are detailed below: Table 8: CAV_XML (xmldocument) Request Parameters Variable Name Data Type Description xmldocument String XML-Formatted request containing all required cardholder data. See XML Message Definitions for formatting. The CAV SOAP Method The CAV method accepts multiple variables as parameters to pass request data and return the response. Function declaration and parameter description are detailed below: CAV(merchantId, reqfirstname, reqmiddlename, reqlastname, reqcardnumber, reqhousenumber, reqstreetname, reqcity, reqprovince, reqpostalcode, reqphonenumber, reqbirthmonth, reqbirthday, reqbirthyear, reqsin, rsptransid, rspresult, rspcodecredit, rspcodeaddr, rspcodesafescan, rspcodesafescanid) Table 9: CAV SOAP -- Request Parameters Request Parameters Variable Name Data Type Description serviceversion Numeric Service Versions 1.1 and 1.2 will return more than one QuickMatch response code. This value will default to version 1.0 if no data is entered. In this case, only one QuickMatch response code will be returned. Page 33 of 51 11/29/2013

34 Request Parameters Variable Name Data Type Description merchantid Numeric Beanstream assigned merchant Id reqfirstname String Cardholders first name reqmiddlename String Cardholders middle name reqlastname String Cardholders last name reqcardnumber String Cardholders card number reqhousenumber String Cardholder s house number. reqstreetname reqcity reqprovince reqpostalcode reqphonenumber reqbirthmonth reqbirthday reqbirthyear reqsin passcode String String String String String String String String String String Cardholder s current home address. If the address has an apartment or unit number associated with it, the format would be as follows: Bloor St Apt 123. Cardholder s city name. Cardholder s province (see Province Codes for a complete list). Cardholder s postal code. Cardholders home phone number. Phone number must be passed as a ten digit number. (i.e. 3 digit area code followed by 7 digit phone number). Numeric month of the cardholder s birth date. Numeric day of the cardholder s birth date. Four-digit numeric year of the cardholder s birth date. Cardholder s Social Insurance Number. A pass code is required if one is set in CAV configuration module in membership area. Page 34 of 51 11/29/2013

35 Table 10: CAV SOAP -- Response Parameters Response Parameters Variable Name Data Type Description rsptransid Numeric Eight-digit transaction id of the CAV record logged to the merchant transaction log. rspresult String Set to True if address validation has passed. Set to False if address validation has failed. rspcodecredit String Status of the credit card number matching against the cardholder credit record. With Service Version 1.1 and 1.2, more than one response code will be returned. Multiple codes are appended with separator. rspcodeaddr String Status of the cardholder name and address matching against a credit record. rspcodesafescan String SafeScan verification response. One to twenty response codes may be returned in this parameter. In Service Version 1.0 multiple codes are appended with no separator. In Service Version 1.1, multiple codes are appended with separator. rspcodesafescanid String SafeScanId verification response. The file number of the cardholder s credit report with Equifax may 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. The CAV method will return one of the response codes detailed in Response Codes. Refer to Sample SOAP Client Script -- CAV_XML Method and Sample SOAP Client Script CAV Method for sample Visual Basic projects that will act as SOAP clients to communicate with the Beanstream SOAP service. Page 35 of 51 11/29/2013

36 8.4 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 11: 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. -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 that the passcode passed in the request XML message is correct. Page 36 of 51 11/29/2013

37 Response Code Explanation -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 that the XML request message is valid XML. -17 Invalid eid transaction ID 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> 8.5 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): Page 37 of 51 11/29/2013

38 es%2forder_form.asp&merchant_id= &trncardowner=paul+randal&trncardnum ber= &trnexpmonth=09&trnexpyear=05&trnordernumber=2232&trnamou 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 will not be processed. The return parameter messageid will return a response code of 215 (which maps to the messagetext Address Validation Failed ). The following 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 12: 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 38 of 51 11/29/2013

39 9 PROVINCE CODES The following table lists the valid province codes that CAV will accept: 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 39 of 51 11/29/2013

40 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)> ]> 10.2 RESPONSE XML MESSAGE The following is the document type declaration of the response XML message that the stand-alone API will return: Page 40 of 51 11/29/2013

41 <!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 41 of 51 11/29/2013

42 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 42 of 51 11/29/2013