soap tran

Beanstream Internet Payment Processing

SOAP Interface: Client User Guide

Document Version 1.3.6

Last Updated December 6, 2004

Customer_Documentation\Beanstream\English\Processing_Methods\SOAP

For further information please contact Beanstream customer support at (250) 472-2326 or

support@beanstream.com.

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 2 of 16

DOCUMENT REVISION HISTORY...........................................................................................................................................3

OVERVIEW..........................................................................................................................................................................................4

1. TRANSACTION PROCESSING USING SOAP DIAGRAM...................................................................................5

2. INTEGRATING SOAP.........................................................................................................................................................6

2.1. WSDL AND WSML FILES...................................................................................................................................................6

2.2. XML MESSAGE FORMAT......................................................................................................................................................6

2.2.1. Sample Transaction Request XML Message ..................................................................................................6

2.2.2. Sample Transaction Response XML Messages .............................................................................................6

2.3. SUPPORTED DATA VARIABLES ............................................................................................................................................7

2.3.1. General Information ..............................................................................................................................................7

2.3.2. Credit Information ..................................................................................................................................................8

2.3.3. Billing Information..................................................................................................................................................8

2.3.4. Shipping Information ............................................................................................................................................8

2.3.5. Reference Fields......................................................................................................................................................9

2.3.6. Response Parameters ...........................................................................................................................................9

2.4. ERROR HANDLING................................................................................................................................................................9

3. SOAP INTEGRATION WITH VERIFIED BY VISA...............................................................................................11

3.1. TRANSACTION PROCESS FLOW.........................................................................................................................................11

3.2. INTEGRATION PROCEDURE................................................................................................................................................11

3.2.1. Recognizing the Redirection Response Message.......................................................................................11

3.2.2. Terminal URL Page...............................................................................................................................................12

3.3. XML MESSAGE FORMAT....................................................................................................................................................12

3.3.1. Sample Initial Transaction Request XML Message with VBV ................................................................12

3.3.2. Sample Redirection Response Message........................................................................................................12

3.3.3. Sample Authentication Request Message ....................................................................................................13

4. SPECIAL CHARACTERS ..................................................................................................................................................14

5. SAMPLE VB SOAP CLIENT INSTALLATION INSTRUCTIONS......................................................................14

5.1. REQUIREMENTS ..................................................................................................................................................................14

5.2. MS SOAP TOOLKIT 3.0 OVERVIEW................................................................................................................................14

5.3. TOOLKIT INSTALLATION ....................................................................................................................................................15

5.4. DOWNLOADING AND EXECUTING THE SAMPLE CLIENT....................................................................................................16

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 3 of 16

Document Revision History

Date Revision Description Author Revision

Number

05/27/03 Added information on error handling (ER 768) Aston Lau 1.3.1

11/12/03 Renumbered TOC to reflect Revision History chapter Aston Lau 1.3.2

03/11/04 Documented serviceVersion request parameter Shawn Gerty 1.3.3

06/03/04 Added vbvEnabled and scEnabled request

parameters

Aston Lau 1.3.4

08/16/04 Removed reference to outdated online SOAP

reference.

Michael

Foucher

1.3.5

11/26/04 Reformatted document, changed wording Jane Waite 1.4

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 4 of 16

Overview

The Simple Object Access Protocol (SOAP) is a lightweight and simple XML-based protocol that is designed

to exchange structured and typed information on the Web. The purpose of SOAP is to enable rich and

automated Web services based on a shared and open Web infrastructure. SOAP can be used in

combination with a variety of existing Internet protocols and formats including HTTP, SMTP, and MIME and

can support a wide range of applications from messaging systems to RPC.

Getting Started

In order to leverage the SOAP interface, you must have a merchant account with Beanstream and be able

to communicate with our web server via 40-bit or 128-bit SSL.

You must also reference, in conjunction with this document, the Process Transaction API document. There

you will find complete information on error handling, transaction completion and data variables.

The Process Transaction API document can be found in the documentation section of the Beanstream

Membership Area.

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 5 of 16

1. Transaction Processing Using SOAP Diagram

MS SOAP ISAPI

SOAP Service

(COM Object)

WSDL File

MS SOAP Client Web Document 2) Request WSDL 3) Retrieve WDSL

4) Call SOAP Service

5) Send Service Request

6) Call SOAP Service

7) Return Response

1) Submit Request

Beanstream Web Server

Merchant Web Server

Web Browser

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 6 of 16

2. Integrating SOAP

2.1. WSDL and WSML files

The Web Services Description Language (WSDL) and Web Services Meta Language (WSML) files are

