Canadian Address Verification Integration Guide

Transcription

CAV USER GUIDE
Document Version 3.3
March 2016
For further information contact Beanstream Customer Support: (888) 472-0811 or
[email protected].
CAV User Guide
1 TABLE OF CONTENTS
2
List of Tables and Figures ................................................................................ 3
3
Overview .......................................................................................................... 4
3.1
Getting Started .......................................................................................... 4
3.2
Navigation ................................................................................................. 4
4 The Canadian Address Verification Suite .......................................................... 5
4.1
QuickMatch ................................................................................................
4.2
SafeScan ....................................................................................................
4.3
SafeScanID ................................................................................................
5 Process Flows ..................................................................................................
5
6
6
1
5.1
Stand-Alone Request via the CAV API ........................................................ 1
5.2
Requests Made with a Credit Card Transaction .......................................... 2
6 Configuration & Administration ........................................................................ 3
7
Viewing CAV Transaction Details ...................................................................... 5
7.1
Reviewing CAV Summary Information ....................................................... 5
7.2
Reviewing Status and Response Messages ................................................ 6
7.3
CAV Reporting Download Response Messages ........................................... 6
7.3.1 QuickMatch Response Messages ................................................................... 7
7.3.2 SafeScan Response Messages ..................................................................... 10
7.3.3 SafeScan ID Response Messages ................................................................ 12
8 CAV Integration Procedures ........................................................................... 14
8.1
Service Versions ...................................................................................... 14
8.2
Submitting a Stand-Alone Request........................................................... 16
8.2.1 ASP Script ................................................................................................ 16
8.3
Response Codes ....................................................................................... 19
8.4
Submitting the Request With a Transaction ............................................. 21
9 Province Codes ............................................................................................... 22
10 XML Message Definitions ................................................................................ 23
10.1 Input XML Message .................................................................................. 23
10.2 Response XML Message ........................................................................... 24
11 Transaction Message XML Schema ................................................................. 25
11.1 Request Message ..................................................................................... 25
11.2 Response Message ................................................................................... 26
12 CAV Batch Processing .................................................................................... 27
12.1 Creating a CAV Batch File ......................................................................... 27
12.2 Uploading a CAV Batch File ...................................................................... 28
Appendix: Test data ............................................................................................. 29
Page 2 of 37
CAV User Guide
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................................................................................ 10
Table 6: SafeScan ID Response Messages ........................................................................... 12
Table 7: CAV Integration Procedures .................................................................................. 14
Table 11: Response Codes................................................................................................... 19
Table 12: CAV with Transaction -- Request Parameters ...................................................... 21
Table 13: CAV Batch Files -- Required Fields ....................................................................... 27
Figure 1: Sample Transaction Report .................................................................................... 5
Figure 2: Sample Transaction Details Page ........................................................................... 6
Page 3 of 37
CAV User Guide
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:
[email protected]
3.2 NAVIGATION
Log onto the Membership area at: https://www.beanstream.com/admin/sDefault.asp
Go to administration account settings CAV.
Page 4 of 37
CAV User Guide
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
CAV User Guide
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
•
date of birth (DOB) (optional)
•
home address
•
social insurance number (SIN) (optional)
•
credit card number
•
telephone number
Page 6 of 37
CAV User Guide
5 PROCESS FLOWS
5.1 STAND-ALONE REQUEST VIA THE CAV API
Merchant Website
Website
Proceed to Checkout
User shops
on website
Data is passed between
Beanstream
and the merchant for the
Quickmatch portion of the tx
Payment Form
1
Transaction
is complete
2
Data is passed between the merchant
and the 3d party for the credit card
processing portion of the tx
Purchase
Confirmation Page
Merchant displays an
"approved" or
"declined" message
based on the results of
the transaction
3d Party
Credit Card
Processing
Engine
Beanstream
Quickmatch
Engine
If Quickmatch is
successful, the
cc transaction is
processed.
Data is validated and
passed to Equifax
Equifax
Processing
Partner & Bank
Third-Party Credit Card Processing
Service
Beanstream Quickmatch 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
CAV User Guide
5.2 REQUESTS MADE WITH A CREDIT CARD TRANSACTION
Merchant Website
Website
Proceed to Checkout
Payment Form
Transaction
is complete
Merchant displays an
"approved" or
"declined" message
based on the results of
the transaction
User shops
on website
Data is passed between
Beanstream
and the merchant
Stop
Response is
reported back to
merchant, and cc
transaction is not
processed
Quickmatch
Unsuccessful
Beanstream
Quickmatch
Engine
Purchase
Confirmation Page
Beanstream
Credit Card
Processing
Engine
Quickmatch
Successful
If Quickmatch is
successful, the
cc transaction is
processed.
Data is validated and
passed to Equifax
Equifax
Beanstream Quickmatch Service
Processing
Partner & Bank
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
6 CONFIGURATION & ADMINISTRATION
CAV User Guide
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
CAV User Guide
All configuration options for the type of service you 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.
Require CAV on all Transactions
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.
Limit CAV Attempts
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.
Access Pass Code
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.
Warning Flags
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
7 VIEWING CAV TRANSACTION DETAILS
CAV User Guide
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
7.2 REVIEWING STATUS AND RESPONSE MESSAGES
CAV User Guide
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:
https://www.beanstream.com/samples/reporting.asp
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
CAV User Guide
7.3.1 QuickMatch RESPONSE MESSAGES
Table 1: Credit File Reason Codes
Equifax
Reason
Code
Condition
100
No Record Found (No - Hit)
Unable to verify information – complete
more information on application and
resubmit.
Failure
101
Subject Reported as
Deceased
Death Notice on File.
Failure
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.
Failure
110
Top Priority Locate
Collection agency has tagged file for locate
if a new address is updated on file.
Warning
111
BC/Alberta Locate
Warning
112
Inquiry Alert
Warning
113
Alert Service
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.
Failure
115
National Locate
Warning
116
Local Locate
Warning
117
Interbureau Locate
Warning
118
Contact Bureau/Collection
Department for Further
Details
An agency cannot locate person – possible
high risk of fraud
Failure
119
Lost or Stolen Wallet or
Identification
This person has reported their
identification lost or stolen.
Warning
120
Returned Mail Locate
Warning
Definition
Page 7 of 37
Success /
Failure /
Warning
CAV User Guide
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/
Failure
/Warning
200
No Credit Card Given for
Verification
No credit card given for verification
Failure
201
No Match Found on Credit
Card
Equifax unable to match credit card.
Failure
204
Account Inactive
Credit card not used for several months
and flagged as inactive by the card issuer.
Failure
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.
Failure
210
Included in Bankruptcy
The credit card number provided is closed
and included in a consumer bankruptcy;
Failure
211
Closed at Consumer
Request
The credit card number provided has been
closed by the consumer.
Failure
212
Closed by Credit Grantor
closed by the credit grantor or bank;
Failure
213
Transferred
Means credit card number provided is
closed, as the card was transferred to a
new credit card number.
Failure
214
Inactive Account
closed by the credit grantor or bank; i.e.,
card is not valid.
Failure
215
Written Off
closed by the credit grantor or bank and
closed as bad debt; i.e., card is not valid.
Failure
2200
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.
Failure
2299
Credit Card Match
Success
Page 8 of 37
CAV User Guide
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
Address on file does not match address
submitted for verification.
Success /
Failure /
Warning
2300
Address Mismatch
Failure
2307
Address Match
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 when a
2307 address match or a 9307 address
comparison match is returned.
Warning
1301
Input Current Address
matches Current Address
on consumer File
Success
*1302
Input Former Address
matches Current Address
on consumer File
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.
Success
Success
1303
matches Former Address on
consumer file
Success
*1304
matches Former Address on
consumer file
Success
1305
matches Previous Former
Address on file
Success
*1306
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 /
Failure /
Warning
9000
Date of Birth Mismatch
Date of birth on file does not match date of
birth submitted for verification.
Failure
9001
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.
Success
9002
Date of Birth Not
Returned
No date of birth returned by Equifax. This code
is available through Service Version 1.2 only.
Warning
Page 9 of 37
CAV User Guide
7.3.2 SafeScan RESPONSE MESSAGES
Table 5: SafeScan Response Messages
Equifax
Reason
Code
Condition
Definition
Success /
Failure /
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.
Failure
2
Inquiry social insurance
number has been
associated with more than
one name or address
Identifies Social Insurance Numbers that
are associated with multiple names and
addresses.
Failure
3
Social Insurance Number
reported retired
Social Insurance Number belongs to a
person who is “deceased”.
Failure
4
Inquiry Business Telephone
Number reported misused
Business telephone number entered has
been used in possible fraud perpetration.
Failure
5
Social Insurance Number
reported misused
SIN entered has been used in actual
fraud perpetration.
Failure
6
Inquiry address has been
associated with more than
one name or Social
Insurance Number
Identifies profiled addresses associated
with multiple names and Social Insurance
Numbers.
Failure
7
Inquiry address is detention
centre
Address entered is a federal or provincial
prison or detention centre.
Failure
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.
Failure
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.
Failure
C
Inquiry residential
telephone number is a
public paytelephone
Residential telephone number entered is
a public pay telephone.
Failure
D
Inquiry business telephone
number is a public
paytelephone
Business telephone number entered is a
public pay telephone.
Failure
E
Inquiry address is high risk
for fraud
Success
Failure
Page 10 of 37
CAV User Guide
Equifax
Reason
Code
Condition
Definition
Success /
Failure /
Warning
F
number has been reported
lost or stolen
G
Inquiry telephone number
has been associated with
more than one name or
address
H
Inquiry address reported
misused – confirmed true
name fraud
Failure
I
number reported misused –
confirmed true name fraud
Failure
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
Failure
M
Confirmed true name fraud
Failure
N
number is invalid
Failure
P
Inquiry residential
telephone number is a
cellular
Warning
Q
number has not yet been
issued
Failure
R
Inquiry telephone number is
a hotel/motel
Failure
Identification reported lost
or stolen
Failure
T
Inquiry address is a
hotel/motel
Failure
U
Inquiry business telephone
number is a cellular
Warning
V
Inquiry credit card account
has been reported lost or
stolen
Failure
Failure
Identifies telephone numbers that are
associated with multiple names and
addresses.
Page 11 of 37
Warning
CAV User Guide
7.3.3 SafeScan ID RESPONSE MESSAGES
Table 6: SafeScan ID Response Messages
Equifax
Reason
Code
Condition
Definition
Success /
Failure /
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
Failure
D
Mismatch - Residential
Address/Telephone;
Telephone Listed As
Business
Telephone is listed as business phone and
address provided does not match
telephone-listing address
Warning
E
Address/Telephone;
Telephone Listed As
Residential
name provided matches with listing but
telephone address listing
Warning
F
Residential Telephone
Cannot Be Verified
Unable to verify and cross reference with
telephone listing
Failure
H
Mismatch – name,
telephone listed as
residential
address matches BUT name does not
match
Failure
I
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.
Failure
J
Address/Telephone,
Name/Telephone;
Telephone Listed as
Residential
Telephone is residential but address
address, name provided does not match
with Telephone listing
Failure
K
Address/Telephone, Year of
Residential
Telephone is residential and name
matches with phone listing but address
address, Year of birth provided does not
match
Failure
Page 12 of 37
CAV User Guide
Equifax
Reason
Code
Condition
Definition
Success /
Failure /
Warning
L
Name/Telephone, Year of
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
Failure
N
Address/Telephone, Year of
Business
Telephone is listed as business but
telephone-listing address, and Year of
birth provided does not match
Warning
O
Mismatch - Year of Birth;
Cannot Be Verified
Year of birth does not match and the
phone number provided can not be
verified
Failure
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
Warning
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
Failure
R
Telephone Number/Postal
Code
Telephone is listed as residential, name
provided matches with listing, but
address does not fall within geographical
location
Warning
S
Mismatch - Year of Birth,
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
Failure
T
Mismatch - Year of Birth
Everything matches except year of birth
Failure
Page 13 of 37
8 CAV INTEGRATION PROCEDURES
CAV User Guide
You must include the following information in your integration:
Table 7: CAV Integration Procedures
Service
Quick Match
Required Variables
Credit card number
Customer name
Billing address: civic number, street name, city, province, country, postal code
SafeScan
Credit Card number
Customer name
Date of birth
SIN number (optional – customers cannot be required by law to provide a SIN)
SafeScanID
Credit Card number
Customer name
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
CAV User Guide
<cavresponse>
<responsecode>1</responsecode>
<transactionid>20007427</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>
<creditcardcode>
<creditcardcode1>2299</creditcardcode1>
</creditcardcode>
<addresscode>
<addresscode1>2307</addresscode1>
</addresscode>
<sscode>
</sscode>
<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
CAV User Guide
<cavresponse>
<birthdatecode>9001</birthdatecode>
<creditcardcode>
</creditcardcode>
<addresscode>
</addresscode>
<sscode>
</sscode>
</cavresponse>
8.2 SUBMITTING A STAND-ALONE REQUEST
You can interface with the CAV API using ASP Script querystring variables.
8.2.1 ASP SCRIPT
The ASP script can be passed to this URL:
https://www.beanstream.com/scripts/process_cav.asp
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
CAV User Guide
<?xml version="1.0"?>
<cavrequest>
<serviceversion>1.2</serviceversion>
<merchantid>110000000</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>5198980004875020</creditcard>
<dob>
<month>02</month>
<day>19</day>
<year>1957</year>
</dob>
<sin>456878906</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 99-999999-99.
To add this feature, please contact: [email protected]
Page 17 of 37
The following is an example of the response XML message:
CAV User Guide
<?xml version="1.0"?>
<cavresponse>
<birthdatecode>9001</birthdatecode>
<creditcardcode>
</creditcardcode>
<addresscode>
</addresscode>
<sscode>
</sscode>
</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
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.
o
The response will only include the following parameters (all others are
suppressed):
o

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
Example of a successful XML request, using the new parameter:
CAV User Guide
<?xml version="1.0" encoding="US-ASCII" standalone="yes"?>
<cavrequest>
<eidtransaction>102428491</eidtransaction>
</cavrequest>
Example of a successful XML response message:
<cavresponse>
<provincematch>1</provincematch>
</cavresponse>
Example of a failed XML request message:
<cavrequest>
<eidtransaction>99999999</eidtransaction>
</cavrequest>
Example of a failed XML response message that includes the new response code:
<cavresponse>
<responsecode>-17</responsecode>
<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
1
Explanation
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
CAV User Guide
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:
<cavresponse>
<responsecode>-10</responsecode>
<creditcardcode>
<creditcardcode>
<addresscode>
<addresscode>
<sscode>
</sscode>
<ssidcode>0</ssidcode>
</cavrequest>
Page 20 of 37
CAV User Guide
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):
https://www.beanstream.com/scripts/process_transaction.asp?errorPage=%2Fsampl
es%2Forder_form.asp&merchant_id=109040000&trnCardOwner=Paul+Randal&trnCardNum
ber=5100000010001004&trnExpMonth=09&trnExpYear=05&trnOrderNumber=2232&trnAmou
nt=10.00&[email protected]&ordName=Paul+Randal&ordPhoneNum
ber=9999999&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
CAV User Guide
9 PROVINCE CODES
This table lists the valid province codes that CAV accepts:
Two-letter Code
Province
AB
Alberta
BC
British Columbia
MB
Manitoba
NB
New Brunswick
NL
Newfoundland and Labrador
NT
Northwest Territories
NS
Nova Scotia
NU
Nunavut
ON
Ontario
PE
Prince Edward Island
QC
Quebec
SK
Saskatchewan
YT
Yukon
Page 22 of 37
10 XML MESSAGE DEFINITIONS
CAV User Guide
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
CAV User Guide
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 addresscode
(addresscode1,addresscode2?,addresscode3?,addresscode4?)>
<!ELEMENT addresscode1 (#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 ssidcode (#PCDATA)>
<!ELEMENT status ( #PCDATA ) >
]>
Page 24 of 37
11 TRANSACTION MESSAGE XML SCHEMA
CAV User Guide
11.1 REQUEST MESSAGE
<?xml version="1.0" encoding="utf-16"?>
<xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<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
CAV User Guide
11.2 RESPONSE MESSAGE
<?xml version="1.0" encoding="utf-16"?>
<xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<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:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="addresscode">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="addresscode1" 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:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="ssidcode" type="xsd:string" />
Page 26 of 37
CAV User Guide
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.
12.1 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
The name of the field in the batch file
Data Type
A=Alphanumeric
N=Numeric
Max Size
The maximum number of characters or digits permitted in the field
QM
O=optional for QuickMatch, R=required for QuickMatch
SS
O=optional for SafeScan, R=required for SafeScan
SSID
O=optional for SafeScan ID, R=required for SafeScan ID
Table 10: CAV Batch Files -- Required Fields
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
Field Name
Page 27 of 37
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
CAV User Guide
Data
Type
Max
Length
QM
SS
SSID
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
Birth Date
N
8
O
R
R
SIN
N
9
-
O
O
Field Name
Description
The city of the consumer’s
home address.
The province of the
The postal code of
The consumer’s home
phone number.
The consumer’s birth date.
Formatted as MMDDYYYY.
Example: March 27th, 1964
would be formatted as
03271964
The consumer’s social
insurance number.
12.2 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
CAV User Guide
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
250-555-1234
613-730-7978
902-445-9242
519-524-4466
House
Number
391
9
45
250
Macro Ln
Langbrae Dr Apt
118
Hincks
Street Name
GERTRUDE AV
APT 311
City
Winnipeg
Ottawa
Halifax
Goderich
Province
MB
ON
NS
ON
Postal Code
R3L0M5
K1S5A1
B3M4L2
N7A3A5
Credit Card
Number
4504481742333
5191230031972147
4510706320185012
4535100693770
Birth Date
(mm/dd/yy)
10/02/1959
3/28/1955
9/23/1975
12/22/1975
SIN
624-256-688
449-640-556
125-126-391
642-617-153
QuickMatch
Credit Card
2299
2200
201
2200
QuickMatch
Address
2307
2307
2307
2307
SafeScan
0
B
-
BA
SafeScanId
R
E
-
Page 29 of 37
CAV User Guide
Test Case E
Test Case F
Test Case G
Test Case H
First Name
Rheal
Raymond
Barbara
ATM
Last Name
Dumont
McWilliam
Way
Zakiuddin
250-748-7681
905-432-1501
416-244-0886
1466
442
1440
Belcarra Rd
Waverly St
Lawrence Av W
Phone
Number
House
Number
Street Name
1545
Delia Cres
City
Orleans
Duncan
Oshawa
North York
Province
ON
BC
ON
ON
Postal Code
K4A2Y1
V9L5P2
L1J5W3
M6L 1B4
Credit Card
Number
519493000487502
0
526807003023681
0
450225292433
8
519123103991651
6
Birth Date
(mm/dd/yy
)
2/19/1957
6/20/1955
02/05/47
12/15/52
SIN
456-883-826
712-909-076
417-439-577
417-439-577
QuickMatch
Credit Card
2299
2200
2299
2299
QuickMatch
Address
2307
2307
2307
2307
SafeScan
5
7
-
5
SafeScanId
-
-
-
J
Page 30 of 37
CAV User Guide
Test Case I
Test Case J
Test Case K
First Name
Dorothy
Henry
Helen
Last Name
Ferrante
Moran
Donalds
Phone
Number
204-254-5536
514-941-5346
604-255-1000
House
Number
167
285
4731
Rue Charon
Harley Crt Un 22
Street Name
Morley Ave
City
Winnipeg
Montreal
Burnaby
Province
MB
QC
BC
Postal Code
R2K3S3
H3K 2N8
V5H 1M9
Credit Card
Number
5191230048226972
5191230047660700
5191230045210025
Birth Date
(mm/dd/yy)
04/13/72
07/20/75
11/11/69
SIN
642-117-741
277-545-885
132-132-135
QuickMatch
Credit Card
118
2299
100
QuickMatch
Address
118
2307
100
SafeScan
B93
P
0
-
D
SafeScanId
Page 31 of 37

Canadian Address Verification Integration Guide

Transcription

Similar documents

pdf brochure setup.cdr

1st Air Cav`s 2-227 `Lobos` host cancer awareness run

On-post lifeguards test skills, compete

Will you make it past February 18?

newsletter-2016-june - Cavendish Road State High School

Private Label Card Management Software

airmobile - 5th Battalion 7th Cavalry Association

RE/MAX vs. THE INDUSTRY

Ulf Hörman - Swegon Air Academy

A-REX - NorduGrid