Beanstream Internet Payment Processing
Server-to-Server with Process Transaction
API
Document Version 1.2.4
Last Updated 12/8/2004 11:24 AM
For further information, please contact Beanstream customer support at (250) 472-2326 or
support@beanstream.com.
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 2 of 17
DOCUMENT REVISION HISTORY................................................................................................. 3
OVERVIEW.............................................................................................................................................. 4
1. TRANSACTION PROCESS FLOW....................................................................................... 4
2. BASIC INTEGRATION............................................................................................................. 4
2.1. CREATING THE BROWSER OBJECT ........................................................................................... 4
2.2. SUBMITTING TRANSACTIONS ................................................................................................... 5
2.3. RESPONSE PARAMETERS .......................................................................................................... 5
2.4. ERROR HANDLING ..................................................................................................................... 6
3. INTEGRATING WITH VERIFIED BY VISA................................................................... 6
3.1. TRANSACTION PROCESS FLOW ................................................................................................ 7
3.2. RECOGNIZING THE REDIRECTION RESPONSE MESSAGE........................................................ 9
3.3. TERMINAL URL PAGE................................................................................................................ 9
3.4. SAMPLE INTEGRATION FLOW.................................................................................................... 9
4. TEST CREDIT CARD NUMBERS........................................................................................ 11
4.1. VBV TESTING......................................................................................................................... 11
5. SAMPLE CODES........................................................................................................................ 11
5.1. ASP EXAMPLE......................................................................................................................... 12
5.2. PHP EXAMPLE......................................................................................................................... 12
5.3. JAVA EXAMPLE ......................................................................................................................... 13
5.3.1. To Use This Example .................................................................................................... 14
5.3.2. Troubleshooting.............................................................................................................. 15
5.4. ASP EXAMPLE WITH VERIFIED BY VISA ............................................................................... 16
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 3 of 17
Document Revision History
Date Revision Description Author Revision
Number
08/26/02 Original 1.0
11/11/02 Added code examples Aston Lau 1.1
04/09/03 Added CURLOPT_RETURNTRANSFER to the PHP code
example.
Aston Lau 1.1.1
05/12/03 Added link to ESCA.cer download Aston Lau 1.1.2
05/21/03 Verified by Visa documentation, restructured chapter la Aston Lau 1.2
05/29/03 Verified by Visa process flow diagram Aston Lau 1.2.1
11/06/03 Added a more detailed overview of what Server-to-Ser
does
Aston Lau 1.2.2
11/14/03 Changed section 3.5 to reflect how to test an
implementation of VbV.
Michael Foucher 1.2.3
12/30/03 Page 5 - trnAuthCode - the return variable name is
authCode
Michael Foucher 1.2.4
03/17/2004 Removed reference to VBV test card number Marcus Doty 1.2.5
11/24/04 Changed wording, reformatted document Jane Waite 1.3
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 4 of 17
Overview
Server to Server communication is an integration technique used in conjunction with Process
Transaction API in order to ensure maximum security for each transaction that is processed.
In a normal transaction, at the moment of purchase a customer is transferred from the merchant
server to the Beanstream server and then redirected back to an approved/declined page. While
generally secure, this method does present the possibility that confidential information may be
read while in transition.
Server to Server communication resolves this problem by eliminating much of the jumping back
and forth between servers. Merchant servers are configured to open a separate, secure session
when sending Beanstream any customer transaction details. Beanstream in turn, sends the
transaction details and an approved/declined message back to the secure session. The customer is
informed through there rather than being redirected to the approve/decline pages specified in the
Beanstream Order Settings module.
There are many methods of construction, all of which follow standard methods used in Internet
applications such as POST. The method chosen will depend on the platform and programming
language being used. Code examples for various programming languages are provided in section 5
of this document.
1. Transaction Process Flow
When submitting transactions to Beanstream using Server to Server communication, the
transaction will proceed as follows:
The customer enters their credit card and payment information on the merchant site.
The customer submits their payment information to a processing script on the merchant
site.
The merchant processing script will create a browser object to POST the transaction
request to the Beanstream Process Transaction API.
Beanstream will process the request and return a response back to the browser object
on the merchant site.
The merchant processing script will interpret the response from Beanstream and display
the transaction status to the customer.
Using this method, the need to direct the customer’s browser to the Beanstream site for processing
is removed, as is the redirect request back to the merchant approved/declined page(s).
If there are any transaction errors or problems communicating with Beanstream, these exceptions
can be handled in the merchant processing script and communicated appropriately to the
customer.
2. Basic Integration
2.1. Creating the Browser Object
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 5 of 17
The method employed to create the browser object will depend on the platform and programming
language being used. Code examples for various programming languages are provided in section 5
of this document.
2.2. Submitting Transactions
All of the transaction data sent to Beanstream through an HTML form POST will be sent, without
modification, through the browser object. To comply with data length restrictions, ensure that the
browser object is using the POST method and not the GET method.
An additional parameter must be passed with your request to notify the system that the
transaction request type is Server-to-Server. The system will then respond with querystring
formatted response parameters rather than redirecting to your approval, decline, or error page.
The name of this parameter must be requestType and be set to the value BACKEND.
2.3. Response Parameters
The Beanstream Transaction Server will respond to a transaction request with a list of querystring
formatted response parameters. All approved/declined transactions, and user generated errors will
return this parameter listing. A system generated response will return a text description of the
problem. It will not return the parameter listing. (For more information on error handling, refer to
section 2.4.)
The following parameters will be returned in response to a transaction request. In the Type
column, numbers represent field size, N indicates that a numeric field, while A indicates an
alphanumeric field.
Field Name Type Description
trnApproved 1N 0 = Transaction refused, 1 = Transaction approved
trnId 8N Unique id number used to identify an individual transaction.
messageId 1-2N The id number of the transaction response message.
messageText A The text message associated with the message ID.
authCode 0-32A If the transaction is approved this parameter will contain a unique code used to
validate the returned transaction. Note this parameter will be empty if you have
disabled authorization codes in your membership.
errorType 1A This field will return the value N, S, or U. See section 2.4 for details.
errorFields A If the case of a User Generated error this field will contain a comma
separated listing of all transaction request parameters detected as invalid.
Sample Approval Response:
trnApproved=1&trnId=10048766&messageId=1&messageText=Approved&authCode=TEST&errorT
ype=N&errorFields=
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 6 of 17
Sample Decline Response:
trnApproved=0&trnId=10048769&messageId=16&messageText=Duplicate+transaction&authCode
=&errorType=N&errorFields=
2.4. Error Handling
There are two types of error messages that the Beanstream transaction server may return when
processing a transaction: system generated errors and user generated errors.
System generated errors are activated if a field contains invalid information or is incomplete.
This type of error message is used at the setup stage to help you target problems before your
configuration is up and running for customers.
User generated errors are activated if a customer has entered invalid or incomplete information
in their billing or shipping fields. If a user generated error occurs then the messageText parameter
will contain a full description of all the fields that must be corrected by the user in order for the
transaction request to be accepted. This message is an HTML formatted listing suitable for display
to the user without modification. You may also choose to format your own message back to the
user based on the field listing returned in the errorFields parameter.
For full descriptions of these error messages please see the document titled Process Transaction
API.
To detect if a system generated or user generated error has occurred refer to the errorType
response field. The errorType field will contain one of the following values:
Value Description
N No System Generated or User Generated errors detected in the transaction request.
The transaction has been passed to the bank for authorization.
S A System Generated error has been detected in the transaction request.
U A User Generated error has been detected in the transaction request.
If no errors are detected, the transaction will be processed and the messageText parameter will
contain the response received from the bank. For message codes refer to section 6.1 of the
Process Transaction API document. These messages are suitable for display to the user as is, or
you may decide to only display approved/declined messages based on the value of the trnStatus
response field.
3. Integrating with Verified by Visa
Verified by Visa (VBV) is a security feature that requires customers to enter a password every time
they use their Visa card to complete a transaction.
Unlike the integration for basic transactions, VBV Sever to Server integration requires two
transaction requests. This means that Beanstream can also send two types of transaction response
messages: a redirection response message or a transaction response message.
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 7 of 17
3.1. Transaction Process Flow
Merchants wishing to use the Verified by Visa feature will have to add another step to the
integration process. A VBV-enabled transaction will involve the following steps:
Customer submits the transaction to the merchant.
Merchant submits the transaction to Beanstream.
If a Visa card is used in the transaction, Beanstream will verify if the card is enrolled in
the VBV program. If not, then Beanstream will return a normal transaction response
message and the transaction will end there. If it is a VBV card, then Beanstream will
return a redirection response message to the merchant.
The merchant displays the contents of the redirection response message to the
customer’s web browser. This redirection response page contains a JavaScript redirect
to forward the customer’s browser to the issuing bank, where they enter their VBV
password. When the password authentication is complete, the result of the
authentication is sent back to the merchant.
The merchant sends the authentication result received from the issuing bank to
Beanstream.
Beanstream validates that the password authentication completed successfully. If
authentication is successful, Beanstream will complete the credit card transaction and
return a transaction response message as per normal, indicating whether the
transaction was approved or declined. If the authentication is not successful,
Beanstream will return the appropriate error code to the merchant.
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 8 of 17
Figure 1: Verified by Visa Server-to-Server Process Flow
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 9 of 17
3.2. Recognizing a VBV Redirection Response Message
When you receive a transaction response message from the Beanstream server, you must check
the information in the responseType parameter. You will see either an R or a T.
responseType = R The VISA card submitted in the transaction request is VBV enabled. The
cardholder must be redirected to their issuing bank for password verification.
responseType = T The transaction process is complete and a standard response has been
received.
3.3. Terminal URL Page
You will need to write a simple Terminal URL webpage for your web server.
This page will be used in the following manner:
The customer will enter his or her password.
The data will be transferred to Beanstream’s process_transaction_auth.asp page.
Your Terminal URL webpage will receive the PaRes and MD responses from the Access
Control Server (ACS).
You will also need to identify the Terminal URL to Beanstream when a transaction is first submitted.
The location of the page should be contained in a variable called TermUrl.
3.4. Sample Integration Flow
The following five steps outline how typical request and response messages are passed from the
merchant to Beanstream in the VBV process:
1. A merchant submits the transaction request to Beanstream according to the normal method,
but with an extra parameter called TermUrl that will indicate the location of the Terminal URL
page (cf. section 3.3).
IF the TermUrl is https://www.merchantserver.com/auth_script.asp, the following request
would be POSTed to process_transaction.asp:
requestType=BACKEND&errorPage=https%3A%2F%2Fwww%2Ebeanstream%2Ecom%2Fsamples%2For
der_form.asp&merchant_id=109040000&trnCardOwner=Paul+Randal&trnCardNumber=4030000010001
234&trnExpMonth=01&trnExpYear=05&trnOrderNumber=2232&trnAmount=10.00&ordEmailAddress=pr
andal@mydomain.net&ordName=Paul+Randal&ordPhoneNumber=9999999&ordAddress1=1045+Main+
Street&ordAddress2=&ordCity=Vancouver&ordProvince=BC&ordPostalCode=V8R+1J6&ordCountry=CA&
TermUrl=https%3A%2F%2Fwww%2Emerchantserver%2Ecom%2Fauth_script.asp
2. Beanstream sees that it’s a Visa transaction, and checks to see if the card is enrolled in VBV.
If not, then Beanstream performs the Server to Server transaction according to normal
procedures and returns and approved or declined transaction response message back to
the merchant server. If the card is enrolled in VBV, Beanstream will return the redirection
response message – a page that the merchant needs to display to the customer’s browser.
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 10 of 17
3. The merchant must check whether a transaction response or redirection response message
was returned from Beanstream. They can check for the presence of a redirection response
message by seeing if responseType=R. If a redirection response page is not returned
(responseType=T), then the merchant has the transaction result and the transaction ends. If
a redirection response page is returned, the merchant displays the page (contained in URLencoded
format in the pageContents variable) to the customer’s browser, which redirects the
customer’s browser to the page where the password is entered. A sample redirection
response message can be seen below.
responseType=R&pageContents=%3CHTML%3E%3CHEAD%3E%3C%2FHEAD%3E%3CBODY%3E%3CF
ORM+action%3D%22https%3A%2F%2F203%2E42%2E45%2E62%2F0%2F9uaBIZYbdsFSN7FADKaAsH
3N6O80%22+method%3DPOST+id%3Dform1+name%3Dform1%3E%3CINPUT+type%3Dhidden+name
%3DPaReq+value%3D%22eJxtUl1vgjAUfd%2BvILyPVihf5lqDI0azzJnJHra3DholkYIFhu7Xr0WYW7IHknvO
bc89PReYn4uj8cllnZdiZk4sbBpcpGWWi%2F3MfE2W94E5p3eQHCTn8Y6nreQUnnhdsz038kxdwS7BIcbYd1
078MPQdnFIbIeEvuMT4pkUttELP1EYplA1xLIBjVCpyfTAREOBpafFekPJRF13AQ0QCi7XMe1Jzw9CPLSvNAh
WcJrwujFGIUA9B2nZikZeKHY8QCOAVh7poWmqKUJd11n7il0KLpraSssCkO4Culnatrqqldo5z%2BhTHHX%2
FfF%2BbJJoB0icgYw2nNsYOVnEY2J4Sb2r7gHoeWKFt0AmxMFYPvCKo9JBobOnObwZU6FItZXzIiICfq1Io61
Sl%2BVMDull%2BWOlM00bFFLZssX5%2F%2B8jq5W7jL6P4kUX1ytl4z4E2cj2kFXMdGMFBL6kBIC2DhiWiYf
eq%2BvNPfAM1YLvf%22%3E%3CINPUT+type%3Dhidden+name%3DMD+value%3D%22requestType%
3DBACKEND%2526trnCardNumber%3D4123450131003312%2526trnExpMonth%3D08%2526trnExpYea
r%3D04%2526trnType%3DPA%2526trnAmount%3D14%2E00%2526merchant%5Fid%3D107380000%
2526errorPage%3Dhttps%253A%252F%252Fwww%252Ebeanstream%252Ecom%252Fsamples%252Fo
rder%5Fform%2Easp%2526trnCardOwner%3DPaul%2BRandal%2526trnOrderNumber%3D2232%2526
ordEmailAddress%3Dalau%40beanstream%2Ecom%2526ordName%3DPaul%2BRandal%2526ordPhone
Number%3D9999999%2526ordAddress1%3D1045%2BMain%2BStreet%2526ordAddress2%3D%2526o
rdCity%3DVancouver%2526ordProvince%3DBC%2526ordPostalCode%3DV8R%2B1J6%2526ordCountry
%3DCA%2526TermUrl%3Dhttps%253A%252F%252Fwww%2Ebeanstream%2Ecom%252Fsamples%25
2Fsample%5Fs2s%5Fvbv%5Fauth%2Easp%2526xid%3D350%22%3E%3CINPUT+type%3Dhidden+na
me%3DTermUrl+value%3D%22https%3A%2F%2Fwww%2Ebeanstream%2Ecom%2Fsamples%2Fsampl
e%5Fs2s%5Fvbv%5Fauth%2Easp%22%3E%3C%2FFORM%3E%3CSCRIPT+language%3D%22JavaScri
pt%22%3Edocument%2Eform1%2Esubmit%28%29%3B%3C%2FSCRIPT%3E%3C%2FBODY%3E%3C
%2FHTML%3E
4. After the customer enters the password, the results of the password validation will be POSTed
to the merchant’s Terminal URL page (as indicated by TermUrl that the merchant specified in
step 1). The Terminal URL page will receive a value in a variable called PaRes and another
value in a variable called MD. The merchant’s Terminal URL Page must POST these two
values to Beanstream’s process_transaction_auth.asp. In the following example, the POST is
performed via ASP; this example will be different depending on how the merchant decides to
implement.
<%
'This is a sample Terminal URL page that the merchant must have on their web
'server. The Issuer Access Control Server (ACS) will redirect to this page
'during the Authentication stage (after the customer enters his password).
set objXMLHTTP = Server.CreateObject("MSXML2.ServerXMLHTTP.4.0")
objXMLHTTP.Open "POST", "https://www.beanstream.com/scripts/process_transaction_auth.asp", false
objXMLHTTP.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
objXMLHTTP.Send("PaRes=" & request("PaRes") & "&MD=" & request("MD"))
response.write objXMLHTTP.ResponseText
set objXMLHTTP = nothing
%>
Process_transaction_auth.asp will validate the results of the password authentication. If
authenticated, the Visa transaction will proceed as usual; if not, then a response code of 311 will
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 11 of 17
be returned to the merchant, indicating that the 3D Secure verification failed, and the VISA
transaction will not take place.
4. Test Credit Card Numbers
The following test credit card numbers may be used to test your Server to Server implementation
to the Beanstream system. Any future expiry date equal to the current month and year or later is
valid.
Card Type Card Number Response VBV Enabled
VISA 4123 4501 3100 3312 Approved Yes (Passcode: 12345)
VISA 4030 0000 1000 1234 Approved No
VISA 4003 0505 0004 0005 Declined No
MasterCard 5100 0000 1000 1004 Approved No
MasterCard 5100 0000 2000 2000 Declined No
AMEX 3711 0000 1000 131 Approved No
AMEX 3424 0000 1000 180 Declined No
4.1. VBV Testing
To test your VBV setup, you should process sample transaction against both a VBV enabled credit
card and a standard credit card. This will ensure that you have integrated correctly for both types
of cards.
Although Visa does not currently provide a test card for VBV, you can still test your integration by
processing a live VBV enabled credit card while your setup is in test mode. You will know that your
implementation is successful if you are presented with a VBV password page. The transaction will
proceed as normal but will not be processed.
5. Sample Codes
The following examples demonstrate how to submit a transaction to the Beanstream server via the
Server-To-Server method using various programming languages. In each of these examples, the
following sample parameters will be submitted via HTTPS POST:
requestType=BACKEND&errorPage=https%3A%2F%2Fwww%2Ebeanstream%2Ecom%2Fsamples%2Forder_f
orm.asp&merchant_id=109040000&trnCardOwner=Paul+Randal&trnCardNumber=5100000010001004&trnEx
pMonth=01&trnExpYear=05&trnOrderNumber=2232&trnAmount=10.00&ordEmailAddress=prandal@mydomai
n.net&ordName=Paul+Randal&ordPhoneNumber=9999999&ordAddress1=1045+Main+Street&ordAddress2=&
ordCity=Vancouver&ordProvince=BC&ordPostalCode=V8R+1J6&ordCountry=CA
These parameters will be submitted to the Beanstream payment gateway, which is located at
https://www.beanstream.com/scripts/process_transaction.asp.
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 12 of 17
5.1. ASP Example
The following is an example of how to POST a transaction to the Beanstream server using ASP and
the Microsoft XML Core Services (MSXML) version 4.0. (MSXML is also known as the Microsoft XML
Parser).
We do not recommend using WinInet to do the POST because WinInet is not thread safe, and
hence is not suitable for use in server applications.
To use this example, you must have MSXML 3.0 or 4.0 installed on your server. For more
information on how to download and install MSXML, see the MSDN documentation at
http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdnfiles/
027/001/766/msdncompositedoc.xml
Sample Code
<%
dim objXMLHTTP
'Create the ServerXMLHTTP object
set objXMLHTTP = Server.CreateObject( "MSXML2.ServerXMLHTTP.4.0" )
'This is the location of the Beanstream payment gateway
objXMLHTTP.Open "POST", _
"https://www.beanstream.com/scripts/process_transaction.asp", false
'Set the HTTP header's content type
objXMLHTTP.setRequestHeader "Content-Type", _
"application/x-www-form-urlencoded"
'Send the request with the following POST parameters
objXMLHTTP.Send( "
requestType=BACKEND&errorPage=https%3A%2F%2Fwww%2Ebeanstream%2Ecom%2Fsamples%2F
order_form.asp&merchant_id=109040000&trnCardOwner=Paul+Randal&trnCardNumber=510000001
0001004&trnExpMonth=01&trnExpYear=05&trnOrderNumber=2232&trnAmount=10.00&ordEmailAddr
ess=prandal@mydomain.net&ordName=Paul+Randal&ordPhoneNumber=9999999&ordAddress1=104
5+Main+Street&ordAddress2=&ordCity=Vancouver&ordProvince=BC&ordPostalCode=V8R+1J6&ordCo
untry=CA" )
'Show the response from Beanstream
response.write objXMLHTTP.ResponseText
%>
.
5.2. PHP Example
The following is an example of how to POST a transaction to the Beanstream server using PHP and
the libcurl CURL library.
To use this example, you must install the CURL package. CURL allows you to connect to servers
using a variety of protocols, and in this example, it uses it to communicate with Beanstream via
HTTPS POST. For information on how to install CURL, see the PHP manual at
http://www.php.net/manual/en/ref.curl.php.
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 13 of 17
Sample Code
<?php
// Initialize curl
$ch = curl_init();
// Get curl to POST
curl_setopt( $ch, CURLOPT_POST, 1 );
// Instruct curl to suppress the output from Beanstream, and to directly
// return the transfer instead. (Output will be stored in $txResult.)
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
// This is the location of the Beanstream payment gateway
curl_setopt( $ch, CURLOPT_URL, "https://www.beanstream.com/scripts/process_transaction.asp" );
// These are the transaction parameters that we will POST
curl_setopt( $ch, CURLOPT_POSTFIELDS,
"requestType=BACKEND&errorPage=https%3A%2F%2Fwww%2Ebeanstream%2Ecom%2Fsamples%2
Forder_form.asp&merchant_id=109040000&trnCardOwner=Paul+Randal&trnCardNumber=510000001
0001004&trnExpMonth=01&trnExpYear=05&trnOrderNumber=2232&trnAmount=10.00&ordEmailAddr
ess=prandal@mydomain.net&ordName=Paul+Randal&ordPhoneNumber=9999999&ordAddress1=104
5+Main+Street&ordAddress2=&ordCity=Vancouver&ordProvince=BC&ordPostalCode=V8R+1J6&ordCo
untry=CA" );
// Now POST the transaction. $txResult will contain Beanstream's response
$txResult = curl_exec( $ch );
echo "Result:<BR>";
echo $txResult;
curl_close( $ch );
?>
5.3. Java Example
The section contains an example of how to POST a transaction to the Beanstream server using
Java. It has been tested with JDK 1.3 and 1.4.
Sample Code
import java.io.*;
import java.net.*;
import javax.net.ssl.*;
public class HttpsPost
{
public static void main( String[] args ) throws Exception
{
int ch;
// These are the transaction parameters that we will POST
String messageString =
"requestType=BACKEND&errorPage=https%3A%2F%2Fwww%2Ebeanstream%2Ecom%2Fsamples%2
Forder_form.asp&merchant_id=109040000&trnCardOwner=Paul+Randal&trnCardNumber=510000001
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 14 of 17
0001004&trnExpMonth=01&trnExpYear=05&trnOrderNumber=2232&trnAmount=10.00&ordEmailAddr
ess=prandal@mydomain.net&ordName=Paul+Randal&ordPhoneNumber=9999999&ordAddress1=104
5+Main+Street&ordAddress2=&ordCity=Vancouver&ordProvince=BC&ordPostalCode=V8R+1J6&ordCo
untry=CA";
// Set the location of the Beanstream payment gateway
URL url = new URL( "https://www.beanstream.com/scripts/process_transaction.asp"
);
// Open the connection
URLConnection conn = url.openConnection();
// Set the DoOutput flag to true because we intend
// to use the URL connection for output
conn.setDoOutput( true );
// Send the transaction via HTTPS POST
OutputStream ostream = conn.getOutputStream();
ostream.write( messageString.getBytes() );
ostream.close();
// Get the response from Beanstream
InputStream istream = conn.getInputStream();
while( ( ch = istream.read() ) != -1 )
{
System.out.print( ( char )ch );
}
istream.close();
}
}
5.3.1. To Use This Example
The following is a checklist of things you will need to do in order use the sample code:
Install the Java Secure Socket Extension (JSSE) if you are using a version of the JDK
earlier than 1.4
Ensure that jsse.jar, jnet.jar and jcert.jar are in your classpath if using a version of the
JDK earlier than 1.4
Ensure that the java.security file is complete
Import the Equifax certificate to the client’s (your computer’s) trusted certificate
keystore
Installing JSSE
If you are using a version of the JDK that is earlier than version 1.4, you will need to download and
install the Java Secure Socket Extension. This will implement a Java version of Secure Sockets
Layer (SSL), which is required to securely communicate with the Beanstream server. You can
download it from the Sun website at http://java.sun.com/products/jsse/.
Setting the Classpath
If you are using a version of the JDK that is earlier than version 1.4, you will need to ensure that
jsse.jar, jnet.jar and jcert.jar are in your classpath. In Windows, this is done by modifying the
CLASSPATH environment variable in Control Panel System Advanced tab. Under the
Advanced tab, click the Environment Variables button to bring up the Environment Variables dialog.
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 15 of 17
In the System Variables section of this dialog, make sure there is a variable called CLASSPATH and
that it contains paths to jsse.jar, jnet.jar and jcert.jar.
In UNIX/Linux, there are two ways set the CLASSPATH environment variable, depending on your
shell. In csh, the CLASSPATH is modified with the setenv command. For example:
setenv CLASSPATH=/usr/java/jdk1.3.1_01/jre/lib/jsse.jar
In sh, the CLASSPATH is modified with these commands:
CLASSPATH=/usr/java/jdk1.3.1_01/jre/lib/jsse.jar
export CLASSPATH
Modifying the java.security File
Your java.security file should contain the following lines. If not, you will need to add them.
security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.net.ssl.internal.ssl.Provider
security.provider.3=com.sun.rsajca.Provider
Adding the Equifax Certificate to the Keystore
Beanstream uses a certificate provided by Equifax, which Java does not recognize. Because of this,
you will need to add the Equifax certificate (provided by Beanstream) to your computer's trusted
certificate keystore, which is a file called cacerts. To do this, use the keytool utility provided by the
JDK. For example:
keytool -import -alias equifax -keystore cacerts -file ESCA.cer
The above example will work if you are in the directory where the cacerts file is located and have
copied the ESCA.cer certificate to the same directory. If this is not the case, you will need to
specify the correct pathnames to these files.
In UNIX/Linux, the cacerts file is located in your JDK directory under ./jre/lib/security/. In
Windows, there may be two copies of the cacerts file—one in the JDK directory under
.\jre\lib\security, and one in the Program Files directory under .\java\j2re1.4.0_01\lib\security
(JDK 1.3) or .\java\j2re1.4.0_01\lib\security (JDK 1.4). Usually, the cacerts file in the Program
Files directory is the one that is used, but if that doesn’t work for you, try the one in the JDK
directory.
If you do not have the ESCA.cer file, you can download it from Beanstream via the following URL:
https://www.beanstream.com/admin/support/ESCA.cer
5.3.2. Troubleshooting
Issue:
I’ve imported the Equifax certificate into my cacerts file, but I still get the error: “Exception in
thread "main" javax.net.ssl.SSLHandshakeException: Could not find trusted certificate”.
Resolution:
You may not have added the certificate to the existing cacerts file. If you run the keytool utility to
install the certificate and keystore cannot find the cacerts file, it will create a new one in the
current directory. Make sure that you have added the certificate to the existing cacerts file by
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 16 of 17
specifying the correct path to the cacerts file when running the keytool utility, or by running the
keytool utility while in the directory where cacerts is located.
Also, if you are using Windows, there may be more than one cacerts file. It is commonly located in
both the JDK directory and in Program Files\Javasoft (JDK 1.3) or Program Files\Java (JDK 1.4).
This may be the reason that the Java runtime reports that the certificate has not been imported
into the cacerts file.
Issue:
I get the following error: “java.net.MalformedURLException: unknown protocol: https”.
Resolution:
You need to install the Java Secure Socket Extension (JSSE). You can download it from the Sun
website at http://java.sun.com/products/jsse/.
5.4. ASP Example With Verified by Visa
The following is an example of how to integrate a Verified by Visa-capable solution using ASP and
the Microsoft XML Core Services (MSXML) version 4.0. (MSXML is also known as the Microsoft XML
Parser).
This piece of code will perform the initial transaction request, and if a redirection response page is
found in the response, will show this page to the client’s web browser. The Terminal URL page
used here is https://www.beanstream.com/samples/sample_s2s_vbv_auth.asp; you will have to
change this to whatever location your actual Terminal URL page is located for this example to
work. (The line containing the location of the Terminal URL page has been bolded for your
convenience.)
To use this example, you must have MSXML 3.0 or 4.0 installed on your server. For more
information on how to download and install MSXML, see the MSDN documentation at
http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdnfiles/
027/001/766/msdncompositedoc.xml
Sample Code
<%
dim objXMLHTTP
dim beanstreamResponse
'Create the ServerXMLHTTP object
set objXMLHTTP = Server.CreateObject( "MSXML2.ServerXMLHTTP.4.0" )
'This is the location of the Beanstream payment gateway
objXMLHTTP.Open "POST", "https://www.beanstream.com/scripts/process_transaction.asp", false
'Set the HTTP header's content type
objXMLHTTP.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
'Send the request with the following POST parameters
objXMLHTTP.Send(
"requestType=BACKEND&trnCardNumber=4123450131003312&trnExpMonth=08&trnExpYear=04&trn
Type=PA&trnAmount=11.00&merchant_id=107380000&errorPage=https%3A%2F%2Fwww%2Ebeans
Beanstream Internet Payment Processing Server-to-Server with Process Transaction API
Page 17 of 17
tream%2Ecom%2Fsamples%2Forder_form.asp&trnCardOwner=Paul+Randal&trnOrderNumber=2232&
ordEmailAddress=alau@beanstream.com&ordName=Paul+Randal&ordPhoneNumber=9999999&ordAd
dress1=1045+Main+Street&ordAddress2=&ordCity=Vancouver&ordProvince=BC&ordPostalCode=V8R
+1J6&ordCountry=CA&TermUrl=https%3A%2F%2Fwww.beanstream.com%2Fsamples%2Fs
ample_s2s_vbv_auth.asp" )
beanstreamResponse = objXMLHTTP.ResponseText
'We have now received a response from Beanstream. Now check if this response
'is a Redirection Response Page by checking for the presence of an <HTML> tag.
'If it is a Redirection Response Page, then display this page to the browser.
'If not, then we have the transaction result, so end the transaction.
if InStr( beanstreamResponse, "<HTML>" ) then
'We have a Redirection Response Page, so show it to the browser
response.write beanstreamResponse
else
'This is a normal transaction, so beanstreamResponse contains the
'results of the transaction.
if instr( beanstreamResponse, "trnApproved=1" ) then
response.write "Transaction Approved"
else
response.write "Transaction Declined"
end if
end if
%>
Terminal URL Page Sample Code:
<%
'This is a sample Terminal URL page that the merchant must have on their web
'server. The Issuer Access Control Server (ACS) will redirect to this page
'during the Authentication stage (after the customer enters his password).
set objXMLHTTP = Server.CreateObject("MSXML2.ServerXMLHTTP.4.0")
objXMLHTTP.Open "POST", "https://www.beanstream.com/scripts/process_transaction_auth.asp",
false
objXMLHTTP.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
objXMLHTTP.Send("PaRes=" & request("PaRes") & "&MD=" & request("MD"))
response.write objXMLHTTP.ResponseText
set objXMLHTTP = nothing
%>