located at the following URLs:

http://www.beanstream.com/soap/ProcessTransaction.wsdl

http://www.beanstream.com/soap/ProcessTransaction.wsml

2.2. XML Message Format

Transaction requests are made with a single XML message passed to the TransactionProcess method. The

other method, TransactionProcessAuth, is used by merchants using the Verified by Visa service to validate

the results of the password authentication. See section 3 for more details on Verified by Visa-enabled

SOAP integration.

The following section details sample XML messages for transaction requests and responses. Required and

optional data variables are detailed within section 2.3 of this document. You must also refer to the

Beanstream Process Transaction API document for complete error handling and transaction response

information.

2.2.1. Sample Transaction Request XML Message

<merchant_id>109040000</merchant_id>

<trnCardOwner>Sam Shopper</trnCardOwner>

<ordEmailAddress>user@domain.com</ordEmailAddress>

<ordName>Sam Shopper</ordName>

<ordAddress1>1020 Fort Street</ordAddress1>

<ordCity>Victoria</ordCity>

</transaction>

2.2.2. Sample Transaction Response XML Messages

Example 1 : Approved Transaction Response

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 7 of 16

<messageText>Approved</messageText>

</response>

Example 2 : Transaction Error Response

<messageText>Duplicate transaction</messageText>

</response>

2.3. Supported Data Variables

Field Names that are in bold are required variables.

The Type column, indicates the field size range and the type of characters to be used. Numbers
represent field size range. N denotes that a field is numeric only while A denotes alphanumeric characters

may be used.

Transaction type abbreviations are:

P = Purchase R = Return VP = Void Purchase

VR = Void Return PA = Pre-Authorization PAC = Pre-Authorization Completion

2.3.1. General Information

Field Name Type Description

serviceVersion 1-6 Version of the SOAP service that you are integrating. Set this
parameter to the current service version 1.2

merchant_id 9N Beanstream-assigned nine digit identification number.

trnOrderNumber 30A The order number of the shoppers purchase.

trnType 3A Field indicating the type of transaction to perform (i.e. P, R, VP, VR,
PA, PAC). This is an optional field with a default value of P.

trnAmount 1-10N Total order amount.

adjId 10N This field is required when the transaction type is an R, VP, VR, PAC,
or adjustment, as these transaction types modify a previous

transaction that is identified by this adjustment ID.

username 1-16A

password 1-16A
These fields are required when username/password validation is

turned on. (under Administration Account Settings Order
Settings on your membership page). For more information on this
option, please refer to the Account Settings documentation.
Note that username/password validation is required when the

transaction type is an R, VP, VR, PAC, or adjustment.

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 8 of 16

vbvEnabled 1N If you have requested the Verified by Visa authentication service,

you can pass this parameter to enable or disable VbV for the

transaction. Username/password validation must be enabled in

order to use the vbvEnabled parameter.

Set vbvEnabled to 1 to enable VbV, or 0 to disable it.

scEnabled 1N If you have requested the MasterCard SecureCode authentication

service, you can pass this parameter to enable or disable

SecureCode for the transaction. Username/password validation

must be enabled in order to use the scEnabled parameter.

Set scEnabled to 1 to enable SecureCode, or scEnabled to 0 to

disable it.

2.3.2. Credit Information

Field Name Type Description

trnCardOwner 4-32A Name of the card owner as it appears on their credit card

trnCardNumber 13-20N Customer credit card number

trnExpMonth 2N Customer credit card expiry month

trnExpYear 2N Customer credit card expiry year
trnCardCvd 3-4N Customer credit card CVD number. 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 Membership Area (under Administration Account
Settings Order Settings).

2.3.3. Billing Information

Field Name Type Description

ordName 1-64A Billing contact's name

ordEmailAddress 1-64A Billing contact's email address

ordPhoneNumber 7-32A Billing contact's phone number

ordAddress1 1-32A Billing address
ordAddress2 0-32A Additional billing address field for long addresses

ordCity 1-32A Billing address city

ordProvince 2A Billing province/state ID

ordPostalCode 1-16A Billing address postal/zip code

ordCountry 2A Billing address country ID

2.3.4. Shipping Information

Field Name Type Description

shipName 1-64A Shipping contact's name

shipEmailAddress 1-64A Shipping contact's email address

shipPhoneNumber 7-32A Shipping contact's phone number

shipAddress1 1-32A Shipping address

shipAddress2 0-32A Additional shipping address field for long addresses

shipCity 1-32A Shipping address city

shipProvince 2A Shipping province/state ID.

