Banner General
Web Services Handbook
October 2009
Trademark, Publishing Statement and Copyright Notice
SunGard or its subsidiaries in the U.S. and other countries is the owner of numerous marks, including “SunGard,” the SunGard logo,
“Banner,” “PowerCAMPUS,” “Advance,” “Luminis,” “fsaATLAS,” “DegreeWorks,” “SEVIS Connection,” “SmartCall,” “PocketRecruiter,”
“UDC,” and “Unified Digital Campus.” Other names and marks used in this material are owned by third parties.
© 2009 SunGard. All rights reserved.
Contains confidential and proprietary information of SunGard and its subsidiaries. Use of these materials is limited to SunGard Higher
Education licensees, and is subject to the terms and conditions of one or more written license agreements between SunGard Higher
Education and the licensee in question.
In preparing and providing this publication, SunGard Higher Education is not rendering legal, accounting, or other similar professional
services. SunGard Higher Education makes no claims that an institution's use of this publication or the software for which it is provided will
insure compliance with applicable federal or state laws, rules, or regulations. Each organization should seek legal, accounting and other
similar professional services from competent providers of the organization’s own choosing.
Prepared by: SunGard Higher Education
4 Country View Road
Malvern, Pennsylvania 19355
United States of America
(800) 522 - 4827
Customer Support Center Website
http://connect.sungardhe.com
Documentation Feedback
http://education.sungardhe.com/survey/documentation.html
Distribution Services E-mail Address
distserv@sungardhe.com
Prepared For
Banner General 7.3
Banner General 8.0
Revision History Log
Publication Date
Summary
October 2009
New version that supports Banner software.
Banner General
Web Services Handbook
Contents
Chapter 1
Introduction
What is a Web service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
How do Banner Web services work?. . . . . . . . . . . . . . . . . . . . . . . 5
Banner Payment Transaction Service Adapter . . . . . . . . . . . . . . . . . 6
Contents of this handbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Chapter 2
Adapter Deployment and Configuration
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Step 1 Create OC4J instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Step 2 Deploy the adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Step 3 Define data sources for the adapter . . . . . . . . . . . . . . . . . . . . . 12
Step 4 Configure jazn security roles and users . . . . . . . . . . . . . . . . . . . 16
Step 5 Configure OC4J instance for schema validations (optional) . . . . . . . . 18
Step 6 Configure adapter logging . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Step 7 Update WSDL endpoint URL . . . . . . . . . . . . . . . . . . . . . . . . 20
Chapter 3
PaymentTransaction
Web Service
Intended usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
AddAccountTransaction operation . . . . . . . . . . . . . . . . . . . . . . . . . 24
AddAccountTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
October 2009
Banner General
Web Services Handbook
Contents
3
ConfirmAddAccountTransaction . . . . . . . . . . . . . . . . . . . . . . . . . 25
SOAP fault messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
ReportTransactionError operation . . . . . . . . . . . . . . . . . . . . . . . . . 26
ReportTransactionError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
ConfirmReportTransactionError . . . . . . . . . . . . . . . . . . . . . . . . . . 26
SOAP fault messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Message mapping to Banner . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
AddAccountTransaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
ConfirmAddAccountTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . 28
ReportTransactionError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
ConfirmReportTransactionError. . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Setup requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Payment cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Payment combinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4
Banner General
Web Services Handbook
Contents
October 2009
1
Introduction
This chapter introduces Web services, describes how Banner APIs are exposed as Web
services, and introduces the Banner Payment Transaction Service Adapter.
What is a Web service?
A Web service is an exposure of an application’s processing logic that supports a serviceoriented architecture and facilitates integration with external systems. A Web service
allows an external system or business process to invoke the application’s logic without
having to understand the application’s internal structure.
Web services can be thought of as application programming interfaces (APIs). What
distinguishes Web services, however, is their foundation in open, Internet-based standards.
This makes them relevant to application integration both within and between
organizations. Standards such as XML, SOAP, WSDL, and UDDI provide cross-platform
compatibility that does not depend on a single programming language or network
transport.
How do Banner Web services work?
The Banner Web Services Adapter is a configurable Java-based application that exposes
key Banner functions as Web services, making these Banner functions available to
external systems using the SOAP protocol over HTTP/HTTPS. External systems interact
with the Web services, which in turn are supported by Banner APIs. This layered approach
provides an insulating buffer between external systems and Banner. External systems do
not interact with Banner directly, but rather exchange XML messages with the exposed
Web services.
The Banner Web Services Adapter supports the synchronous, request/reply message
exchange pattern:
1. An external system requests a service of Banner by sending an XML message to the
Web service endpoint exposed by the adapter. The message contains the information
required for Banner to service the request.
2. The Banner Web Services Adapter invokes the appropriate Banner API.
3. The Banner API performs the necessary Banner processing logic.
October 2009
Banner General
Web Services Handbook
Introduction
5
4. If the action is completed successfully, the API provides a response message that the
adapter forwards to the external system.
If the action is not completed successfully, the adapter sends an error message (called
a SOAP fault) to the external system.
Banner Payment Transaction Service
Adapter
The Banner Payment Transaction Service Adapter is a pre-configured instance of the
Banner Web Services Adapter. This instance exposes Web services provided by Banner
General.
The adapter is delivered as an Enterprise Archive (EAR) file. The file is a J2EE
application that can be deployed in an Oracle Application Server OC4J (Oracle
Components for Java) instance. EAR files are standard Java archive files and have the file
extension .ear. An EAR file can consist of any combination of the following:
• One or more Web modules
• One or more EJB modules
• One or more application client modules
• Additional JAR files required by the application
For Banner General 8.x and 7.x, the Banner Payment Transaction Service Adapter
(pci_services.ear) is available as a separate download. For all subsequent Banner
General releases, the adapter is available in the Banner General Java subdirectory.
Contents of this handbook
This handbook provides the steps used by systems administrators to install and configure
the Banner Payment Transaction Service Adapter. This handbook also includes the
following information used by integration analysts and business analysts to understand the
PaymentTransaction Web service:
• Intended usage
• Message exchange pattern and specific messages used
• Mapping between message elements/attributes and Banner columns
• Setup requirements
6
Banner General
Web Services Handbook
Introduction
October 2009
2
Adapter Deployment and
Configuration
The Banner Payment Transaction Service Adapter exposes the PaymentTransaction Web
service. The adapter must be deployed to the Oracle Application Server inside an OC4J
container. Oracle Containers for J2EE (OC4J) is the J2EE runtime component of Oracle
Application Server. This chapter provides the steps for deploying and configuring the
Banner Payment Transaction Service Adapter.
Prerequisites
The Banner Payment Transaction Service Adapter must be installed to Oracle Application
Server 10g. The following versions and patches are supported:
• 10.1.2.0.2 with patch 5231566
• 10.1.2.3
The adapter also requires the following Banner products:
Banner 7.x
Product
Minimum Version
Banner General
Banner Web General
Banner Web Tailor
7.3 with patch p1-639eor_gen70600
7.4 with patch p1-639er2_bwg70301
7.4.0.1 with patch p1-7549th_twb70401
Banner 8.x
October 2009
Product
Minimum Version
Banner General
Banner Web General
Banner Web Tailor
8.0 with patch p1-639eqc_gen80200
8.0 with patch p1-639es5_bwg80200
8.0 with patch p1-7549uz_twb80201
Banner General
Web Services Handbook
Adapter Deployment and Configuration
7
Steps
Use the following steps to deploy and configure the Banner Payment Transaction Service
Adapter:
• Step 1, “Create OC4J instance”
• Step 2, “Deploy the adapter”
• Step 3, “Define data sources for the adapter”
• Step 4, “Configure jazn security roles and users”
• Step 5, “Configure OC4J instance for schema validations (optional)”
• Step 6, “Configure adapter logging”
• Step 7, “Update WSDL endpoint URL”
This chapter describes each step in detail.
Note
A quick way to start using the adapter is to deploy it to an existing OC4J
instance where Banner Web service adapters are already deployed.
„
Step 1
Create OC4J instance
If you are deploying the Banner Payment Transaction Service Adapter to an existing OC4J
instance, you can skip this step.
If you are deploying the adapter to a new OC4J instance on the Oracle Application Server,
you must create the instance. This instance should be separate from the default “home” so
you can separately administer the Web services environment.
Note
Throughout this chapter, <OC4J instance> denotes the OC4J instance
where the Banner Payment Transaction Service Adapter is deployed.
Illustrations show a sample deployment where the OC4J instance is
named BWS.
„
Use the following steps to create a new OC4J instance for the adapter.
8
Banner General
Web Services Handbook
Adapter Deployment and Configuration
October 2009
1. Use a Web browser to log in to the Oracle Enterprise Manager Console. The console
is displayed:
2. Click Create OC4J Instance. The console displays the Create OC4J Instance page.
3. Enter the name of the new instance. You can choose any meaningful name for the
new instance.
4. Click Create. The console displays a message that the instance was created.
5. Click OK. The console is displayed:
October 2009
Banner General
Web Services Handbook
Adapter Deployment and Configuration
9
Step 2
Deploy the adapter
Use the following steps to deploy the Banner Payment Transaction Service Adapter.
1. From the System Components table on the Oracle Enterprise Manager Console, click
the name of the OC4J instance where the adapter is to be deployed. The console
displays the Home page for the selected instance:
2. Select the Applications tab. The console displays a list of deployed applications:
3. Click Deploy EAR File. The console displays the Deploy Application page:
4. Click Browse and navigate to the location of the pci_services.ear file.
5. Select the file and click Open.
6. Specify the Application Name (for example, Payment_Transaction_Service).
10
Banner General
Web Services Handbook
Adapter Deployment and Configuration
October 2009
7. For Parent Application, select default. The following figure shows the Deploy
Application page with all parameters specified:
8. Click Continue. The console displays a URL mapping page with the URL mapping
defined in the ear file. The displayed text string is the configurable part of the default
URL exposed by the adapter: <http:// or https://><server name>:<port
number>/pci/v1_0.
9. (Optional) If desired, change the URL mapping by adding to the default string. Note
any change below, and be sure to take this change into account in subsequent steps
that refer to the default URL.
New URL mapping:________________________________________________
Changing the URL mapping is beneficial if multiple adapters of the same type are
being installed on the same server in different OC4J instances. These can be
delineated by adding a descriptive text string, such as /test or /prod to the default
/pci text string. While not necessary, it is recommended that the default string is
augmented rather than changed entirely.
10. Click Finish. The console displays the deployment options:
11. Click Deploy to accept the values and deploy the adapter. The console displays a
confirmation page when the adapter is successfully deployed.
October 2009
Banner General
Web Services Handbook
Adapter Deployment and Configuration
11
12. Click OK to continue. The console displays the Applications tab with the deployed
application:
For additional information on deployment or if you have deployment errors, refer to
Oracle® Application Server Containers for J2EE User's Guide 10g, Release 2 (10.1.2).
Step 3
Define data sources for the adapter
A data source provides the connection properties to the Banner database. By default, the
adapter needs two data sources with the following lookup names: jdbc/bannerws and
jdbc/transsvc.
The steps used to define these data sources depend on whether the data sources already
exist.
If the data sources exist with the default lookup names
If you already installed a Banner Web Services Adapter in the OC4J instance, then the data
sources should already exist. The same data sources can be used for multiple adapters.
If the data sources do not exist
Use the following steps to define the data sources if they do not currently exist.
1. Select the Administration tab from the Home page of the OC4J instance where the
adapter is deployed. The console displays administration options:
12
Banner General
Web Services Handbook
Adapter Deployment and Configuration
October 2009
2. Select Data Sources from the Application Defaults section. The console displays a
list of data sources for the instance:
3. Click Create to create a new data source. The console displays the Create Data
Source page with the following sections:
• General
• Datasource Username and Password
• JNDI Locations
• Connection Attributes
• Properties - not needed
4. Enter the following information in the General section:
October 2009
Name
bannerwsDS
(This is an example. Enter the name of your choice.)
Data Source Class
com.evermind.sql.DriverManagerDataSource
JDBC URL
jdbc:oracle:thin:@host:port:SID where
host = database host
port = database listener port (usually 1521 or 1549)
SID = database instance
JDBC Driver
oracle.jdbc.driver.OracleDriver
Banner General
Web Services Handbook
Adapter Deployment and Configuration
13
5. Enter the following information in the Datasource Username and Password section:
Username
integmgr
Use Cleartext Password
Select the Use Cleartext Password button and provide a
password for the integmgr Oracle user.
6. Enter the following information in the JNDI Locations section:
Location
jdbc/bannerws
Transactional(XA)
Location
jdbc/xa/bannerwsXA
EJB Location
jdbc/bannerws
7. Enter the following information in the Connection Attributes section:
14
Banner General
Web Services Handbook
Adapter Deployment and Configuration
October 2009
Connection Retry
Interval (seconds)
1
Cached Connection
Inactivity Timeout
(seconds)
30
Maximum Open
Connections
Recommended value is 5. Depending on the usage, this
value can be tuned.
Minimum Open
Connections
Recommended value is 1.
8. Click Create. The required data source is created in data-sources.xml in the
directory. The console displays a
confirmation message and asks if you would like to restart the server.
%IAS_HOME%/j2ee/<OC4J instance>/config
9. Click No to return to the Data Sources page.
10. Select the radio button next to the data source you just created.
11. Click Create Like.
12. Enter the following information in the General section, keeping the default values in
all other fields:
Name
Transsvc
(This is an example. Enter the name of your choice.)
13. Enter the following information in the JNDI Locations section:
Location
jdbc/transsvc
Transactional(XA)
Location
jdbc/xa/transsvc
EJB Location
jdbc/transsvc
14. Click Create. The required data source is created in data-sources.xml in the
directory, and the console displays a
confirmation message and asks if you would like to restart the server.
%IAS_HOME%/j2ee/<OC4J instance>/config
15. Click Yes to restart the server.
October 2009
Banner General
Web Services Handbook
Adapter Deployment and Configuration
15
16. When the server confirms that the instance was restarted, click OK. The console
displays the list of all data sources:
If the data sources exist with different lookup names (not common)
If you already have data sources defined with different lookup names, use the following
steps to modify the adapter configuration to accommodate the existing data source lookup
names.
1. Navigate to the iAS installation directory:
%IAS_HOME%/j2ee/<OC4J instance>/applications/<deployed application
name>/pci_web/WEB-INF/classes
2. Open process-config.xml with an editor.
3. Modify the <DataSourceLookupName>jdbc/bannerws</DataSourceLookupName>
XML tag by replacing jdbc/bannerws with the existing data source lookup name.
4. Restart the OC4J instance for the changes to take effect.
Step 4
Configure jazn security roles and users
To protect each defined endpoint, jazn security roles and users must be established for the
Banner Payment Transaction Service Adapter. Security roles and users are defined at the
application level, not the OC4J instance level. Use the following steps to create a security
group and add users to that group for the adapter.
1. Select the Applications tab from the Home page of the OC4J instance where the
adapter is installed. The console displays a list of deployed applications.
2. Select the radio button of the adapter for which security roles and users are to be
defined.
3. Click Edit. The console displays the Application configuration page.
4. Select Security from the Administration section. The console displays the Security
page:
16
Banner General
Web Services Handbook
Adapter Deployment and Configuration
October 2009
5. Click Add Group in the Groups section. The console displays the Security: Add
Group page.
6. Enter the following information:
Name
jazn.com/pci_ws_clients
(This is an example. Enter the name of your choice.)
Description
Security access group for the adapter
7. Click OK to create the required group. The console displays the Security page with
the new group.
8. Click Add User in the Users section. The console displays the Security: Add User
page.
9. Enter the following information in the General section:
October 2009
Name
jazn.com/payment_vendor
(This is an example. Enter the name of your choice.)
Description
Banner Payment Transaction Service Adapter User
Banner General
Web Services Handbook
Adapter Deployment and Configuration
17
Password
Password for the user being created.
Confirm Password
Confirmation of the password for the user being created.
10. Assign this new user to the jazn.com/pci_ws_clients group by checking the
corresponding check box in the Group Memberships section on the same Security:
Add User page:
11. Click OK to create the user. The console displays the Security page with the new
user.
12. Verify that the new user is assigned to the jazn.com/pci_ws_clients group.
13. Click Map Role to Principals in the Security Roles section. The console displays the
Role page:
14. Select the jazn.com/pci_ws_clients group name.
15. Click Apply. The console displays a confirmation page.
16. Click OK. The Role page is redisplayed.
17. Return to the Security page and verify that the group is mapped to the role.
18. Return to the Application Server Home page.
19. Restart the OC4J instance for the changes to take effect.
Step 5
Configure OC4J instance for schema validations (optional)
Validating XML request and response messages for each Web service invocation degrades
system performance. For this reason, schema validation is turned off by default. To turn
schema validation on, you must set system property BANNERWS_SCHEMA_VALIDATION with
18
Banner General
Web Services Handbook
Adapter Deployment and Configuration
October 2009
a value of true for the OC4J instance where the adapter is installed. Use the following
steps to turn schema validation on.
1. Select the Administration tab from the Home page of the OC4J instance where the
adapter is deployed. The console displays administration options:
2. Select Server Properties from the Instance Properties section. The console displays
the Server Properties page.
3. Scroll to the Command Line Options section.The corresponding value for Java
Options might look similar to this:
-Xrs -server -Djava.security.policy=$ORACLE_HOME/j2ee/home/
config/java2.policy -Djava.awt.headless=true
4. Add the following system property at the end of Java Options:
-DBANNERWS_SCHEMA_VALIDATION=true
5. Click Apply. The console displays a confirmation message.
6. Click Yes to restart the server.
Step 6
Configure adapter logging
The Banner Payment Transaction Service Adapter uses Apache’s log4j to log the activities
performed by the application at runtime. Log4j uses a properties file to establish specific
runtime options. The following options should be reviewed and modified as appropriate:
• Location of the log files - The default location is %IAS_HOME%/j2ee/home/log.
This location should be changed to the OC4J instance where the Banner Payment
Transaction Service Adapter ear file is deployed.
• Logging level - The default level is INFO, resulting in limited information (INFO,
WARNING, and ERROR level statements) being stored in log files. To provide
detailed logging, you should modify the log4j configurations.
October 2009
Banner General
Web Services Handbook
Adapter Deployment and Configuration
19
Use the following steps to modify the logging options:
1. Navigate to %IAS_HOME%/j2ee/<OC4J instance>/applications/<Web services
adapter name>/pci_web/WEB-INF/classes.
2. Edit log4j.properties as follows:
Property:
Original value:
New value:
Property:
Original value:
New value:
log4j.appender.out.File
log/pci_ws.log
../<OC4J instance>/log/pci_ws.log
log4j.category.com.sungardsct
INFO
DEBUG
You should change the logging level to DEBUG for intial operation only. Otherwise,
the log file gets too big.
3. Restart the OC4J instance for the changes to take effect.
Step 7
Update WSDL endpoint URL
SOAP-based Web services are described via a WSDL (Web Services Definition
Language) document. WSDL is an XML format for describing network services as
endpoints. A WSDL document contains information about the messages that can be
exchanged with the Web service, the network protocol supported, and the location of the
service expressed as a URL.
The WSDL for the Banner Payment Transaction Service Adapter
(pci_acct_trans_one.wsdl) is provided in the General\java subdirectory. This file can
be used to generate client-side code for accessing the Web service. It can also be used by
third-party testing tools, such as soapUI (www.soapui.org), to generate XML-based test
cases and test suites for testing the Web service.
The WSDL document must be updated to reflect the actual location of the service, as
determined during installation.
Use the following steps to configure the WSDL document so it references the proper
endpoint URL.
1. Locate the pci_acct_trans_one.wsdl file provided in the General\java
subdirectory.
2. Open the file with a text editor or XML editor.
3. Locate the <service> tag in the WSDL document. The soap:address location
attribute under this tag contains the following tokenized dummy URL string:
20
Banner General
Web Services Handbook
Adapter Deployment and Configuration
October 2009
http://@@@hostname@@@:@@@port@@@/pci/v1_0
4. Modify the dummy URL to reflect the correct host name and port for your
installation. If you changed the default URL string (/pci) during installation (page
11), make the corresponding changes here.
Example
Updating the dummy URL to reflect a deployment to a server named OAS_Test that
listens on port 443 would have the following result:
http://oas_test.somewhere.edu:443/pci/v1_0
If the default URL string was changed from /pci to /pci/bws_test, the URL would
also need to be updated:
http://oas_test.somewhere.edu:443/pci/bws_test/v1_0
With these modifications in place, testing and development tools can use the WSDL
document to generate code for accessing the specific URL.
October 2009
Banner General
Web Services Handbook
Adapter Deployment and Configuration
21
22
Banner General
Web Services Handbook
Adapter Deployment and Configuration
October 2009
3
PaymentTransaction
Web Service
Payment transactions entered in Banner Self-Service applications are automatically
redirected to an external payment vendor for processing. The PaymentTransaction Web
service allows the external payment vendor to post authorized payments to the originating
Banner Self-Service application and report the results of failed payment authorizations.
Intended usage
The PaymentTransaction Web service supports integration between Banner and external
payment vendors. The following graphic provides an overview of the integration.
Payment transactions are processed as follows:
1. A Banner Self-Service user wants to make a payment such as pay a transcript fee or
donate to the institution. The user enters the payment amount in Banner Self-Service
and clicks the payment button or link.
2. The Banner Self-Service application redirects the browser to an external payment
vendor, passing common parameters.
3. The user enters payment information in the payment vendor’s application.
4. The payment vendor tries to validate the payment.
October 2009
Banner General
Web Services Handbook
PaymentTransaction Web Service
23
5. One of the following occurs:
• If the payment authorization is successful, the payment vendor calls
AddAccountTransaction using the transaction data and authorization details. The
Web service responds with a ConfirmAddAccountTransaction message indicating
success or failure in updating the payment transaction.
• If the payment authorization is unsuccessful, the payment vendor calls
ReportTransactionError. The Web service responds with a
ConfirmReportTransactionError message that indicates success or failure in
updating the payment transaction.
6. Based on the response from the Web service, the payment vendor redirects the
browser to a success or failure URL provided by the Banner Self-Service application.
Operations
The PaymentTransaction Web service includes two operations that update payment
transactions that were initially created in Banner Self-Service. The payment vendor calls
one of these operations depending on whether the payment transaction was authorized:
• AddAccountTransaction is called if the payment transaction was authorized.
• ReportTransactionError is called if the payment transaction was not authorized.
AddAccountTransaction operation
The AddAccountTransaction operation allows payment vendors to update Banner with the
results of a successful payment authorization. This operation uses a request/reply
exchange of the following messages using the SOAP protocol over HTTP:
• AddAccountTransation
• ConfirmAddAccountTransaction
AddAccountTransaction
A payment vendor uses the AddAccountTransaction message to request the update of a
payment transaction initially created in Banner Self-Service. The following diagram
shows the structure of the AddAccountTransaction message schema:
24
Banner General
Web Services Handbook
PaymentTransaction Web Service
October 2009
ConfirmAddAccountTransaction
ConfirmAddAccountTransaction is the response message of the operation. The response
can be a success or failure:
• If the TransactionId provided in the request is found and the TransactionAmount
provided in the request matches the original transaction amount, the application
update process is called. If the update is successful, then the operation returns a
TransactionStatus element with the value Success.
• If the TransactionId is not found or if the TransactionAmount is different than the
original transaction amount, the operation returns a TransactionStatus element with
the value Failure. In addition, a StatusDescription element contains a textual
description of the error.
The following diagram shows the structure of the ConfirmAddAccountTransaction
message schema.
SOAP fault messages
If the Banner Payment Transaction Service Adapter has trouble processing an inbound
request, a SOAP fault is raised. Situations that might cause a SOAP fault message include
the following:
• The inbound request does not conform to the XML schema definition.
October 2009
Banner General
Web Services Handbook
PaymentTransaction Web Service
25
• A network, database, or other technical issue occurs.
ReportTransactionError operation
The ReportTransactionError operation allows external payment vendors to provide Banner
with the results of a failed payment authorization. The type of failure depends on the
payment vendor. In some cases a failure can occur if the card number or expiration date is
invalid. In most cases, however, this situation results in a transaction cancellation instead
of an error. The ReportTransactionError operation uses a request/reply exchange of the
following messages using the SOAP protocol over HTTP:
• ReportTransactionError
• ConfirmReportTransactionError
ReportTransactionError
A payment vendor uses the ReportTransactionError message to report the failed
authorization of a payment and to update the account transaction initially created in
Banner Self-Service. The following diagram shows the structure of the
ReportTransactionError message schema.
ConfirmReportTransactionError
When an error is reported, the operation returns the ConfirmReportTransactionError
message. The message indicates one of the following, depending on whether the
TransactionId in the request is found:
• If the TransactionId is found, the operation returns a Status element with the value
Acknowledged.
• If the TransactionId is not found, the operation returns a Status element with the
value Error. In addition, a StatusDescription element contains a textual description
of the error.
The following diagram shows the structure of the ConfirmReportTransactionError
message schema.
26
Banner General
Web Services Handbook
PaymentTransaction Web Service
October 2009
SOAP fault messages
If the Banner Payment Transaction Service Adapter has trouble processing an inbound
request, a SOAP fault is raised. Situations that might cause a SOAP fault message include
the following:
• The inbound request does not conform to the XML schema definition.
• A network, database, or other technical issue occurs.
Message mapping to Banner
The following tables provide a mapping between the message elements/attributes and
Banner columns. The left vertical lines represent the nesting of the attributes inside the
elements. Elements can nest inside other elements as well.
AddAccountTransaction
Element/Attribute
Database Mapping
AddAccountTransaction
AccountTransaction
TransactionId
Validated against
GORCCAU_PAY_TRANS_ID
TransactionAmount
Validated against GORCCAU_AMOUNT
TransactionDate
CreditCardAuthorizationDetails
CardType
GORCCAU_DETAIL
AuthorizationNumber
GORCCAU_VENDOR_AUTH_CODE
MerchantID
GORCCAU_MERCHANT_ID
VendorReferenceId
October 2009
GORCCAU_VENDOR_REFER_NO
Banner General
Web Services Handbook
PaymentTransaction Web Service
27
ConfirmAddAccountTransaction
Element/Attribute
Database Mapping
ConfirmAddAccountTransaction
TransactionStatus
Generated/derived
StatusDescription
GORCCAU_VENDOR_ERROR_MSG
ReportTransactionError
Element/Attribute
Database Mapping
ReportTransactionError
TransactionId
Validated against
GORCCAU_PAY_TRANS_ID
FailureReason
GORCCAU_VENDOR_ ERROR_MSG
ConfirmReportTransactionError
Element/Attribute
Database Mapping
ConfirmReportTransactionError
Status
StatusDescription
Generated/derived
Generated/derived
Setup requirements
Payment cards must be set up in Banner so they cross-reference the codes used by Banner
and the payment vendor. You also need to set up the various combinations of process code,
payment card code, system code, and merchant ID that your institution uses. These
combinations are used to assign a detail code and cashier ID to payment transactions.
28
Banner General
Web Services Handbook
PaymentTransaction Web Service
October 2009
Payment cards
Various payment cards can be used within Banner Self-Service. Examples include
American Express, Visa, and MasterCard. Payment card codes stored within Banner must
be cross-referenced to the payment card codes sent by your payment vendor. Use the
following steps to identify the payment cards that can be used for payments at your
institution.
1. Access the Credit Card Validation Form (GTVCCRDD).
2. Enter the following information for each payment card that can be used at your
institution:
Code
External Merchant ID
Description
Payment card code that is stored in Banner
Payment card code sent by the payment vendor
Description of the payment card
3. Save.
Payment combinations
The Credit Card Merchant ID Form (GOAMERC) is used to identify each combination of
process code, payment card code, system code, and merchant ID (third party transaction
ID) that your institution uses. For each combination, you must define the associated
payment detail code and cashier ID.
When your payment vendor returns a payment transaction, the GOAMERC record that
matches on process code, payment card code, system code, and merchant ID is used to
determine which detail code and cashier ID are used to process the payment transaction in
Banner.
Use the following steps to set up records on GOAMERC.
1. Access the Credit Card Merchant ID Form (GOAMERC).
Note
The key block is used to enter search criteria for displaying information in
the next block. Any or all fields in the key block can be left blank.
„
2. Go to the Credit Card Merchant ID block.
3. For every combination of process code, payment card code, system code, and
merchant ID, insert a new record with the following information:
October 2009
Banner General
Web Services Handbook
PaymentTransaction Web Service
29
Process
Banner process that uses payment processing (for example,
WEBCCREGFEES).
Credit Card
Payment card that is used with payment processing (for
example, VISA).
System
Banner system (for example, S for Banner Student).
Third Party
Transaction
Merchant ID provided by the payment vendor to identify
the profile that is used for payment transactions.
Detail
Code used to identify payment detail. This code depends on
the process (for example, a detail code in Banner Student
Self-Service or a gift type in Banner Advancement SelfService).
Voice Response
Message
Message number that is spoken to a Banner Voice
Response user to identify the payment card type. Optional.
Active
Check box that indicates if the record is active.
Cashier ID
User ID for the cashiering session when payments for the
process, system, payment card type, and merchant ID are
inserted into Banner.
4. Save.
30
Banner General
Web Services Handbook
PaymentTransaction Web Service
October 2009