Beanstream Internet Payment Processing
Process Transaction API
Document Version 1.3
Last Updated November 23, 2004
Customer_Documentation\Beanstream\English\Processing_Methods\Process_Transaction_AP
I
For further information please contact Beanstream customer support at (250) 472-2326 or
support@beanstream.com.
Beanstream Internet Commerce Process Transaction API
Page 2 of 30
DOCUMENT REVISION HISTORY....................................................................................... 3
OVERVIEW ....................................................................................................................... 4
1. THE CUSTOMER TRANSACTION......................................................................... 5
1.1. SECURITY FEATURES.......................................................................................... 5
2. SUBMITTING THE TRANSACTION...................................................................... 6
2.1. CHECKING FOR DUPLICATE TRANSACTIONS ................................................................ 6
2.2. SYSTEM GENERATED ERRORS................................................................................ 6
2.3. USER GENERATED ERRORS................................................................................... 7
3. TRANSACTION COMPLETION ............................................................................ 8
4. SERVER-TO-SERVER PROCESSING .................................................................... 8
5. DATA VARIABLES.............................................................................................. 9
5.1. INPUT VARIABLES ............................................................................................. 9
Credit Information ..................................................................................... 11
Billing Information ..................................................................................... 11
Shipping Information ................................................................................. 12
Product Information ................................................................................... 12
Pricing Information .................................................................................... 13
Custom Information ................................................................................... 13
5.2. RESPONSE VARIABLES ...................................................................................... 13
6. VARIABLE CODES............................................................................................ 15
6.1. RESPONSE MESSAGES CODES (MESSAGEID VARIABLE) ................................................ 15
6.2. COUNTRY CODES ............................................................................................ 22
6.3. PROVINCE/STATE CODES .................................................................................. 24
6.4. AVS RESPONSE CODES .................................................................................... 24
7. RECURRING TRANSACTIONS .......................................................................... 25
7.1. BILLING FREQUENCY ........................................................................................ 25
7.2. BILLING DATES.............................................................................................. 25
7.3. RECURRING DATA VARIABLES ............................................................................. 26
8. TEST CARD NUMBERS ..................................................................................... 27
8.1. REGULAR CREDIT CARDS................................................................................... 27
8.2. VERIFIED BY VISA / MASTERCARD SECURECODE CREDIT CARDS..................................... 27
9. URL ENCODING CHART ................................................................................... 28
10. EXAMPLES.................................................................................................... 29
Beanstream Internet Commerce Process Transaction API
Page 3 of 30
Document Revision History
Date Revision Description Author Revision
Number
3/13/02 Added detail on processing adjustment transaction types and purchase
transaction types.
Added approvedPage/declinedPage specifications to the list of Input
Variables.
Shawn Gerty
Aston Lau
1.1.00
10/22/02 Added instructions on CVD Aston Lau 1.2.00
10/23/02 Updated instructions on using ref fields Aston Lau 1.2.01
2/18/03 Added instructions on recurring transactions.
Added details on new merchant definable approvedPage and declinedPage
parameters.
Added details on Server to Server Transaction Response Notification.
Shawn Gerty 1.2.02
4/16/03 Added cavEnabled parameter to list of input variables. Aston Lau 1.2.03
6/27/03 Added AVS response codes to section 4.2.1
Added AVS response code message table to section 5.5
Shawn Gerty 1.2.05
8/06/03 Updated description of response parameter authCode.
Changed trnOrderNumer from numeric only to alphanumeric.
Shawn Gerty 1.2.06
8/20/03 Added new bank and Beanstream response messages. Michael J Foucher 1.2.07
8/27/03 Added Verified By Visa information. Aston Lau 1.2.08
9/15/03 Extended length of card owner and address variables.
Fixed formatting of section 5
Aston Lau 1.2.09
10/27/03 Added test credit card numbers Marcus Doty 1.2.10
11/06/03 Added duplicate checking information
Removed reference to Server-to-Server Response Notification URL
(Response Notification URL is not a feature of STS)
Added information on Server-to-Server
Aston Lau 1.2.11
12/10/03 Fixed errorPage variable in example Aston Lau 1.2.12
2/05/03 Added date formatting examples for Recurring Billing rbFirstBilling and
rbSecondBilling request parameters.
Shawn Gerty 1.2.13
6/02/04 Added Verified by Visa / MasterCard SecureCode test card numbers
Added vbvEnabled and scEnabled input parameters
Aston Lau 1.2.14
6/06/04 Changing the adjId from 10 numbers to 8. Michael J Foucher 1.2.15
6/06/04 Update section 4.1.4, shipping phone number field named
“shipPhoneNumber”. Also add note that post variables are case specific.
Marcus Doty 1.2.16
7/15/04 Updated response codes in section 5.1 Marcus Doty 1.2.17
9/09/04
Updated example posts to process_transaction.asp Marcus Doty 1.2.18
9/13/04 Changed response messages for response codes 179, 180, 181, 182,
183, 184, 187, 188, 189 from Declined to Approved.
Bernie Lambert 1.2.18
11/23/04 Changed wording, reformatted document. Jane Waite 1.3
Beanstream Internet Commerce Process Transaction API
Page 4 of 30
Overview
The transaction processing API method allows you to link any e-commerce order processing system
directly to the Beanstream transaction server.
This may be as simple as a one page order form, or as complex as a full shopping cart. Whereas all other
processing methods provide you with a web interface that may be built into your site, Transaction
Processing API allows you to build your own web interface and offers the highest level of flexibility to your
order process.
With this interface you may process not only purchase transaction types (purchase, pre-auth), but also
adjustment transaction types (return, void purchase, void return, pre-auth completion).
Getting Started
The Process Transaction API is secured via 128-bit SSL encryption to prevent third parties from seeing the
details of your customer’s transaction request during transit to the Beanstream server. In order to access
the Process Transaction API, you must have a merchant account with Beanstream and be able to
communicate with our web server via 40-bit or 128-bit SSL.
Beanstream Internet Commerce Process Transaction API
Page 5 of 30
1. The Customer Transaction
Transactions are submitted to the Beanstream transaction server via a standard HTTP POST or GET
request. From start to finish, the transaction process takes the following form:
A shopper browses your web site for products or services they would like to order.
He or she completes the payment form located on either your website or the Beanstream
server.
All order information is submitted to be processed by Beanstream.
*The Beanstream server returns a web page to your customer’s browser, where they must
enter their VBV password.The password is verified and the results are sent to the Beanstream
server.
The results of the transaction are returned to a web page that you specify.
* This step only occurs if Verified by Visa (VBV) is enabled for your account. In this case, customer credit
cards are protected by a password which must be entered each time a new card number is entered. As
VBV steps are transparent to the merchant, the integration steps outlined in this document are exactly the
same for both VBV and non-VBV implementations.
1.1. Security Features
You can ensure optimal security throughout the stages of a customer transaction by enabling several
features of the Beanstream system.
1.1.1 Order Settings
Go to Administration Account Settings Order Settings in the left menu of the membership page.
Using the checkboxes in this module, you may:
Require a username/password validation
Validate orders against inventory
Validate that the referring host (the web site that the customer comes from) is yours
Please note that to validate orders against your inventory, you must upload your inventory to the
Beanstream system. For more information on how to do this, please refer to the document titled
Inventory Management.
1.1.2 PGP Encryption
PGP is a key security feature available for use with Process Transaction. For further information on this
please see document titled Process Transaction using PGP. Using this option you may:
Use PGP signing to verify that the transaction has been authorized by you
Use PGP encryption to further encrypt the details of the transaction
1.1.3 Add the Ambiron Secure Logo to your Payment Page
Beanstream Internet Commerce Process Transaction API
Page 6 of 30
Beanstream has worked with Ambiron’s Multi-Card compliance Program (MCCP) to
demonstrate to you and your customers that we comply with American Express DSPO,
Discover DISC, MasterCard SDP, Visa AIS and Visa CIPS credit card association programs.
To learn more about Ambiron and to register your site click on the seal at the bottom of the
Beanstream homepage www.beanstream.com/website/index.asp.
If you have already registered for the Ambiron program, you can use the following code to
insert the logo onto your payment page.
<!-- Ambiron Vital Signs Compliance Seal -->
<STYLE>img{cursor:pointer;}</STYLE>
<IMG
onclick="javascript:window.open('https://vitalsigns.ambiron.net/compliance/cert.php?code=34D0B
5A975142D6C3C7BE88BB81ADE20',
'newwin','location=no,toolbar=no,scrollbars=no,resizable=no,directories=no,status=no
,width=500,height=325');
return false;"
src
="https://vitalsigns.ambiron.net/compliance/seal.php?code=34D0B5A975142D6C3C7BE88BB81
ADE20" border=0 >
<!-- End Ambiron Vital Signs Compliance Seal -->
1.1.4
2. Submitting the Transaction
All transaction fields are populated and submitted to the transaction server at the following URL:
https://www.beanstream.com/scripts/process_transaction.asp
Transaction details are sent to this page as a set of field name/value pairs and submitted through either a
form post or a query string. The call to process_transaction.asp will contain all of the information required
to complete the transaction. For examples, refer to section of this document.
The order information is then posted to our processing script to complete the transaction. There are a
number of required fields that must be entered in order to complete a transaction. The remaining optional
fields are used for informational purposes and product tracking.
2.1. Checking for Duplicate Transactions
To minimize the possibility for error, Beanstream has created an automatic check for duplicate
transactions. Beanstream will mark an item as a duplicate if the transaction amount, the card number
and the card expiry date are identical to another transaction recorded within the same 24 hour period:
If you choose to pass an Order Number, the Beanstream system will base duplicate checking on the
transaction amount, the card number, the card expiry date and the order number. This will allow
customers to process more than one order per day using the same card.
2.2. System Generated Errors
Beanstream Internet Commerce Process Transaction API
Page 7 of 30
To help debug your Process Transaction online order form or shopping cart integration at the development
stage, you may wish to set automatic transaction error messages. If a field contains invalid data, or if a
transaction conflicts with your account settings, you will be notified immediately with a system generated
message outlining any missing or conflicting information. In a properly working system, these messages
will never be displayed to a shopper. Messages are displayed on the transaction processing error page
and are not redirected back to the address specified by the errorPage variable.
Possible error messages include the following:
Connection is not secure
Invalid merchant ID
Authorization Failed
Missing transaction data
Missing errorPage address
2.3. User Generated Errors
If any customer credit or billing information is invalid or missing, Process Transaction will redirect back to
the address specified by the errorPage variable. All of the submitted information will be returned along
with two error parameters:
errorMessage Contains a descriptive message indicating all of the errors found on the order. Use
this message to prompt customers to correct information on their order form.
errorFields Contains a comma-separated list of all the field names that contain invalid data. Use
this to customize your own error handling.
Please note that all variables are passed back in URL-encoded form. Certain characters must be encoded
because they either cannot be used or they come with specific meaning in URL. For example, %20 is the
URL-encoded form of the space character. See section 9 of this document for a full listing of characters
and their URL-encoded equivalents.
Example
A process_transaction.asp is called with the errorPage variable
https://www.beanstream.com/order/sample/order_form.asp.
A customer passes an invalid credit card number and expiry date.
The process_transaction.asp will redirect to
https://www.beanstream.com/order/sample/order_form.asp with the following additional two
URL encoded variables:
errorMessage=
%3CLI%3EInvalid+card+number%3Cbr%3E%3CLI%3Einvalid+expiry+date%2E%3Cbr%3E%3
Cbr%3E&errorFields=trnCardNumber%2CtrnExpYear
errorFields=
trnCardNumber%2CtrnExpYear
Beanstream Internet Commerce Process Transaction API
Page 8 of 30
Please note that only the credit card number and expiry are invalid so these are the only two field
names passed back in the errorFields parameter.
Transaction Request:
https://www.beanstream.com/scripts/process_transaction.asp?errorPage=%2Fsamples%2Forder_form.as
p&merchant_id=109040000&trnCardOwner=Paul+Randal&trnCardNumber=510012341234&trnExpMonth
=01&trnExpYear=08&trnOrderNumber=2232&trnAmount=10.00&ordEmailAddress=prandal@mydomain.n
et&ordName=Paul+Randal&ordPhoneNumber=9999999&ordAddress1=1045+Main+Street&ordAddress2=
&ordCity=Vancouver&ordProvince=BC&ordPostalCode=V8R+1J6&ordCountry=CA
Transaction Response:
https://www.beanstream.com/samples/order_form.asp?errorMessage=%3CLI%3EInvalid+card+nu
mber%3Cbr%3E%3CLI%3EInvalid+expiry+date%2E%3Cbr%3E%3Cbr%3E&errorFields=trnC
ardNumber%2CtrnExpYear&errorPage=%2Fsamples%2Forder_form.asp&merchant_id=109040000&trn
CardOwner=Paul+Randal&trnCardNumber=510012341234&trnExpMonth=01&trnExpYear=08&trnOrderNu
mber=2232&trnAmount=10.00&ordEmailAddress=prandal@mydomain.net&ordName=Paul+Randal&ordPh
oneNumber=9999999&ordAddress1=1045+Main+Street&ordAddress2=&ordCity=Vancouver&ordProvince
=BC&ordPostalCode=V8R+1J6&ordCountry=CA
Addendum as of January 1 2002. In the case where a User Generated Error occurs, the system will
not return the value of the trnCardNumber and trnCardExpiry fields to the errorPage URL. All other
parameters will be returned as normal.
3. Transaction Completion
After order information has been validated, the transaction is passed to the bank for authorization.
Depending on the status of the transaction, the customer is then directed to either the Transaction
Approved or Transaction Declined URL which you have chosen. To set the approved/declined pages, go to
Administration Account Setting Order Settings.
See section 5.2 for the complete list of variables used to pass transaction results to the approved/declined
pages.
1.1.5 You may also wish to specify a Response Notification URL using the
Order Settings module. This feature will send you an immediate
transaction response. When enabled, the Beanstream system will
post the transaction response to this URL. Use the same variables as
for the approved/declined pages.
4. Server-to-Server Processing
Server-to-Server is an additional feature of process_transaction.asp. With server-to-server transactions,
results are returned directly rather than being redirected to the approval/decline pages specified in the
membership area.
For more information on server-to-server transactions, refer to the document titled Server-to-Server with
Process Transaction API.
Beanstream Internet Commerce Process Transaction API
Page 9 of 30
5. Data Variables
Use the variables listed in the following tables for your Process Transaction API.
Each table has five columns:
Field Name The name of the form element used to store data. All required fields must be passed
to the Transaction Processing script in order to complete the purchase. Field names
marked with an asterisk (*) are required if you have selected to Validate
Orders against Inventory in the Beanstream Order Settings module.
Max Size The maximum number of characters that may be contained in a field.
Alpha/Numeric/ The kind of characters to be used in a field.
Currency N= numbers only
A= letters or a combination of numbers and letters
$= a currency in decimal form
Required Identifies if a field is required.
R = A required field for all transaction types
O = An optional field for all Purchase Transaction Types
P = A required field for Purchase (P) and Pre-Authorization (PA) transactions
A = A required field for Adjustment Transaction only. Adjustment Transactions
include all R, VP, VR, and PAC transactions which are processed against a previously
completed transaction.
Description Detailed description of the information which should be contained in each field.
Transaction type abbreviations:
P = Purchase R = Return VP = Void Purchase
VR = Void Return PA = Pre Authorization PAC = Pre Authorization Completion
5.1. Input Variables
*Please note that all input variables are case specific.
Field Name Max Size Alpha/
Numeric/
Currency
Required Description
merchant_id 9 N R The nine-digit Beanstream assigned identification
number.
trnOrderNumber 30 A R The order number of the shopper’s purchase.
trnType 3 A R Indicates the type of transaction to perform
(i.e. P,R,VP,VR, PA, PAC). This is an optional field.
If omitted, this field will default to P.
Beanstream Internet Commerce Process Transaction API
Page 10 of 30
Field Name Max Size Alpha/
Numeric/
Currency
Required Description
trnLanguage 3 A O Three digit ISO language code. This value is passed
to the approval/decline page untouched.
errorPage 128 A R If any billing or credit card information is invalid or
missing the customer will be redirected to this
address along with the error message.
Username 16 A A
Password 16 A A
If you have activated the username/password
validation option in (located in the Beanstream
Order Settings module) these fields are mandatory.
This option must be enabled in order to process
R,V and PA transactions. Once enabled these
parameters are required for all transactions types
including P and PA.
adjId 8 N A This field is required when the transaction type is
an R, VP, VR, PAC, or an adjustment. These all mod
previous transactions that are identified by this
adjustment ID. This number must be the trnId
of the originating transaction.
approvedPage - A O If a transaction request is approved, this is the URL
that the consumer’s browser will be redirected to.
This parameter overrides the URL set within the
Order Settings module of the Membership Area.
There is no length restriction on this field.
declinedPage - A O If a transaction request is declined, this is the URL
that the consumer’s browser will be redirected to.
This parameter overrides the URL set within the
Order Settings module of the Membership Area.
There is no length restriction on this field.
trnComments 8000 A O An optional comment that can be stored with the
transaction.
cavEnabled 1 N O If you have requested the CAV address verification
service and you have the Require CAV on all
transactions option turned off in Beanstream’s
membership area. Pass this parameter to specify
that you want the transaction verified by CAV before
processed.
Pass cavEnabled=1 to enable CAV, or cavEnabled=0
disable it.
vbvEnabled 1 N O If you have requested Verified by Visa
authentication service, pass this parameter to
enable or disable VbV for the transaction. You must
enable the Username/password validation option in
Beanstream’s Order Settings module.
Pass vbvEnabled=1 to enable VbV, or vbvEnabled=0
disable it.
scEnabled 1 N O If you have requested MasterCard SecureCode
authentication service, pass this parameter to
enable or disable SecureCode for the transaction.
Beanstream Internet Commerce Process Transaction API
Page 11 of 30
Field Name Max Size Alpha/
Numeric/
Currency
Required Description
You must enable the Username/password validation
option in Beanstream’s Order Settings module.
Pass scEnabled=1 to enable SecureCode, or
scEnabled=0 to disable it.
1.1.6 Credit Information
Name Max Size Alpha/
Numeric/
Currency
Required Description
trnCardOwner 64 A P Name of the card owner as seen on their credit card.
trnCardNumber 20 N P Customer credit card number
trnExpMonth 2 N P Customer credit card expiry month. Please note
that this must be a date on or later than the current
month and year. The month must be entered
numerically (January = 01)
trnExpYear 2 N P Customer credit card expiry year. The year must be
entered as a number less than 50. Please note, if
the year is the current year, then the month must be
greater than the current month.
trnCardCvd 4 N O Customer credit card CVD. This will be the last 3
digits (4 for Amex) on the back of the customer’s
credit card. This is for security purposes and is
optional unless Require Credit Card CVD is enabled
in the Beanstream Order Settings module.
1.1.7 Billing Information
Field Name Max Size Alpha/
Numeric/
Currency
Required Description
ordName 64 A P The primary contact name for the person/company
listed in the billing information.
ordEmailAddress 64 A P The Email address for the person/company listed as
the primary contact in the billing information.
Must be a valid email address format. Validates that
the address has the “@” and “.” symbols and that
there are letters between these symbols, e.g.
a@b.com.
ordPhoneNumber 32 A P The phone number for the primary contact as listed in
billing information.
ordAddress1 64 A P The billing address.
ordAddress2 64 A O An additional billing address field for long addresses
ordCity 32 A P The name of the city for billing information.
ordProvince 2 A P The billing province/state ID. See section 6.3 for a list
province/state codes.
ordPostalCode 16 A P Billing address postal/zip code
Beanstream Internet Commerce Process Transaction API
Page 12 of 30
Field Name Max Size Alpha/
Numeric/
Currency
Required Description
ordCountry 2 A P Billing address country ID. See section 6.2 for a list of
country codes.
1.1.8 Shipping Information
1.1.9
Name Max
Size
Alpha/
Numeric/
Currency
Required Description
shipName 64 A O Name of the person/company to ship the
order to.
shipEmailAddress 64 A O Shipping contact's email address.
Must be a valid email address format. Validates
that the address has the “@” and “.” symbols and
that there are letters between these symbols, e.g.
a@b.com
shipPhoneNumber 32 A O Shipping contact's phone number
shipAddress1 64 A O Shipping address
shipAddress2 64 A O Additional shipping address field for long addresses
shipCity 32 A O Shipping address city
shipProvince 2 A O Shipping address province/state ID. See section 6.3
list of province and state codes.
shipPostalCode 16 A O Shipping address postal/Zip code
shipCountry 2 A O Shipping address country ID. See section 6.2 for a
list of country codes.
shippingMethod 64 A O Description of the shipping method used for this
Order.
deliveryEstimate 9 N O Estimated delivery time in days.
1.1.10 Product Information
Field Name Max Size Alpha/
Numeric/
Currency
Required Description
prod_id_n * 32 A O The product ID or SKU number used to uniquely
identify a product
prod_name_n 64 A O Description of the ordered product
prod_quantity_n * 9 N O Quantity of the ordered product
prod_shipping_n 9 $ O Shipping cost of the product
prod_cost_n 9 $ O Purchase cost of the product
There is no limit to the number of product informational fields that may be included with your order. All
field names must be numbered from 1-n (ie. prod_id_1, prod_quantity_1, prod_id_2, prod_quantity_2,
etc.).
Beanstream Internet Commerce Process Transaction API
Page 13 of 30
If product information is passed in, you may want to use the Validate Orders Against Inventory option in
the Beanstream Order Settings module. For more information on this option, please refer to the
document titled Account Settings.
1.1.11 Pricing Information
1.1.12
Field Name Max
Size
Alpha/
Numeric/
Currency
Required Description
ordItemPrice * 9 $ O The total price of all items on the order, taking into
account product quantities.
ordShippingPrice * 9 $ O Order shipping charges. This includes the individual
product shipping charges, if any.
ordTax1Price * 9 $ O Total amount of tax1 charged to the order
ordTax2Price * 9 $ O Total amount of tax2 charged to the order
trnAmount 9 $ R Total order amount. This should be equal to the sum
of the ordItemPrice, ordServicePrice,
ordShippingPrice, ordTax1Price, and ordTax2Price.
Must be a positive numeric value.
1.1.13 Custom Information
1.1.14
Field
Name
Max
Size
Alpha/
Numeric/
Currency
Required Description
refn - A O Up to five reference fields may be passed along with the order
to contain any site-specific information you need to maintain dur
the order process. When this information is sent out to the
processing script, it is stored in Beanstream’s database along
with the details of the transaction and returned back to your site
unmodified. These fields may be used to maintain information
such as shopper IDs, account numbers, order numbers, or any
other tracking information you may require.
These field names must be numbered from 1 to 5 in the format
ref1, ref2, ref3, ref4 and ref5. There is no restriction on the size
reference fields.
5.2. Response Variables
The following fields are returned upon completion of a transaction:
1.1.15 Response Parameters
Name Max
Size
Alpha/
Numeric/
Currency
Description
Beanstream Internet Commerce Process Transaction API
Page 14 of 30
Name Max
Size
Alpha/
Numeric/
Currency
Description
trnId 8 N Unique ID number used to identify an individual transaction
messageId 3 N The ID number of the transaction response message. See section 6.1
for a list of response message codes
messageText 128 A The text message associated with the messageID
authCode 6 A If the transaction has been approved, this parameter will contain the
authorization code returned from the bank. If the transaction has
been declined, the parameter will contain no value.
The authorization code is the unique transaction identifier assigned
by the bank. The authorization code must be displayed to the card
holder when a transaction is complete.
trnAmount 9 $ The amount of the transaction
TrnDate 20 A The date and time that the transaction was processed
trnOrderNumber 10 N The order number associated with the transaction
trnLanguage 3 A Contains the value of the trnLanguage field submitted in the
transaction request.
trnCustomerNam 32 A Contains the value of the trnCardOwner field submitted in the transact
request.
trnEmailAddress 64 A Contains the value of the ordEmailAddress field submitted in the
transaction request.
trnPhoneNumber 32 A Contains the value of the ordPhoneNumber field submitted in the
transaction request.
avsProcessed 1 N Parameter returned only if AVS is enabled on the merchant account. S
a value of 1 if the issuing bank has successfully processed an AVS
check on the transaction. Set to a value of 0 if no AVS check has
been performed.
avsId 1 A Parameter returned only if AVS is enabled on the merchant account.
The id number of the AVS response message. See section 6.4 for a
listing of possible values.
avsResult 1 N Parameter returned only if AVS is enabled on the merchant account. S
Set at a value of 1 if AVS has been validated with both a match agains
address and a match against postal/ZIP code.
avsAddrMatch 1 N Parameter returned only if AVS is enabled on the merchant account. S
Set at a value of 1 if the ordAddress1 parameter matches the
consumers address records at the issuing bank. Set to a value of 0 if
ordAddress1 parameter does not match the consumers address
records or if AVS was not processed for the transaction.
avsPostalMatch 1 N Parameter returned only if AVS is enabled on the merchant account. S
Set to a value of 1 if the ordPostalCode parameter matches the
consumers address records at the issuing bank. Set to a value of 0 if
the ordPostalCode parameter does not match the consumers address
records or if AVS was not processed for the transaction.
avsMessage 128 A Parameter returned only if AVS is enabled on the merchant account. S
the value of the text message associated with the avsId response
code.
ref1 - A The value of the ref1 field submitted in the transaction request.
ref2 - A The value of the ref2 field submitted in the transaction request.
ref3 - A The value of the ref3 field submitted in the transaction request.
ref4 - A The value of the ref4 field submitted in the transaction request.
Beanstream Internet Commerce Process Transaction API
Page 15 of 30
Name Max
Size
Alpha/
Numeric/
Currency
Description
ref5 - A The value of the ref5 field submitted in the transaction request.
6. Variable Codes
6.1. Response Messages Codes (messageId variable)
In this table:
Message Id Refers to the number that will appear in your response code messageID variable.
Message Type Refers to the organization which assigns a particular response code.
BIC = Beanstream Internet Commerce
TD = TD Canada Trust
GPS = Global Payment Systems
Approved If True is in this column, then a message with this code has passed validation.
If False appears in this column, a message with this code has been declined.
Message
Id
Message
Type
Approved Cardholder Message Merchant Message
1 GPS/TD True Approved Approved
2 GPS True Debit approved Debit approved
3 GPS False DECLINE Declined - Please call credit agency
4 GPS False Issuer unavailable Issuer unavailable
5 GPS False Invalid banking merchant ID Invalid banking merchant ID
6 GPS False PIC UP PIC UP
7 GPS False DECLINE Transaction Declined
8 GPS False Transaction reversed Transaction reversed
9 GPS False Approved with ID Approved with ID
10 GPS False Invalid serv ID Invalid serv ID
11 GPS False Invalid transaction amount Invalid transaction amount
12 GPS False Invalid account Invalid account
13 GPS False Please retry transaction Please retry transaction
14 BIC False Invalid expiration date Invalid expiration date
15 GPS False Unauthorized transaction Unauthorized transaction
16 BIC False
Duplicate Transaction - This
transactionhas already been approved
Duplicate Transaction –
This transaction has already been approved
17 GPS False Current batch must be settled Current batch must be settled
18 GPS False Electronic Draft Capture unavailable Electronic Draft Capture unavailable
19 GPS False Unexpected error Unexpected error
20 GPS False
License has expired - Unable to
authorize
License has expired - Unable to authorize
21 BIC False
Validation is less than the minimum
amount
Validation is less than the minimum amount
22 BIC False
Validation greater than maximum
amount
Validation greater than maximum amount
Beanstream Internet Commerce Process Transaction API
Page 16 of 30
Message
Id
Message
Type
Approved Cardholder Message Merchant Message
23 GPS False Validation - Bad data Validation - Bad data
24 GPS False Bad card number Bad card number
25 GPS False Bad card Bad card
26 BIC False Invalid expiry date Invalid expiry date
27 GPS False Timer Exceeded Timer Exceeded
28 GPS False Bad logical merchant number Bad logical merchant number
29 GPS False Security Violation Security Violation
30 GPS False Com Port Open Error Com Port Open Error
31 GPS False Max Com Reties Max Com Reties
32 GPS False Open File Error Open File Error
33 GPS False User or Remote Abort User or Remote Abort
34 GPS False Com Error Com Error
35 GPS False Error expired license Error expired license
36 GPS False No Pickup No Pickup
37 GPS False Incomplete Incomplete
38 GPS False Communication error Communication error
39 GPS False Error Tranaction Type Error Tranaction Type
40 GPS False Error Data Dictionary Error Data Dictionary
41 GPS False ErrorGetSc ErrorGetSc
42 GPS False ErrorExeSc ErrorExeSc
43 GPS False Error Velocity Error Velocity
44 GPS False Error Stale Dated Input File Error Stale Dated Input File
45 GPS False ForcdCmplt ForcdCmplt
46 GPS False ErrorSrvNr ErrorSrvNr
47 GPS False Printer configuration error Printer configuration error
48 GPS False Card reader configuration error Card reader configuration error
49 BIC False Invalid transaction request string Invalid transaction request string
50 BIC False Invalid transaction type Invalid transaction type
51 BIC False DECLINE Restricted Card or IP
52 BIC False Invalid Card Number Invalid Card Number
53 BIC False Application Error - Sending Request Application Error - Sending Request
54 BIC False
Transaction timeout –
No available device
Transaction timeout - No available device
55 BIC False
Transaction timeout –
No transaction Response
Transaction timeout - No transaction Response
56 BIC False Aplication Error - Retrieving Response Aplication Error - Retrieving Response
57 GPS False
Transaction Amount
greater than processing limit.
Transaction Amount greater than processing limit.
58 GPS False DECLINE Declined
59 BIC False
Declined – Operation must
be performed by Master Merchant
Declined - Operation must be performed by
Master Merchant
60 BIC False
Declined – Operation
restricted through Master Merchant
Declined - Operation restricted through
Master Merchant
61 TD True Approved Approved
62 TD True Approved Approved
63 TD True Approved Approved
64 TD True Approved Approved
65 TD True Approved Approved
66 TD True Approved Approved
67 TD True Approved Approved
68 TD True Approved Approved
69 TD True Approved Approved
70 TD True Approved Approved
71 TD False Declined Declined
Beanstream Internet Commerce Process Transaction API
Page 17 of 30
Message
Id
Message
Type
Approved Cardholder Message Merchant Message
72 TD False Declined EXPIRED CARD Declined EXPIRED CARD
73 TD False Declined Declined
74 TD False Declined Declined
75 TD False Declined Declined
76 TD False PLEASE TRY AGAIN PLEASE TRY AGAIN
77 TD False Declined Declined
78 TD False Declined Declined
79 TD False Declined Declined
80 TD False Declined Declined
81 TD False Declined Declined
82 TD False Declined Declined
83 TD False Declined Declined
84 TD False Declined Declined
85 TD False Declined Declined
86 TD False PLEASE TRY AGAIN Declined
87 TD False Declined Declined ADJ NOT ALLOWED
88 TD False Declined Declined
89 TD False Declined Declined INVALID TRAN DATE
90 TD False Declined Declined
91 TD False PLEASE TRY AGAIN Declined
92 TD False Declined Declined
93 TD False Declined Declined
94 TD False Declined Declined
95 TD False Declined Declined
96 TD False Declined Declined
97 TD False Declined Declined
98 TD False Declined Declined
99 TD False Declined Declined
100 TD False Declined Declined DUPLICATE TRAN
101 TD False Declined Declined
102 TD False Declined Declined
103 TD False Declined Declined MAX PER REFUND
104 TD False Declined Declined NUM TIMES USED
105 TD False Declined Declined MAX REFUND TOTAL
106 TD False Declined Declined
107 TD False Declined Declined
108 TD False Declined Declined
109 TD False Declined Declined MAX REFUND NUMBER
110 TD False Declined Declined
111 TD False Declined Declined
112 TD False Declined Declined
113 TD False Declined Declined
114 TD False Declined Declined
115 TD False Declined Declined
116 TD False Declined Declined
117 TD False Declined Declined
118 TD False Declined Declined
119 TD False Declined Declined
120 TD False Declined Declined
121 TD False Declined Declined
122 TD False Declined Declined
123 TD False Declined Declined
124 TD False Declined Declined
125 TD False Declined Declined
Beanstream Internet Commerce Process Transaction API
Page 18 of 30
Message
Id
Message
Type
Approved Cardholder Message Merchant Message
126 TD False Declined Declined
127 TD False Declined Declined CARD NOT SUPPORTED
128 TD False Declined Declined
129 TD False Declined Declined
130 TD False Declined Declined
131 TD False Declined Declined
132 TD False Declined Declined
133 TD False Declined Declined
134 TD False Declined Declined
135 TD False Declined Declined
136 TD False Declined Declined
137 TD False Declined Declined
138 TD False Declined Declined
139 TD False Declined Declined SERVICE MERCHANT NOT ON FILE
140 TD False Declined Declined
141 TD False Declined Declined
142 TD False Declined Declined
143 TD False Declined Declined
144 TD False Declined Declined
145 TD False Declined Declined
146 TD False Declined Declined
147 TD False Declined Declined INVALID TRAN DATE
148 TD False Declined Declined INVALID EXP DATE
149 TD False Declined Declined INVALID TRANCODE
150 TD False Declined Declined
151 TD False Declined Declined
152 TD False Declined Declined
153 TD False Declined Declined
154 TD False Declined Declined BAD FORMAT
155 TD False Declined Declined BAD DATA
156 TD False Declined Declined
157 TD False Declined Declined
158 TD False PLEASE TRY AGAIN Declined - TIMEOUT
159 TD False Declined Declined
160 TD False Declined Declined TERMINAL DEACTIVATED
161 TD False Declined Declined BAD RESPONSE LENGTH
162 TD False Declined Declined
163 TD False Declined Declined
164 TD False Declined Declined
165 TD False Declined Declined
166 TD False Declined Declined BAD SEQUENCE NUMBER
167 TD False Declined Declined
168 TD False Declined Declined EXPIRED CARD
169 TD False Declined Declined
170 TD False Declined Declined
171 TD False Declined Declined
172 TD False Declined Declined
173 TD False Declined Declined
174 TD False Declined Declined
175 TD False Declined Declined
176 TD False Declined Declined
177 TD False Declined Declined ADMIN CARD NOT FOUND
178 TD False Declined Declined ADMIN CARD NOT ALLOWED
179 TD True Approved Approved
Beanstream Internet Commerce Process Transaction API
Page 19 of 30
Message
Id
Message
Type
Approved Cardholder Message Merchant Message
180 TD True Approved Approved
181 TD True Approved Approved
182 TD True Approved Approved
183 TD True Approved Approved
184 TD True Approved Approved
185 TD False Declined Declined
186 TD False Declined Declined
187 TD True Approved Approved
188 TD True Approved Approved
189 TD True Approved Approved
190 BIC False Unknown transaction response Unknown transaction response
191 BIC False Invalid Transaction Amount Invalid Transaction Amount
192 BIC False
Transaction cannot be
voided after being returned
Transaction cannot be voided after being returned
193 BIC False
Amount does not match the
transaction you are modifying.
Amount does not match the transaction you are modifying.
194 BIC False Transaction exceeds return limit. Transaction exceeds return limit.
195 BIC False Invalid adjustment amount. Invalid adjustment amount.
196 BIC False
Original purchase transaction
has been voided
Original purchase transaction has been voided
197 BIC False
Transactions cannot be adjusted
to a zero or negative value
Transactions cannot be adjusted to a
zero or negative value
198 BIC False
Zero value transactions
cannot be voided
Zero value transactions cannot be voided
199 BIC False
Credit card does not
match original purchase.
Credit card does not match original purchase.
200 BIC False Transaction cannot be adjusted Transaction cannot be adjusted
201 BIC False Invalid transaction adjustment ID Invalid transaction adjustment ID
202 BIC False Invalid order number Invalid order number
203 BIC False Pre-Authorization already completed Pre-Authorization already completed
204 BIC False Declined: Use Pre-Auth Completion Declined: Use Pre-Auth Completion
205 BIC False
Transaction only voidable on
the date processed
Transaction only voidable on the date processed
206 BIC False Account missing terminal id Account missing terminal id
207 BIC False Invalid merchant id Invalid merchant id
208 BIC False
Completion greater than remaining
reserve amount.
Completion greater than remaining reserve amount.
209 BIC False Merchant Account Disabled Merchant Account Disabled
210 BIC False Merchant Account Closed Merchant Account Closed
211 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
212 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
213 GPS False Invalid or missing AVS address Invalid or missing AVS address
214 BIC False Transaction reversed Transaction reversed
215 BIC False Address Validation Failed Address Validation Failed
216 GPS False
Validation greater than
maximum amount
Validation greater than maximum amount
217 BIC False DECLINE Transaction Declined TR
218 BIC False DECLINE Transaction Declined AC
219 GPS False PIN INVLD PIN INVLD
220 GPS False MAX PIN RETRIES MAX PIN RETRIES
221 GPS False INV ACCT MATCH INV ACCT MATCH
222 GPS False INV AMT MATCH INV AMT MATCH
223 GPS False INV ITEM NUM INV ITEM NUM
Beanstream Internet Commerce Process Transaction API
Page 20 of 30
Message
Id
Message
Type
Approved Cardholder Message Merchant Message
224 GPS False ITEM REV-VOIDED ITEM REV-VOIDED
225 GPS False USE DUP THEN BALANCE NOW USE DUP THEN BALANCE NOW
226 GPS False NO DUPE FOUND NO DUPE FOUND
227 GPS False INVALID DATA INVALID DATA
228 GPS False NO TRANS FOUND NO TRANS FOUND
229 GPS False AP NOT CAPTURED AP NOT CAPTURED
230 GPS False AP AUTH ONLY AP AUTH ONLY
231 GPS False INV BANK INV BANK
232 GPS False TRAN TYPE INVLD TRAN TYPE INVLD
233 GPS False DB UNAVAIL 02 DB UNAVAIL 02
234 GPS False DB UNAVAIL 03 DB UNAVAIL 03
235 GPS False DB UNAVAIL 04 DB UNAVAIL 04
236 GPS False UNAUTH USER UNAUTH USER
237 GPS False INVALID CARD INVALID CARD
238 GPS False DB ISSUER UNAVAIL DB ISSUER UNAVAIL
239 GPS False INVALID POS CARD INVALID POS CARD
240 GPS False ACCT TYPE INVLD ACCT TYPE INVLD
241 GPS False INVALID PREFIX INVALID PREFIX
242 GPS False INVALID FIID INVALID FIID
243 GPS False VERIFY VERIFY
244 GPS False INVALID LIC INVALID LIC
245 GPS False INVALID STATE CD INVALID STATE CD
246 GPS False DB UNAVAIL 01 DB UNAVAIL 01
247 GPS False SCAN UNAVAILABLE SCAN UNAVAILABLE
248 GPS False EXCEEDS MAX AMT EXCEEDS MAX AMT
249 GPS False EXCEEDS MAX USERS EXCEEDS MAX USERS
250 GPS False INVALID USER ID/PIN INVALID USER ID/PIN
251 GPS False AMOUNT BELOW MINIMUM AMOUNT BELOW MINIMUM
252 GPS False AMOUNT OVER MAXIMUM AMOUNT OVER MAXIMUM
253 GPS False AMOUNT BADLY FORMED AMOUNT BADLY FORMED
254 GPS False INVALID USER ID/PIN INVALID USER ID/PIN
255 GPS False CERT. DOES NOT EXIST CERT. DOES NOT EXIST
256 GPS False INV. CERT. FOR STORE INV. CERT. FOR STORE
257 GPS False CERTIFICATE CLOSED CERTIFICATE CLOSED
258 GPS False CERTIFICATE EXPIRED CERTIFICATE EXPIRED
259 GPS False AMOUNT BELOW MINIMUM AMOUNT BELOW MINIMUM
260 GPS False AMOUNT OVER MAXIMUM AMOUNT OVER MAXIMUM
261 GPS False AMOUNT BADLY FORMED AMOUNT BADLY FORMED
262 GPS False INVALID USER ID/PIN INVALID USER ID/PIN
263 GPS False INVALID AMOUNT INVALID AMOUNT
264 GPS False CERT. ALREADY ACTIVE CERT. ALREADY ACTIVE
265 GPS False CERT. DOES NOT EXIST CERT. DOES NOT EXIST
266 GPS False INVALID USER ID/PIN INVALID USER ID/PIN
267 GPS False CERT. DOES NOT EXIST CERT. DOES NOT EXIST
268 GPS False INV. CERT. FOR STORE INV. CERT. FOR STORE
269 GPS False CERTIFICATE REDEEMED CERTIFICATE REDEEMED
270 GPS False CERTIFICATE EXPIRED CERTIFICATE EXPIRED
271 GPS False VALIDATION NO MATCH VALIDATION NO MATCH
272 GPS False INCORRECT AMOUNT INCORRECT AMOUNT
273 GPS False VALIDATION NO MATCH VALIDATION NO MATCH
274 GPS False INVALID USER ID/PIN INVALID USER ID/PIN
275 GPS False CERT. DOES NOT EXIST CERT. DOES NOT EXIST
276 GPS False INV. TRAN. FOR STORE INV. TRAN. FOR STORE
277 GPS False CERTIFICATE TOO OLD CERTIFICATE TOO OLD
Beanstream Internet Commerce Process Transaction API
Page 21 of 30
Message
Id
Message
Type
Approved Cardholder Message Merchant Message
278 GPS False INCORRECT AMOUNT INCORRECT AMOUNT
279 GPS False Velocity >$Daily Max Velocity >$Daily Max
280 GPS False Velocity >%Daily Max Velocity >%Daily Max
281 GPS False Velocity >Bad Daily Max Velocity >Bad Daily Max
282 GPS False AP DUPE AP DUPE
283 GPS False Msg Error Msg Error
284 GPS False Velocity <$Min Velocity <$Min
285 GPS False Velocity <>Avg Velocity <>Avg
286 GPS False Velocity Neg File Velocity Neg File
287 GPS False Err PinPad Config PPxxxxx Err PinPad Config PPxxxxx
288 GPS False Err Settle File Sharing Err Settle File Sharing
289 GPS False Engine Aborted By Request Engine Aborted By Request
290 GPS False Engine Aborted By Request Engine Aborted By Request
291 GPS False ervice Unavailable - Please try again late Service Unavailable - Please try again later
292 GPS False Err Bad Password Err Bad Password
293 GPS False Err Operation Not Permitted Err Operation Not Permitted
294 GPS False Err Archived Batch Not Found Err Archived Batch Not Found
295 GPS False Err Ext.Data Config EDxxxxx Err Ext.Data Config EDxxxxx
296 GPS False Err Ext.Data Failure EDxxxxx Err Ext.Data Failure EDxxxxx
297 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
298 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
299 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
300 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
301 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
302 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
303 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
304 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
305 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
306 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
307 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
308 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
309 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
310 BIC False
Service Unavailable –
Please try again later
Service Unavailable - Please try again later
311 BIC False 3D Secure Failed 3D Secure Failed
312 BIC False Card type not accepted Card type not accepted
313 BIC False DECLINE Over sales limit
314 BIC False
Missing or invalid payment
information – Please validate
all required payment information
Missing or invalid consumer payment information
315 BIC False CALL HELP DESK HTTPS Connection Required
316 BIC False CALL HELP DESK Invalid transaction validation type
317 BIC False CALL HELP DESK Authentication Failed
Beanstream Internet Commerce Process Transaction API
Page 22 of 30
Message
Id
Message
Type
Approved Cardholder Message Merchant Message
318 BIC False CALL HELP DESK No transaction request data received
319 BIC False CALL HELP DESK Transaction Declined - Restricted transaction type
320 BIC False CALL HELP DESK Missing errorPage URL
321 BIC False CALL HELP DESK Missing or invalid return URL
322 BIC False CALL HELP DESK Transaction amount does not match inventory calculation
323 BIC False CALL HELP DESK One or more products not found in inventory
324 BIC False CALL HELP DESK Invalid product quantity
325 BIC False File Transfer Approved File Transfer Approved
326 BIC True Declined - Invalid bank account Declined - Invalid bank account
327 False DECLINE Declined - Invalid CVD
6.2. Country Codes
ID Name ID Name ID Name
AF Afghanistan DE Germany OM Oman
AL Albania GH Ghana PK Pakistan
DZ Algeria GI Gibraltar PW Palau
AS American Samoa GR Greece PS Palestinian Territory, Occupied
AD Andorra GL Greenland PA Panama
AO Angola GD Grenada PG Papua New Guinea
AI Anguilla GP Guadeloupe PY Paraguay
AQ Antarctica GU Guam PE Peru
AG Antigua and Barbuda GT Guatemala PH Philippines
AR Argentina GN Guinea PN Pitcairn
AM Armenia GW Guinea-Bissau PL Poland
AW Aruba GY Guyana PT Portugal
AU Australia HT Haiti PR Puerto Rico
AT Austria HM Heard and McDonald IslandsQA Qatar
AZ Azerbaijan HN Honduras RE Reunion
BS Bahamas HK Hong Kong RO Romania
BH Bahrain HU Hungary RU Russian Federation
BD Bangladesh IS Iceland RW Rwanda
BB Barbados IN India KN Saint Kitts and Nevis
BY Belarus ID Indonesia LC Saint Lucia
BE Belgium IR Iran (Islamic Republic of) VC Saint Vincent and The Grenadines
BZ Belize IQ Iraq WS Samoa
BJ Benin IE Ireland SM San Marino
BM Bermuda IL Israel ST Sao Tome and Principe
BT Bhutan IT Italy SA Saudi Arabia
BO Bolivia JM Jamaica SN Senegal
BA Bosnia Herzegovina JP Japan SC Seychelles
BW Botswana JO Jordan SL Sierra Leone
BV Bouvet Island KZ Kazakhstan SG Singapore
BR Brazil KE Kenya SK Slovakia
IO British Indian
Ocean Territory
KI Kiribati SI Slovenia
BN Brunei Darussalam KP Korea, Democratic
People's Republic of
SB Solomon Islands
Beanstream Internet Commerce Process Transaction API
Page 23 of 30
ID Name ID Name ID Name
BG Bulgaria KR Korea, Republic of SO Somalia
BF Burkina Faso KW Kuwait ZA South Africa
BI Burundi KG Kyrgyzstan GS South Georgia/
South Sandwich Islands
KH Cambodia LA Lao, People's
Democratic Republic
ES Spain
CM Cameroon LV Latvia LK Sri Lanka
CA Canada LB Lebanon SH St. Helena
CV Cape Verde LS Lesotho PM St. Pierre and Miquelon
KY Cayman Islands LR Liberia SD Sudan
CF Central African Republic LY Libyan Arab Jamahiriya SR Suriname
TD Chad LI Liechtenstein SJ Svalbard and Jan Mayen Islands
CL Chile LT Lithuania SZ Swaziland
CN China LU Luxembourg SE Sweden
CX Christmas Island MO Macau CH Switzerland
CC Cocos (Keeling) Islands MK donia, The Former Yuslav Re
of
SY Syrian Arab Republic
CO Colombia MG Madagascar TW Taiwan, Province of china
KM Comoros MW Malawi TJ Tajikistan
CG Congo MY Malaysia TZ Tanzania, United Republic of
CD o, The Democratic Repub
the
MV Maldives TH Thailand
CK Cook Islands ML Mali TG Togo
CR Costa Rica MT Malta TK Tokelau
CI Cote D'ivoire MH Marshall Islands TO Tonga
HR Croatia MQ Martinique TT Trinidad and Tobago
CU Cuba MR Mauritania TN Tunisia
CY Cyprus MU Mauritius TR Turkey
CZ Czech Republic YT Mayotte TM Turkmenistan
DK Denmark MX Mexico TC Turks and Caicos Islands
DJ Djibouti FM Micronesia TV Tuvalu
DM Dominica MD Moldova, Republic of UG Uganda
DO Dominican Republic MC Monaco UA Ukraine
TP East Timor MN Mongolia AE United Arab Emirates
EC Ecuador MS Montserrat GB United Kingdom
EG Egypt MA Morocco US United States
SV El Salvador MZ Mozambique UM United States Minor Outlying Islands
GQ Equatorial Guinea MM Myanmar UY Uruguay
ER Eritrea NA Namibia UZ Uzbekistan
EE Estonia NR Nauru VU Vanuatu
ET Ethiopia NP Nepal VA Vatican city state
FK alkland Islands (Malvinas NL Netherlands VE Venezuela
FO Faroe Islands AN Netherlands Antilles VN Viet Nam
FJ Fiji NC New Caledonia VG Virgin Islands (British)
FI Finland NZ New Zealand VI Virgin Islands (US)
FR France NI Nicaragua WF Wallis and Futuna Islands
GF French Guiana NE Niger EH Western Sahara
PF French Polynesia NG Nigeria YE Yemen, Republic of
TF rench Southern Territorie NU Niue YU Yugoslavia
GA Gabon NF Norfolk Island ZM Zambia
Beanstream Internet Commerce Process Transaction API
Page 24 of 30
ID Name ID Name ID Name
GM Gambia MP Northern Mariana Islands ZW Zimbabwe
GE Georgia NO Norway
DE Germany OM Oman
6.3. Province/State Codes
ID Name ID Name ID Name
AB AB Alberta MA MA Massachusetts ON ON Ontario
AK AK Alaska MB MB Manitoba OR OR Oregon
AL AL Alabama MD MD Maryland PA PA Pennsylvania
AR AR Arkansas ME ME Maine PE PE Prince Edward Island
AS AS American Samoa MI MI Michigan PR PR Puerto Rico
AZ AZ Arizona MN MN Minnesota QC QC Quebec
BC BC British Columbia MO MO Missouri RI RI Rhode Island
CA CA California MP MP Northern Marianas SC SC South Carolina
CO CO Colorado MS MS Mississippi SD SD South Dakota
CT CT Connecticut MT MT Montana SK SK Saskatachewan
DC DC District of Columbia NB NB New Brunswick TN TN Tennessee
DE DE Delaware NC NC North Carolina TX TX Texas
FL FL Florida ND ND North Dakota UT UT Utah
FM FM Micronesia NE NE Nebraska VA VA Virginia
GA GA Georgia NF NF Newfoundland VI VI Virgin Islands
GU GU Guam NH NH New Hampshire VT VT Vermont
HI HI Hawaii NJ NJ New Jersey WA WA Washington
IA IA Iowa NM NM New Mexico WI WI Wisconsin
ID ID Idaho NS NS Nova Scotia WV WV West Virginia
IL IL Illinois NT NT Northwest Territories/Nunavut WY WY Wyoming
IN IN Indiana NV NV Nevada YT YT Yukon
KS KS Kansas NY NY New York -- Outside U.S./Canada
KY KY Kentucky OH OH Ohio
LA LA Louisiana OK OK Oklahoma
6.4. AVS Response Codes
ID Result Processed Address
Match
Postal/ZIP
Match
Message
0 0 0 0 0 Address Verification not performed for this transaction.
5 0 0 0 0 Invalid AVS Response.
9 0 0 0 0 Address Verification Data contains edit error.
A 0 1 1 0 Street address matches, Postal/ZIP does not match.
B 0 1 1 0 Street address matches, Postal/ZIP not verified.
C 0 1 0 0 Street address and Postal/ZIP not verified.
D 1 1 1 1 Street address and Postal/ZIP match.
E 0 0 0 0 Transaction ineligible.
G 0 0 0 0 Non AVS participant. Information not verified.
I 0 0 0 0 Address information not verified for
international transaction.
M 1 1 1 1 Street address and Postal/ZIP match.
Beanstream Internet Commerce Process Transaction API
Page 25 of 30
ID Result Processed Address
Match
Postal/ZIP
Match
Message
N 0 1 0 0 Street address and Postal/ZIP do not match.
P 0 1 0 1 Postal/ZIP matches. Street address not verified.
R 0 0 0 0 System unavailable or timeout.
S 0 0 0 0 AVS not supported at this time.
U 0 0 0 0 Address information is unavailable.
W 0 1 0 1 Postal/ZIP matches, street address does not match.
X 1 1 1 1 Street address and Postal/ZIP match.
Y 1 1 1 1 Street address and Postal/ZIP match.
Z 0 1 0 1 Postal/ZIP matches, street address does not match.
7. Recurring Transactions
In certain cases you may wish to schedule regular billing for a customer. Companies that charge monthly
service fees (for example internet service providers or magazine distributors) are among those who could
benefit from this option. A recurring billing account can be created for any successful transaction that is
processed and approved by the issuing bank.
To create a recurring billing account for a card holder, you must pass additional parameters indicating
billing frequency and pricing. Please note that you must have the recurring billing option enabled by
Beanstream or these fields will be ignored.
Any field formatting errors that are detected in the recurring billing parameters will be handled as User
Generated Errors (see section 2.3).
7.1. Billing Frequency
Set a schedule for billing a client using the rbBillingPeriod and rbBillingIncrement fields. The billing period
determines how you will calculate pay periods. Set this variable to days, weeks, months, or years. The
billing increment determines how regularly you will charge an account.
For example IF:
The billing period is set to weeks
The billing increment is set to 2
Your customer will be billed every two weeks.
7.2. Billing Dates
Specify exact billing dates using the rbFirstBilling and rbSecondBilling parameters.
rbFirstBilling :
Use this parameter to indicate the date that a recurring billing account first becomes active. The first
billing date can be set to any date in the future and to any date in the past up to one billing frequency
Beanstream Internet Commerce Process Transaction API
Page 26 of 30
minus a day. For example, if you have chosen to bill every week you cannot set the first billing date more
than six days prior to the current system date. If you do not pass a value for this parameter, the first
billing date will default to the current date as recorded by the Beanstream system (in Pacific Standard
Time).
rbSecondBilling :
The parameter rbSecondBilling is the date that the second billing period begins. This second billing date is
used when an account is created partway through a billing period. As the merchant, you will need to
charge the customer only a partial bill for the first billing period. Regular payments will begin with the
second billing period.
For example, a merchant decides to create a recurring billing account set with a $30 monthly fee charged
on the first of the month. For any account created part way through the month the merchant will want to
pro-rate the customer’s first payment. This means that he will want to charge a pro-rated monthly fee
from the time the account is created to the end of the month. For an account created with a first billing
date of April 20 and a second billing date of May 1, the system will calculate the pro-rated amount and
charge $10.00 for the remaining 10 days of April, then the full $30 on May 1st and continue to charge the
full $30 on the 1st of each subsequent month.
If you do not pass a value for this parameter, the default setting for the second billing period will be the
first billing date plus the billing frequency you have chosen. For example, if the first billing date is set at
April 20 and you have chosen to bill once every month, then default settings for the second billing date
will be May 20.
7.3. Recurring Data Variables
The following data variables are used for flagging a transaction request as a Recurring Transaction and for
setting the billing frequency. Please note that these variables must be entered in addition to those listed
in section 5.
Field Name Max
Size
Alpha/
Numeric/
Currency
Required Description
trnRecurring 1 N O Flags a transaction as a recurring item. Enter 1 for a
recurring transaction. The default value of this field is 0,
indicating that the request is not a recurring transaction.
All items with a * must be included if this field is set to 1.
rbBillingPeriod 1 A O* To choose to bill clients according to periods of :
Days enter D
Weeks enter W
Months enter M
Years enter Y.
rbBillingIncrement 255 N O* Choose how often you will charge a client (every two
weeks, every nine days).
rbFirstBilling 8 N O Set to the first recurring billing collection date. See
section 7.1 for details. This value must be formatted as
MMDDYYYY. November 26, 2003 would be passed as
11262003.
rbSecondBilling 8 N O Set to the second recurring billing collection date. See
Section 7.1. This value must be formatted as MMDDYYYY
your first billing was September 1, 2004 and you have cho
Beanstream Internet Commerce Process Transaction API
Page 27 of 30
Field Name Max
Size
Alpha/
Numeric/
Currency
Required Description
to bill once a Month, this value would be 10012004.
rbExpiry 8 N O Set to the date that the recurring billing account will
expire. If no value is passed the account will be flagged
to never expire.
rbApplyTax1 N O If set to the value 1, tax1 will be applied to all recurring
billing payments. If set to a value of 0, no tax1 charges
will be applied. Default value of this field is 0.
rbApplyTax2 N O If set to the value 1, tax2 will be applied to all recurring
billing payments. If set to a value of 0, no tax2 charges w
applied. Default value of this field is 0.
* Field required if trnRecurring is passed with a value of 1.
8. Test Card Numbers
Several test credit card numbers are available to test transaction integration. By using these test cards,
you can emulate the full transaction process, from submitting your payment request to receiving your
payment response.
These test card numbers are only active while your merchant account is in test status. Test card numbers
are listed below, along with their expected response. Any expiry date that is equal to the current month
and year or later is valid.
8.1. Regular Credit Cards
Card Type Card Number Approved/Declined
VISA 4030 0000 1000 1234 Approve
VISA 4003 0505 0004 0005 Decline
MasterCard 5100 0000 1000 1004 Approve
MasterCard 5100 0000 2000 2000 Decline
AMEX 3711 0000 1000 131 Approve
AMEX 3424 0000 1000 180 Decline
8.2. Verified by Visa / MasterCard SecureCode Credit Cards
When Verified by Visa and/or MasterCard SecureCode are enabled, the customer will be asked to submit
their credit card’s password during the checkout process. You can use the following card numbers and
passwords to test VbV and SecureCode.
Card Type Card Number Approved/Declined Password
VISA 4123 4501 3100 3312 Approve 12345
MasterCard 5123 4500 0000 2889 Approve 12345
Beanstream Internet Commerce Process Transaction API
Page 28 of 30
9. URL Encoding Chart
This chart shows the URL-encoded equivalent for every letter in the ASCII set. Items in bold must be
represented with their encoded equivalents when used in a URL; all others are optional.
%00 = %30 = 0 %60 = ` %90 = %C0 = À %F0 = ð
%01 = %31 = 1 %61 = a %91 = ‘ %C1 = Á %F1 = ñ
%02 = %32 = 2 %62 = b %92 = ’ %C2 = Â %F2 = ò
%03 = %33 = 3 %63 = c %93 = “ %C3 = Ã %F3 = ó
%04 = %34 = 4 %64 = d %94 = ” %C4 = Ä %F4 = ô
%05 = %35 = 5 %65 = e %95 = • %C5 = Å %F5 = õ
%06 = %36 = 6 %66 = f %96 = – %C6 = Æ %F6 = ö
%07 = %37 = 7 %67 = g %97 = — %C7 = Ç %F7 = ÷
%08 = %38 = 8 %68 = h %98 = ˜ %C8 = È %F8 = ø
%09 = Tab %39 = 9 %69 = i %99 = ™ %C9 = É %F9 = ù
%0A = LF %3A = : %6A = j %9A = š %CA = Ê %FA = ú
%0B = %3B = ; %6B = k %9B = › %CB = Ë %FB = û
%0C = %3C = < %6C = l %9C = oe %CC = Ì %FC = ü
%0D = CR %3D = = %6D = m %9D = %CD = Í %FD = ý
%0E = %3E = > %6E = n %9E = %CE = Î %FE = þ
%0F = %3F = ? %6F = o %9F = Ÿ %CF = Ï %FF = ÿ
%10 = %40 = @ %70 = p %A0 = %D0 = Ð
%11 = %41 = A %71 = q %A1 = ¡ %D1 = Ñ
%12 = %42 = B %72 = r %A2 = ¢ %D2 = Ò
%13 = %43 = C %73 = s %A3 = £ %D3 = Ó
%14 = %44 = D %74 = t %A4 = ¤ %D4 = Ô
%15 = %45 = E %75 = u %A5 = ¥ %D5 = Õ
%16 = %46 = F %76 = v %A6 = ¦ %D6 = Ö
%17 = %47 = G %77 = w %A7 = § %D7 = ×
%18 = %48 = H %78 = x %A8 = ¨ %D8 = Ø
%19 = %49 = I %79 = y %A9 = © %D9 = Ù
%1A = %4A = J %7A = z %AA = ª %DA = Ú
%1B = %4B = K %7B = { %AB = « %DB = Û
%1C = %4C = L %7C = | %AC = ¬ %DC = Ü
%1D = %4D = M %7D = } %AD = %DD = Ý
%1E = %4E = N %7E = ~ %AE = ® %DE = Þ
%1F = %4F = O %7F = %AF = ¯ %DF = ß
%20 = space %50 = P %80 = %B0 = ° %E0 = à
%21 = ! %51 = Q %81 = %B1 = ± %E1 = á
%22 = " %52 = R %82 = ‚ %B2 = ² %E2 = â
%23 = # %53 = S %83 = ƒ %B3 = ³ %E3 = ã
%24 = $ %54 = T %84 = „ %B4 = ´ %E4 = ä
%25 = % %55 = U %85 = … %B5 = µ %E5 = å
%26 = & %56 = V %86 = † %B6 = ¶ %E6 = æ
%27 = ' %57 = W %87 = ‡ %B7 = · %E7 = ç
%28 = ( %58 = X %88 = ˆ %B8 = ¸ %E8 = è
%29 = ) %59 = Y %89 = ‰ %B9 = ¹ %E9 = é
%2A = * %5A = Z %8A = Š %BA = º %EA = ê
%2B = + %5B = [ %8B = ‹ %BB = » %EB = ë
%2C = , %5C = \ %8C = OE %BC = ¼ %EC = ì
%2D = - %5D = ] %8D = %BD = ½ %ED = í
%2E = . %5E = ^ %8E = %BE = ¾ %EE = î
%2F = / %5F = _ %8F = %BF = ¿ %EF = ï
Beanstream Internet Commerce Process Transaction API
Page 29 of 30
10. Examples
The following is an example of how to call the Process Transaction API using the transaction parameters
listed below:
Merchant Information:
Beanstream Merchant ID = 2
Your Order Number = 288
Transaction Username = ab12345678901234
Transaction Password = cd56789012345678
Transaction Type = default is P for purchase
Error Page to Handle Errors = https://www.beanstream.com/secure/sample/order_form.asp
Customer Information:
Name = Bob Buyer
Email Address = bob@buyer.com
Phone Number = 555-1234
Address1 = 1234 Main St
City = Victoria
Province = BC
Postal Code = V8T5J1
Country = CA
Card Owner = Bob D Buyer
Card Number = 5100000010001004
Card Expiry Month = 10
Card Expiry Year = 03
Optional product information where two products are sold is:
First Product Name = ACER AcerPower SE Minitower
First Product ID or SKU = SYS-ACER
First Product Quantity = 3
First Product Unit Price = $799.95
First Product Extended Price = $2399.85
First Product Tax 1 = $168.00
First Product Tax 2 = $168.00
First Product Shipping Cost = $45.60
Second Product Name = 12/4/32x CD Rocket Mach 12 ReWriter
Second Product ID or SKU = STR-WRITER
Second Product Quantity = 2
Second Product Unit Price = $389.95
Second Product Extended Price = $779.90
Second Product Tax 1 = $54.60
Second Product Tax 2 = $54.60
Second Product Shipping Cost = $12.25
Total Order Information:
Total Shipping Charge = $156.80
Total Tax 1 = $177.57
Total Tax 2 = $177.57
Beanstream Internet Commerce Process Transaction API
Page 30 of 30
Total Product Cost = $3237.60 (Including Shipping, Less Taxes)
Grand Total Cost = $3691.69 (Including Taxes and Shipping)
The call to the Process Transaction API would look like the following:
https://www.beanstream.com/scripts/process_transaction.asp?merchant_id=109040000&username=ab12
345678901234&password=cd56789012345678&trnOrderNumber=288&errorPage=https://www.beanstrea
m.com/samples/order_form.asp&prod_id_1=SYS-ACER&prod_upc_1=SYSCER&
prod_name_1=ACER+AcerPower+SE+Minitower&prod_quantity_1=3&prod_cost_1=799.95&prod_id
_2=STR-WRITER&prod_upc_2=STRWRITER&
prod_name_2=12/4/32x+CD+Rocket+Mach+12+ReWriter&prod_quantity_2=2&prod_cost_2=3
89.95&ordItemPrice=3179.75&ordShippingPrice=156.80&ordTax1Price=177.57&ordTax2Price=177.57&tr
nAmount=3691.69&trnCardOwner=Bob%20D%20Buyer&trnCardNumber=5100000010001004&trnExpMo
nth=10&trnExpYear=08&ordName=Bob%20Buyer&ordEmailAddress=bob@buyer.com&ordPhoneNumber=
555-
1234&ordAddress1=1234%20Main%20St&ordCity=Victoria&ordProvince=BC&ordPostalCode=V8T5J1&ord
Country=CA
Note that this URL has been URL-encoded. Refer to section 5 for a full listing of characters and their URLencoded
equivalents.