shipPostalCode 1-16A Shipping address postal/zip code

shipCountry 2A Shipping address country ID.

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 9 of 16

2.3.5. Reference Fields

Added February 20, 2002

Field Name Type Description

ref1 0-256A

ref2 0-256A

ref3 0-256A

ref4 0-256A

ref5 0-256A

These five fields may be used to pass additional information to record with

the transaction request. You may choose to display this data on the

Beanstream email receipt.

2.3.6. Response Parameters

Field Name Type Description

trnId 8N Unique id number used to identify an individual transaction.

trnApproved 1N 0 = Transaction refused, 1 = Transaction approved

messageId 1-2N The id number of the transaction response message.

messageText 0-128A The text message associated with the message ID.

trnAuthCode 0-32N 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.44 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.

Unlike the Process Transaction API, the SOAP interface does not need to return additional details such as

trnAmount, trnOrderNumber. This is because a SOAP call to Beanstream will exist within the same

process or script that processes the response. Within the block of code that contains the SOAP call:

transaction request parameters are set, a call to submit the transaction is made, and the collection of

response parameters are received. With the order amount and order number being set just a few lines

above in the code, there is no reason to return these identical values back in the response parameters.

One exception to this is when no order number is passed with the SOAP transaction request. The

Beanstream system will assign an order number in this case. This order number, however, will be

identical to the Transaction ID (trnId) field. The merchant should refer to the trnId value for

Beanstream’s automatically-generated order number.

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.

To detect if an 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 have been detected the transaction will be processed and the messageText parameter will

contain the response received from the bank. This message will be one of the ones listed in section 6 of

the Process Transaction API document. These messages are suitable for display to the user as is, or you

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 10 of 16

may decide to only display Approved or Declined messages based on the value of the trnStatus response

field.

System Generated Errors

To help debug your 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.

We recommended that you handle these messages in your code so that in the unlikely case that a System

Generated error does occur, you will have a mechanism to be notified. The only reason this may happen

would be if you make code changes or if the account configuration settings have been changed in your

Beanstream membership area.

Possible error messages include:

Connection is not secure

Invalid merchant ID

Authorization Failed

Missing transaction data

Missing errorPage address

Sample System Generated Error response:
trnApproved=0&trnId=0&messageId=0&messageText=Authorization+Failed&authCode=&errorType=S&er

rorFields=

User Generated Errors

If any of the credit information or billing information is invalid or missing, Process Transaction will respond

with a User Generated Error.

If a User Generated Error has occurred then the messageText parameter will contain a descriptive listing

of all 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.

The errorFields parameter will contain a comma separated listing of field names in the transaction request

that contain missing or invalid values. If no User Generated Errors are returned, or if a System Generated

Error is returned, the errorFields parameter will not contain a value.

Sample User Generated Error response:
trnApproved=0trnId=0&messageId=0&messageText=%3CLI%3EEnter+your+name%3Cbr%3E%3CLI%3

EEnter+your+email+address%3Cbr%3E%3CLI%3EEnter+your+city%3Cbr%3E%3Cbr%3E&authCode=&e

rrorType=U&errorFields=ordName%2CordEmailAddress%2CordCity

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 11 of 16

3. SOAP Integration with Verified by Visa

Verified by Visa (VBV) is a security initiative that protects Visa credit cards with a password. Every time

the card is used, the customer must enter his or her password to complete the transaction.

Where the non-VBV integration involved only one transaction request and the corresponding transaction

response, VBV-enabled integration will involve an extra request. This means that there are two types of

responses that Beanstream can return:

Redirection response message

Transaction response message

An explanation of the request and response messages involved is described below.

3.1. Transaction Process Flow

Merchants using VBV will have to add an extra steip in their integration. A VBV-enabled transaction will

involve the following steps:

A customer submits the transaction to the merchant.

The merchant submits the transaction to Beanstream via the SOAP transaction interface’s

TransactionProcess method.

If a Visa card is used, Beanstream will check if the card is enrolled in the VBV program. If not,

then Beanstream will return a normal approved or declined response message. If it is a VBV card,

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 will do a JavaScript redirect from the customer’s browser

to the issuing bank. The customer will enter their VBV password here. The results of the

completed authentication are sent back to the merchant.

The merchant sends the authentication result to Beanstream via the SOAP transaction interface’s

TransactionProcessAuth method.

Beanstream validates that the password authentication was 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.

3.2. Integration Procedure

3.2.1. Recognizing the Redirection Response Message

To recognize a response redirection message, check the <responseType> tag.

If the <responseTag> contains an R the Visa card is VBV enabled. The cardholder must be

redirected to their issuing bank for password verification

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 12 of 16

If the <responseTag> contains a T, the card is not VBV enabled. The transaction process is

complete and a standard approved/declined response has been received.

If the <responseType> tag contains “R”, then the <redirectionPage> tag will contain XML-Encoded
HTML redirection code. This is forwarded to the clients to instruct the browser to redirect to the Access

Control Server’s (ACS) password page. Please note that the contents of the <redirectionPage> parameter

must be XML-decoded as specified in section 4 of this document. For example, the “>” symbol must be

converted to “>”.

3.2.2. Terminal URL Page

You will need to create a simple Terminal URL page to reside on your server. This page will receive the

PaRes and MD responses from the Access Control Server (ACS). These responses are passed after the
customer enters his or her password and forwards the information to Beanstream via the SOAP

transaction interface’s TransactionProcessAuth method.

The merchant will also need to pass the location of the Terminal URL to Beanstream when the transaction

is first submitted. The location of the page should be contained in a variable called termUrl.

3.3. XML Message Format

3.3.1. Sample Initial Transaction Request XML Message with VBV

There will only be one important difference between this format and the format outlined in section 2.2.

A termUrl tag must be included containing the location of the Terminal URL page.

<merchant_id>109040000</merchant_id>

<trnCardOwner>Sam Shopper</trnCardOwner>

<ordEmailAddress>user@domain.com</ordEmailAddress>

<ordName>Sam Shopper</ordName>

<ordAddress1>1020 Fort Street</ordAddress1>

<ordCity>Victoria</ordCity>

<termUrl>https://www.merchantserver.com/auth_script.asp</termUrl>

</transaction>

3.3.2. Sample Redirection Response Message

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 13 of 16

<HTML>

<BODY>

<FORM action="https://203.42.45.62/0/OpcDm6RJC53xKnDd3OKDTbt6pwA0" method=POST id=form1

name=form1>

<INPUT type=hidden name=PaReq

value="eJxtUl1vgjAUfd+vILyPtnwJ5lrDJMuccRrHfgArjZJJQShD9+vXIswt2UOTe85tzz333sL8XByNT143eSlmJrGwa

XDByiwX+5n5ljzeB+ac3kFyqDmPXzlra05hzZsm3XMjz9QT7DluYJPQ9kPHdkNCHNtxw4k9IW4YYJPCNtrxE4WhCFU1LBvQ

CJVYzQ6pkBRSdnpYvlCXKAEP0ACh4PUypj3pT4IQD+krDSItOE14I41RCFDPAStbIesLxY4PaATQ1kd6kLKaItR1nbWv0kvB

hWwsVhaAdBbQzdK21VGj1M55Rtdx1P1zvtbxxwyQvgFZKjm1MXawZxMDk6nnT4lqt+chLbQNStQMsGrwiqDSRaIxpTO/G

VAzr9VOxkZGBPxclUJZp0r+JwZ0s7x40jNlUo1pU7G48HfPC885r0ScOZtVnLxLv+oibeR6SSvmemAuDnpJDQBpGTQsEQ2r

V9GfL/ENzmm8Fw==">

<INPUT type=hidden name=MD

value="requestType=BACKEND&trnCardNumber=4123450131003312&trnExpMonth=08&trnExp

Year=04&trnType=PA&trnAmount=11.00&merchant_id=107380000&errorPage=https%3A%2F%

2Fwww%2Ebeanstream%2Ecom%2Fsamples%2Forder_form.asp&trnCardOwner=Paul+Randal&trnOrderNu

mber=2232&ordEmailAddress=alau@beanstream.com&ordName=Paul+Randal&ordPhoneNumber=99

99999&ordAddress1=1045+Main+Street&ordAddress2=&ordCity=Vancouver&ordProvince=BC&a

mp;ordPostalCode=V8R+1J6&ordCountry=CA&TermUrl=https%3A%2F%2Fwww.beanstream.com%2Fsamp

les%2Fsample_s2s_vbv_auth.asp&xid=309">

</FORM>

document.form1.submit();

</SCRIPT>

</BODY>

</HTML>

</redirectionPage>

</response>

3.3.3. Sample Authentication Request Message

When the customer completes the password authentication, the results of the authentication are sent back

to the merchant via the merchant’s Terminal URL page. Two parameters will be sent to the Terminal URL

page: md and paRes.

The merchant must formulate the following XML message and send it to Beanstream via the SOAP

transaction interface’s TransactionProcessAuth method.

<md>requestType=SOAP&trnCardNumber=4123450131003312&trnExpMonth=08&trnExpYear

=04&trnType=PA&trnAmount=11.00&merchant_id=107380000&errorPage=https%3A%2F%2Fw

ww%2Ebeanstream%2Ecom%2Fsamples%2Forder_form.asp&trnCardOwner=Paul+Randal&trnOrderNumbe

r=2232&ordEmailAddress=alau@beanstream.com&ordName=Paul+Randal&ordPhoneNumber=999999

9&ordAddress1=1045+Main+Street&ordAddress2=&ordCity=Vancouver&ordProvince=BC&o

rdPostalCode=V8R+1J6&ordCountry=CA&TermUrl=https%3A%2F%2Fwww.beanstream.com%2Fsamples%

2Fsample_s2s_vbv_auth.asp&xid=310</md>

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 14 of 16

<paRes>eJxlUdtuwjAMfd9XVH1f46R3ZIJgaBoPTLuwD8haCyrRFtJ2ZX+/BFrYtCiRfOwcX45xdir3zhfppqirqcs9cB2

qsjovqu3U/dg83ifuTN7hZqeJlu+UdZokrqlp1JacIjcUCIUf8DQUoeDmgIAE/CDy0yROeRS6El/mb3SUOFSRpognkI3QZNPZT

lWtRJUdF6tnGYQiBUA2QCxJr5ZSiAiCKDTMC8ZKlSQXpKqm1aRKZGcHZnVXtfpbchEgGwF2ei93bXuYMNb3vfd5pXlZbag2j

OzWyUtnrcakOxW5XC/n/f+3gvXmdYrM/sBctSQFgA8hxI7gEy7MRXb2oyptH3ZyO9YF4MHWmA8RG/jtQKO0NpsY5xgR0ul

QV2R+mORXG9mt4YcnK2TWWsliDhH4wk9EGnCIraTngM1SGFkgsM4BILNUNmyLDUs21p/l/wBZzLOy</paRes>

</transaction>

4. Special Characters

Before submitting your transaction to the Beanstream Transaction Server, all XML special characters must

be converted to their associated Entity Reference. The Beanstream Transaction Server uses a fully

compliant XML parser to retrieve your transaction details. If XML special characters are detected, the

transaction request will be declined.

An Entity Reference is a named or numeric code that allows the XML parser to interpret the special

character. There are five named Entity References that the XML parser will handle, and are listed in the

table below. Any additional Entity References you wish to use must be declared within your message.

Special

Character

Entity Reference

& &

< <

> >

" &quote;

‘ '

5. Sample VB SOAP Client Installation Instructions

5.1. Requirements

You must have Visual Basic to compile the sample client. IIS 5.0 or above must be installed on your web

server.

5.2. MS SOAP Toolkit 3.0 Overview

The Microsoft Simple Object Access Protocol (SOAP) Toolkit 3.0 consists of:

A client-side component that allows an application to invoke Web service operations described by a

Web Services Description Language (WSDL) document

A server-side component that maps invoked Web service operations to COM object method calls as

described by the WSDL and Web Services Meta Language (WSML) files. This file is necessary for

Microsoft's implementation of SOAP

Necessary components that construct, transmit, read, and process SOAP messages. These

processes are collectively referred to as marshalling and unmarshalling

In addition, the SOAP Toolkit 3.0 provides additional tools that simplify application development:

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 15 of 16

A WSDL/WSML Generator tool that generates the WSDL and WSML files for you, relieving you of

the often tedious process of manually creating such files

An alternative to the XML DOM API to process XML documents in the SOAP messages - called the

SOAP Messaging Object (SMO) framework. This Microsoft Visual Basic add-in generates message

part objects that simplify the creation and processing of XML documents contained in SOAP

messages.

5.3. Toolkit Installation

Install the MS SOAP Toolkit 3.0 on your web server and on the workstation running Visual Basic.

Click the SoapToolkit30.exe icon …

Follow the installation wizard.

Beanstream Internet Commerce SOAP Interface: Client User Guide

Page 16 of 16

5.4. Downloading and Executing the Sample Client

Download the Visual Basic sample SOAP Transaction Client project from the following URL:

http://www.beanstream.com/support/SoapTransactionClient.zip

Extract the project files from the compressed archive using WinZIP (http://www.winzip.com)

into a folder on the workstation running Visual Basic.

Open the SoapTranactionClient.vbp project file.

Run the program to submit a test transaction by pressing F5 or by selecting Start under the

Run menu.

posted on 2005-03-02 09:29 毛小华阅读(1190) 评论(0) 编辑收藏举报

刷新页面返回顶部

sadier

公告