Banner
Payment Processor Connection
Handbook
Banner®, Colleague®, PowerCAMPUS®, Luminis® and Datatel® are trademarks of Ellucian or its affiliates and are registered in the U.S. and other countries. Ellucian, Advance, DegreeWorks, fsaATLAS, Course Signals, SmartCall, Recruiter, MOX, ILP, and WCMS are trademarks of Ellucian or its affiliates. Other names may be trademarks of their respective owners.
©2010-2011 Ellucian. All rights reserved. The unauthorized possession, use, reproduction, distribution, display or disclosure of this material or the information contained herein is prohibited.
Contains confidential and proprietary information of Ellucian and its subsidiaries. Use of these materials is limited to Ellucian licensees, and is subject to the terms and conditions of one or more written license agreements between Ellucian and the licensee in question.
In preparing and providing this publication, Ellucian is not rendering legal, accounting, or other similar professional services. Ellucian makes no claims that an institution's use of this publication or the software for which it is provided will guarantee 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: Ellucian 4375 Fair Lakes Court Fairfax, Virginia 22033 United States of America
Revision History
Publication Date Summary
Contents
Banner
Payment Processor Connection Handbook
Chapter 1
Overview
. . . 1-1 PCI compliance . . . 1-1 Supported vendors . . . 1-2 Processing flow . . . 1-2 Data exchange . . . 1-4 Banner dependencies . . . 1-5Contents of this handbook . . . 1-5
Chapter 2
PaymentTransaction Web Service
. . . 2-1What is a Web service? . . . 2-1
What is the Banner Payment Transaction Service Adapter? . . . 2-1
Requirements . . . 2-2 Oracle application server and Java. . . 2-2 Oracle database. . . 2-3 Banner Translation Service . . . 2-3
Installation on Oracle Application Server 10.1.3.4/5 . . . 2-3 Step 1 Create an OC4J instance . . . 2-4 Step 2 Install the adapter . . . 2-7 Step 3 Define the adapter data source. . . 2-10 Step 4 Define the Translation Service data source . . . 2-15 Step 5 Install the adapter . . . 2-17 Step 6 Configure the security role and user . . . 2-21 Step 7 Enable schema validation (optional) . . . 2-26
Step 8 Configure logging. . . 2-27 Step 9 Verify the deployment . . . 2-28
Installation on Oracle WebLogic Server 11g . . . 2-29 Recommended configuration . . . 2-30 Installation steps . . . 2-30 Step 1 Configure logging (optional). . . 2-30 Step 2 Define the adapter data source. . . 2-32 Step 3 Define the Banner Translation Service data source . . . 2-39 Step 4 Install the adapter . . . 2-41 Step 5 Configure the security group and user. . . 2-48 Step 6 Enable schema validation (optional) . . . 2-53 Step 7 Verify the deployment . . . 2-54
Web service operations . . . 2-56 AddAccountTransaction operation . . . 2-57 ReportTransactionError operation . . . 2-58
SOAP fault messages. . . 2-59
Message mapping to Banner . . . 2-59 AddAccountTransaction . . . 2-59 ConfirmAddAccountTransaction. . . 2-60 ReportTransactionError . . . 2-60 ConfirmReportTransactionError. . . 2-60
Setup requirements. . . 2-61 Payment card types. . . 2-61 Accounting information. . . 2-61
Chapter 3
Common Implementation
. . . 3-1Implementation steps. . . 3-1 Step 1 Define processes that use payment card processing . . . 3-2 Step 2 Define source code. . . 3-3 Step 3 Define printer code. . . 3-3 Step 4 Build address hierarchy . . . 3-3 Step 5 Define default merchant IDs. . . 3-4
Step 7 Build multiple merchant ID hierarchy. . . 3-6 Step 8 Define payment card types . . . 3-9 Step 9 Define accounting information . . . 3-10 Step 10 Define Banner Web Tailor parameters . . . 3-12 Step 11 Define payment transaction descriptions. . . 3-12 Step 12 Provide success and failure URLs to payment processing vendor . . . . 3-13
Implementation examples . . . 3-14
Objects used with payment card processing . . . 3-15 Vendor Payment Transaction Audit Form (GOICCAU). . . 3-15 Object Library (GOQOLIB). . . 3-17 Tables . . . 3-18 Packages . . . 3-18 API . . . 3-21
Chapter 4
Banner Student Implementation
. . . 4-1Form setup for admissions applications . . . 4-1 Application Fee Waiver Reason Validation Form (STVWAIV) . . . 4-1 Web Application Customized Lists Form (SAAWADP) . . . 4-2 Admissions Application Form (SAAADMS) . . . 4-3 Electronic Application Submitted Form (SAAETBL) . . . 4-5 Electronic Applicant Web Default Rules Form (SAAWADF) . . . 4-6
Form setup for enrollment verification requests . . . 4-7 Enrollment Verification Type Code Validation Form (STVEPRT) . . . 4-7 Web Self Service Options Validation Form (STVWSSO). . . 4-8 Web Payment Options Validation Form (STVWPYO) . . . 4-9 Enrollment Verification Request Rules Form (SFAEPRT) . . . 4-10
Form setup for registration and student accounts . . . 4-13
Form setup for transcript requests . . . 4-13 Transcript Type Code Validation Form (STVTPRT). . . 4-13 Web Self Service Options Validation Form (STVWSSO). . . 4-14 Web Payment Options Validation Form (STVWPYO) . . . 4-14
Transcript Type Rules Form (SHATPRT). . . 4-14 Web Transcript Request Rules Form (SHAWTRR). . . 4-16
Form setup for graduation applications . . . 4-17 Web Payment Options Validation Form (STVWPYO) . . . 4-18 Graduation Application Display Rule Code Validation Form (STVGADR) . . . 4-18 Self-Service Graduation Application Display Rules Form (SHAGADR) . . . 4-18
Chapter 5
Banner Student Self-Service Implementation
. . . 5-1Processing features. . . 5-1
Common implementation for Banner Student Self-Service . . . 5-3 Step 1 Verify common implementation. . . 5-3 Step 2 Define AR holds indicator . . . 5-3 Step 3 Define default term codes . . . 5-4
Implementation for admissions applications . . . 5-5 Step 1 Verify form setup . . . 5-5 Step 2 Customize procedure definitions in Banner Web Tailor . . . 5-5 Step 3 Customize information text in Banner Web Tailor . . . 5-7
Implementation for enrollment verification requests. . . 5-8 Step 1 Verify form setup . . . 5-8 Step 2 Customize procedure definition in Banner Web Tailor. . . 5-8
Implementation for registration and student accounts. . . 5-9 Step 1 Customize procedure definition in Banner Web Tailor. . . 5-9 Step 2 Establish link to payment card payments . . . 5-10
Implementation for transcript requests . . . 5-11 Step 1 Verify form setup . . . 5-11 Step 2 Customize procedure definitions in Banner Web Tailor . . . 5-11
Implementation for graduation applications . . . 5-12 Step 1 Verify form setup . . . 5-12 Step 2 Customize procedure definition in Banner Web Tailor. . . 5-13 Step 3 Customize information text in Banner Web Tailor . . . 5-14
Web pages . . . 5-14 Select a Waiver (bwskapmt.P_SelectWaiver) . . . 5-14 Process a Waiver (bwskapmt.P_ProcessWaiver). . . 5-14 Application Fee Payment (bwskalog.P_ProcIndex). . . 5-14 Enrollment Verification Request Summary (bwskrqst.P_Disp_Confirm) . . . 5-15 Credit Card Payment (bwckcpmt.P_CCPaymentTermSelected) . . . 5-15 Transcript Request Summary (bwskwtrr.P_Disp_Confirm) . . . 5-15 Graduation Application Summary (bwskgrad.P_Disp_Payment) . . . 5-15
Chapter 6
Banner Flexible Registration Implementation
. . . 6-1Processing features. . . 6-1
Implementation . . . 6-2 Step 1 Verify common implementation. . . 6-2 Step 2 Verify AR holds indicator . . . 6-2 Step 3 Verify default term code . . . 6-2 Step 4 Verify process code . . . 6-2 Step 5 Enable payment card processing. . . 6-2 Step 6 Configure success and failure URLs. . . 6-3
Chapter 7
Banner Advancement Implementation
. . . 7-1Campaign Detail Form (AFACAMP) . . . 7-1
Designations Form (ADADESG) . . . 7-1
Advancement Prospect Information Form (AMAINFO). . . 7-2
Fiscal Year Validation Form (ATVFISC) . . . 7-2
Chapter 8
Banner Advancement Self-Service Implementation
. . . 8-1Processing features. . . 8-1
Implementation for Banner Advancement Self-Service . . . 8-1 Step 1 Verify common implementation. . . 8-2 Step 2 Verify form setup . . . 8-2 Step 3 Indicate display of gift number on receipts . . . 8-2
Step 4 Indicate display of donor ID on receipts . . . 8-2 Step 5 Customize procedure definitions in Banner Web Tailor . . . 8-3 Step 6 Customize information text in Banner Web Tailor . . . 8-6 Step 7 Customize rules for gifts made with Banner Advancement Self-Service. . 8-7
Web pages . . . 8-9 Make a Donation (bwakgift.P_Make_A_Donation and bwakgift.
P_Pledge_Payment) . . . 8-9 Credit Card Payment (bwakgift.P_Make_A_Donation and bwakgift.
P_Pledge_Payment) . . . 8-9 Online Receipt (bwakgift.P_Donation_Receipt). . . 8-10 Make a Donation (bwakngft.P_Make_A_Donation). . . 8-10 Online Receipt (bwakngft.P_Donation_Receipt) . . . 8-10
Troubleshooting
. . . T-1Payment not applied to account . . . T-1
1 Overview
The Payment Processor Connection connects Banner® applications with third-party vendors that process payment card transactions. Payment amounts are entered or acknowledged in Banner. The Payment Processor Connection uses URL redirects and Web services to connect Banner to vendor applications where payment card information is entered, processed, and confirmed.
Payment card processing can be implemented for the following types of payments made in Banner:
PCI compliance
The Payment Card Industry (PCI) Security Standards Council is a forum that develops, enhances, stores, disseminates, and implements security standards for payment card transactions on a global basis. PCI security standards affect the storage, transmission, and processing of cardholder data as part of the authorization or settlement of payment card transactions. PCI standards apply to organizations that store, transmit, and process cardholder data. PCI standards also apply to software vendors who develop payment applications that store, transmit, and process cardholder data.
Ellucian applications do not store, transmit, and process cardholder data. Rather, cardholder data is stored, transmitted, and processed by a PCI-compliant application or service that is provided by your payment processing vendor. The Payment Processor Connection connects your Ellucian applications with this payment processing vendor.
Application Payment
Banner Student Self-Service Admissions applications Enrollment verification requests Registration and student accounts Transcript requests
Graduation applications Banner Advancement Self-Service Gifts and pledge payments
Supported vendors
Ellucian supports the following third-party vendors for payment card processing:
• CASHnet • Nelnet
• Official Payments • TouchNet
Processing flow
Certain tasks performed in Banner require a payment (for example, tuition payment or a donation). If the user chooses to pay with a payment card, the following processing occurs:
Detailed processing steps are as follows:
1. The user enters or acknowledges the payment amount in a Banner application. (If the amount is pre-determined, the amount does not have to be entered.) No personally identifiable information is entered in Banner.
2. The user clicks the button or link in the Banner application to submit the transaction and create a Banner transaction record. Once the transaction is submitted, the amount cannot be changed.
3. The Banner application redirects the browser to the payment processing vendor’s Web site (identified by the Banner Web Tailor PAYVEND_URL parameter).
4. The user accesses the payment processing vendor’s Web site. The access procedure depends on the payment processing vendor.
5. The user enters payment card information and follows the instructions on the payment processing vendor’s Web site.
6. The payment processing vendor processes the payment. The subsequent processing depends on whether the payment processing succeeds or fails.
7. If the payment processing vendor successfully processes the payment, the following processing occurs:
7.1. The payment processing vendor invokes a Web service, which is exposed by Banner, to update the Banner transaction record with the results of the payment transaction. No personally identifiable information is transmitted to or stored in Banner
7.2. The Web service responds with a message to the payment processing vendor stating whether the Banner update was successful or not.
7.3. The payment processing vendor might display a confirmation page or send a confirmation e-mail to the payee. If a confirmation page is displayed, the user follows instructions on the confirmation page to return to Banner.
7.4. The payment processing vendor redirects the browser to Banner.
7.5. Banner displays the success page.
8. If the payment processing vendor does not successfully process the payment, the following processing occurs:
8.1. The payment processing vendor invokes a Web service, which is exposed by Banner, to update the Banner transaction record with the reason why the payment transaction failed.
8.2. The Web service responds with a message to the payment processing vendor providing an acknowledgement of the status update.
8.3. The payment processing vendor might display a failure confirmation page. Error messages are defined by the payment processing vendor. If a failure confirmation page is displayed, the user follows instructions on the failure confirmation page to resubmit the payment information (use a different payment card), cancel the transaction, or log out of the site.
8.4. The payment processing vendor redirects the browser to Banner.
8.5. Banner displays the failure page.
Data exchange
When a payment transaction is initiated, a new record is created in the Credit Card Audit Table (GORCCAU) to track the transaction. The following information is stored in the new record and is also transmitted to the payment processing vendor:
• Transaction ID • Transaction amount
• Transaction description (defined by Banner Web Tailor information text) • Merchant ID (used to determine available payment methods)
After the payment processing vendor processes the payment transaction, information is returned to Banner and the associated GORCCAU record is updated.
For transactions that process successfully, the following information is returned:
• Transaction ID that originated in Banner • Transaction amount processed by the vendor • Transaction date (optional)
• Type of payment card (for example, Visa) • Payment card authorization code
• Merchant ID that originated in Banner • Vendor reference number
For transactions that fail, the following information is returned:
• Transaction ID that originated in Banner • Reason for failure
Banner dependencies
The Payment Processor Connection requires the following products:
*Patch p1-i6z6yh_gen8040104 contains the newest version of the adapter that exposes Banner functions to payment processing vendors. If you install both patches, you should install the ear file that is delivered in p1-i6z6yh_gen8040104, rather than the ear file that is delivered in p1-639eqc_gen80200.
Contents of this handbook
This handbook provides the steps that systems administrators use to install the Banner Payment Transaction Service Adapter. This adapter exposes key Banner functions to payment processing vendors.
This handbook also provides the steps used to implement payment card processing in Banner. This includes common implementation steps, plus implementation steps specific to Banner Student, Banner Student Self-Service, Banner Flexible Registration, Banner Advancement, and Banner Advancement Self-Service.
Product Minimum Version
Banner General Deployment on Oracle Application Server 10.1.3.4/5: General 8.0 with
patch p1-639eqc_gen80200 (required)* and patch p1-i6z6yh_gen8040104 (recommended)* Deployment on Oracle WebLogic Server 11g: General 8.0 with
patch p1-639eqc_gen80200 (required)* and patch p1-i6z6yh_gen8040104 (required)* Banner Web General 8.0 with patch p1-639es5_bwg80200 Banner Web Tailor 8.0 with patch p1-7549uz_twb80201
2 PaymentTransaction
Web Service
When a payment transaction is entered in a Banner® application, the transaction is automatically redirected to an external payment processing vendor for processing. When processing is complete, the payment processing vendor invokes the PaymentTransaction Web service to post the payment transaction, if successful, to the originating Banner application, or to report the result, if failed.
This chapter provides information about the PaymentTransaction Web service. This includes instructions for installing the adapter that exposes the Web service, a description of each operation in the Web service, the mapping of message elements/attributes to Banner columns, and data setup requirements.
What is a Web service?
A Web service exposes an application’s processing logic to support a service-oriented architecture and to facilitate 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 are based on open, Internet-based standards. This makes them relevant to application integration within an organization and with external 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.
What is the Banner Payment Transaction
Service Adapter?
The Banner Payment Transaction Service Adapter is a Java-based application that exposes the PaymentTransaction Web service. This exposure makes certain Banner functions available to payment processing vendors using the SOAP protocol over HTTP/HTTPS. Payment processing vendors interact with the Web service, which in turn is supported by Banner APIs. This layered approach provides an insulating buffer between payment processing vendors and Banner. Payment processing vendors do not interact with Banner directly, but rather exchange XML messages with the exposed Web service.
The Banner Payment Transaction Service Adapter supports the synchronous, request/reply message exchange pattern as follows:
1. The payment processing vendor requests a service of Banner by sending an XML message to the Web service endpoint (URL) that is exposed by the adapter. The message contains the information required for Banner to service the request. The URL that is exposed by the adapter follows this pattern:
<http or https>://<host>:<port>/pci/v1_0
See “Web service operations” on page 2-56 for more information about the URL.
2. The Banner Payment Transaction Service Adapter invokes the appropriate Banner API.
3. The Banner API performs the necessary Banner processing logic.
4. One of the following occurs:
4.1. If the action is completed successfully, the API provides a response message, which the adapter forwards to the payment processing vendor.
4.2. If the action is not completed successfully, the adapter sends an error message (called a SOAP fault) to the payment processing vendor.
The adapter is packaged as a J2EE compatible enterprise archive file named
pci_services.ear (Oracle Application Server) or pci_services_weblogic.ear
(Oracle Weblogic Server). The adapter is available in the Banner General Java subdirectory.
Requirements
The Banner Payment Transaction Service Adapter has the following requirements.
Oracle application server and Java
The Banner Payment Transaction Service Adapter is certified on Oracle Application Server (OAS) 10.1.3.4/5 and Oracle WebLogic Server 11g with Java 1.6.
OAS 10.1.3.4/5 is delivered with Java 1.5. The following Oracle document provides instructions for changing to Java 1.6. If you contract with Ellucian for Oracle support, you can access the FAQ on the Customer Support Center. Otherwise, you can use your Oracle support account to access the document.
Oracle database
The required Oracle database depends on the application server that you are using:
Banner Translation Service
The Banner Payment Transaction Service Adapter does not require the Banner Translation Service. The adapter, however, does require the definition of a data source that refers to the Banner Translation Service. Installation instructions in this chapter include a step for creating the data source and its associated connection pool. These components can reference the transsvc schema if Banner Web Services is installed, or they can use the
integmgr schema, as documented in this chapter.
Installation on Oracle Application Server
10.1.3.4/5
The Banner Payment Transaction Service Adapter is packaged as a J2EE compatible enterprise archive file (pci_services.ear), which is available in the Banner General Java subdirectory.
Use the following steps to install the adapter on OAS 10.1.3.4/5:
• Step 1, “Create an OC4J instance”
• Step 2, “Install the adapter”
• Step 3, “Define the adapter data source”
• Step 4, “Define the Translation Service data source”
• Step 6, “Configure the security role and user”
• Step 7, “Enable schema validation (optional)”
Document Title: How to change the Java version used to run a specific OC4J instance
Ellucian FAQ: 1-AXZ803 Oracle Doc ID: 351476.1
Application Server Required Database
Oracle Application Server 10.1.3.4/5 Oracle Database 10gR2 or 11g Oracle WebLogic Server 11g Oracle Database 11g
• Step 8, “Configure logging”
• Step 9, “Verify the deployment”
The adapter can be installed on an existing Oracle Application Server. A separate OC4J instance should be dedicated for the adapter so that the PaymentTransaction Web service environment can be independently managed.
Step 1 Create an OC4J instance
The adapter can be installed on an existing application server, but a separate OC4J instance should be dedicated for the adapter. This allows you to independently manage the PaymentTransaction Web service environment. Use the following steps to create a new OC4J instance for the Banner Payment Transaction Service Adapter.
1. Connect to the Oracle Enterprise Manager:
http://<host>:<port>/em
Note
The adapter uses the server’s HTTP or HTTPS port. These ports are
The console is displayed.
2. Click the name of the application server that will contain the new instance. (The value of the Type field should be Application Server.) The Application Server page is displayed.
3. Click Create OC4J Instance. The Create OC4J Instance page is displayed.
4. Enter the following information to create the new instance:
5. Click Create. The instance is created and started. A confirmation message is displayed.
6. Click OK. The System Components list is redisplayed with the new instance.
OC4J instance name Enter a meaningful name for the new instance.
Start this OC4J instance after creation
Step 2 Install the adapter
Use the following steps to deploy the adapter to the Oracle Application Server.
1. In the System Components list, click the name of the OC4J instance that you created in Step 1, “Create an OC4J instance”. The Home page for the selected instance is displayed.
3. Click Deploy. The Deploy: Select Archive page is displayed.
4. Select the file to be uploaded:
4.1. In the Archive section, select Archive is present on local host. Upload the
archive to the server where Application Server Control is running.
4.1. In the Archive Location field, click Browse and navigate to the
pci_services.ear file.
4.2. Select the file and click Open.
5. If you are installing on OAS 10.1.3.5, go to step 6. A deployment plan is not needed.
-or-If you are installing on OAS 10.1.3.4, select the deployment plan for the adapter:
5.1. In the Deployment Plan section, select Deployment plan is present on local
host. Upload the deployment plan to the server where Application Server Control is running.
5.2. In the Plan Location field, click Browse and navigate to the
deployment_plans folder.
6. Click Next on the Deploy: Select Archive page. The files are uploaded and the Deploy: Application Attributes page is displayed.
7. Enter a name for the application (for example, Payment_Transaction_Service) in the
Application Name field.
Warning
If the adapter is being deployed in multiple OC4J instances on the same server, the application name must be unique for each deployment.
8. If the adapter is being deployed in one instance only, accept the default context root and go to step 9.
-or-If the adapter is being deployed in multiple OC4J instances on the same server, add descriptive text to the default context root in the Context Root field (for example, /pci/test or /pci/prod). Adding descriptive text to the default string, rather than changing the entire default string, is preferable. Use this new context root in any subsequent steps that refer to the default URL.
Warning
If the adapter is being deployed in multiple OC4J instances on the same server, the context root must be unique for each deployment.
9. Click Next. The Deploy: Deployment Settings page is displayed.
10. Click Deploy to accept the values and install the adapter. A deployment confirmation page is displayed.
11. Click Return to continue. The Applications tab is displayed with the deployed application.
Step 3 Define the adapter data source
A data source provides the connection properties to the Banner database. By default, the adapter needs a data source with lookup name jdbc/bannerws.
There are two ways to define a data source:
• At the OC4J instance level - This method promotes resource sharing, allowing
multiple applications in the instance to use the same connection pool to connect to the database.
• At the application level - This method permits each application in the instance to
Use the following steps to define the connection pool and data source.
2. Select JDBC Resources in the Services section. The JDBC Resources page is displayed.
3. Click Create in the Connection Pools section. The Create Connection Pool - Application page is displayed.
4. Select the application and connection pool type for the new pool:
Application If you want to define the connection pool at the OC4J level, select default. All applications in the instance will use this connection pool.
If you want to define the connection pool at the application level, select the adapter application.
5. Click Continue. The Create Connection Pool page is displayed.
6. Enter the following information to set up the connection pool for the integmgr
schema:
Name bannerWS_pool
(This is an example. Enter the name of your choice.)
Connection Factory Class oracle.jdbc.pool.OracleDataSource
JDBC URL jdbc:oracle:thin:@host:port:SID where host = database host
port = database listener port (usually 1521) SID = database instance
Username integmgr
Use Cleartext Password Select Use Cleartext Password and enter a password for the integmgr schema.
7. Click Test Connection. The Test Connection page is displayed.
8. Click Test to test the connection pool for the integmgr schema. The Create Connection Pool page is redisplayed with a success or failure message.
8.1. If the test succeeds, continue with the next step.
8.2. If the test fails, ensure that the connection URL and credentials are correct. Continue testing until the connection is successful.
9. Click Finish.
10. Click Create in the Data Sources section on the JDBC Resources page. The Create Data Source - Application & Type page is displayed.
11. Select the application and data source type for the data source:
Application If you want to define the data source at the OC4J level, select default. All applications in the instance will use this data source.
If you want to define the data source at the application level, select the adapter application.
12. Click Continue. The Create Data Source - Managed Data Source page is displayed.
13. Enter the following information to set up the bannerWS data source:
14. Click Finish.
Step 4 Define the Translation Service data source
By default, the adapter needs a data source with lookup name jdbc/transsvc. The PaymentTransaction Web service, however, does not request value translations. For this reason, the Translation Service data source and its associated connection pool can be defined to reference any database schema.
Use the following steps to define the connection pool and data source by copying the adapter connection pool and data source that you defined in step 3.
1. Select the Administration tab. A list of tasks is displayed.
2. Select JDBC Resources in the Services section. The JDBC Resources page is displayed.
3. Click Create in the Connection Pools section. The Create Connection Pool - Application page is displayed.
Name bannerWS
JNDI Location jdbc/bannerws
4. Select the application and connection pool type for the new pool:
5. Click Continue. The Create Connection Pool page is displayed.
6. Enter Transsvc_pool in the Name field.
7. Click Finish.
8. Click Create in the Data Sources section on the JDBC Resources page. The Create Data Source - Application & Type page is displayed.
9. Select the application and data source type for the data source:
10. Click Continue. The Create Data Source - Managed Data Source page is displayed.
Application If you want to define the connection pool at the OC4J level, select default. All applications in the instance will use this connection pool.
If you want to define the connection pool at the application level, select the name of the deployed adapter.
New Connection Pool from Existing Connection Pool
Select the button.
Existing Connection Pool Select “bannerWS_pool”.
Application If you want to define the data source at the OC4J level, select default. All applications in the instance will use this data source.
If you want to define the data source at the application level, select the name of the deployed adapter.
New Data Source from Existing Data Source
Select the button.
11. Enter the following information to set up the transsvc data source:
12. Click Finish.
Step 5 Install the adapter
Use the following steps to deploy the adapter to the Oracle Application Server.
1. Select the Applications tab. A list of deployed applications is displayed.
Name transsvc
JNDI Location jdbc/transsvc
2. Click Deploy. The Deploy: Select Archive page is displayed.
3. Select the file to be uploaded:
3.1. In the Archive section, select Archive is present on local host. Upload the
archive to the server where Application Server Control is running.
3.1. In the Archive Location field, click Browse and navigate to the
pci_services.ear file.
3.2. Select the file and click Open.
4. If you are installing on OAS 10.1.3.5, go to step 6. A deployment plan is not needed.
-or-If you are installing on OAS 10.1.3.4, select the deployment plan for the adapter:
4.1. In the Deployment Plan section, select Deployment plan is present on local
host. Upload the deployment plan to the server where Application Server Control is running.
4.2. In the Plan Location field, click Browse and navigate to the
deployment_plans folder.
5. Click Next on the Deploy: Select Archive page. The files are uploaded and the Deploy: Application Attributes page is displayed.
6. Enter a name for the application (for example, Payment_Transaction_Service) in the
Application Name field.
Warning
If the adapter is being deployed in multiple OC4J instances on the same server, the application name must be unique for each deployment.
7. If the adapter is being deployed in one instance only, accept the default context root and go to step 9.
-or-If the adapter is being deployed in multiple OC4J instances on the same server, add descriptive text to the default context root in the Context Root field (for example, /pci/test or /pci/prod). Adding descriptive text to the default string, rather than changing the entire default string, is preferable. Use this new context root in any subsequent steps that refer to the default URL.
Warning
If the adapter is being deployed in multiple OC4J instances on the same server, the context root must be unique for each deployment.
8. Click Next. The Deploy: Deployment Settings page is displayed.
9. Click Deploy to accept the values and install the adapter. A deployment confirmation page is displayed.
10. Click Return to continue. The Applications tab is displayed with the deployed application.
Step 6 Configure the security role and user
Use the following steps to add the bannerws role and an administrative user to the Banner Payment Transaction Service Adapter application. This role and user protect the defined endpoint.
2. Select Security Providers in the Security section. The Security Providers page is displayed.
3. In the Application Level Security section, click the Edit button for the adapter application. The Security Provider page is displayed.
5. Click the link under the Roles column. The Roles page is displayed.
6. Click Create. The Add Role page is displayed.
7. Enter bannerws in the Name field.
9. Return to the Security Provider page.
10. Click the link under the Users column. The Users page is displayed.
12. Enter the following information to create a user:
13. In the Assign Roles section, select the bannerws role in the Available Roles list and move it to the Selected Roles list.
14. Click OK. The Users page is redisplayed with the new user.
Name payment_vendor
(This is an example. Enter the name of your choice.)
Password Password for the user being created
Step 7 Enable schema validation (optional)
Validating XML request and response messages for each Web service invocation degrades system performance. For this reason, schema validation is disabled by default. To enable schema validation, you must set system property BANNERWS_SCHEMA_VALIDATION with a value of true for the OC4J instance where the adapter is installed. Use the following steps to enable schema validation.
2. Select Server Properties in the Properties section. The Server Properties page is displayed.
3. In the Command Line Options section, click Add Another Row.
4. Add the following system property:
-DBANNERWS_SCHEMA_VALIDATION=true
5. Click Apply. A confirmation message is displayed.
6. Click Yes to restart the server.
Step 8 Configure 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 is installed.
• Logging level. The default level is INFO, resulting in limited information (INFO,
WARNING, ERROR, and FATAL level statements) being stored in log files. To provide detailed logging for initial operations, you should change the logging level to DEBUG.
Note
You should change the logging level for initial operation only.
Use the following steps to modify the logging options as appropriate.
1. Navigate to <IAS_HOME>/j2ee/<OC4J instance>/applications/<Web services adapter name>/pci_web/WEB-INF/classes.
2. Edit log4j.properties as follows:
3. Restart the OC4J instance for the changes to take effect.
Step 9 Verify the deployment
Use the following steps to verify that the adapter is successfully deployed.
1. Use a Web browser to access the URL mapped in Step 3, “Define the adapter data source”:
<http or https>://<host>:<port>/<context root>/
This URL is used to access an information page, not the endpoint. The context root is
pci, unless the context root was changed when the adapter was installed.
2. Log in with the name and password configured in Step 6, “Configure the security role and user”. An information page for the adapter is displayed. This page shows the version of the adapter and provides a link to the Web service’s WSDL.
3. (Optional) If you need to determine the URL that is being used to listen for messages, click the link on the information page to display the associated WSDL. The
<soap:address location> attribute under the <service> tag at the bottom of the WSDL identifies the URL that you should always use to invoke the Web service. In some situations, you can access the home page via a browser, but payment transactions are not logged in the pci_ws.log or in the redirect log for the container where the adapter is installed. This may be due to a wrong port configuration. The Web service uses the HTTP or HTTPS port of the server. These ports are configurable, by institution, via the Oracle Enterprise Manager console and are identified on the Runtime Ports page:
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
Installation on Oracle WebLogic Server
11g
The Banner Payment Transaction Service Adapter is packaged as a J2EE compatible enterprise archive file (pci_services_weblogic.ear), which is available in the Banner General Java subdirectory.
Recommended configuration
The adapter must be installed in a Basic WebLogic Server Domain 10.3.4.0 or above. It must not be installed using any other Oracle WebLogic template, especially the Oracle WebLogic Classic Domain that supports Oracle Forms and Reports.
The recommended configuration is to establish a separate physical or virtual server for Ellucian middle-tier components. This server would run a separate installation of Oracle WebLogic Server, configured using the Basic Domain template (not the Classic Domain template) that is provided by Oracle.
The Oracle WebLogic Server instance should consist of the default Admin Server and at least one Managed Server for the deployment of the Banner Payment Transaction Service Adapter.
If a domain based on the Basic Domain template already exists for middle-tier applications, the adapter can be installed in a separate Managed Server in that domain. Refer to the Oracle WebLogic Server Documentation Library for details on creating a new domain and a new Managed Server.
Installation steps
Use the following steps to install the adapter on Oracle WebLogic Server 11g:
• Step 1, “Configure logging (optional)”
• Step 2, “Define the adapter data source”
• Step 3, “Define the Banner Translation Service data source”
• Step 4, “Install the adapter”
• Step 5, “Configure the security group and user”
• Step 6, “Enable schema validation (optional)”
• Step 7, “Verify the deployment”
The adapter can be installed on an existing WebLogic Basic domain. It cannot be installed on a Classic Domain that comes with the WLS_FORMS and WLS_REPORTS servers. A separate Managed Server should be dedicated for the adapter so that the
PaymentTransaction Web service environment can be independently managed.
Step 1 Configure logging (optional)
The Banner Payment Transaction Service Adapter uses Apache’s log4j to log the activities performed by the application at runtime. The log file is located at the following location:
where <domain_name> is the name of the domain where the Banner Payment Transaction Service Adapter will be installed. This location cannot be changed. A property in the log4j.properties file determines the logging level. The default logging level is INFO, which results in limited information (INFO, WARNING, ERROR, and FATAL level statements) being stored in log files. Use the following steps to modify the logging level if you want more detailed logging for initial operations.
Note
You should change the logging level for initial operation only.
1. Copy pci_services_weblogic.ear to a temporary location. This location is referred to as <EAR_HOME>.
2. Navigate to <EAR_HOME> and execute the following command.
jar xvf pci_services_weblogic.ear
The extract contains a Web archive named pci_web.war.
3. Create a folder under <EAR_HOME> and name it war_home.
4. Navigate to war_home and execute the following command.
jar xvf <EAR_HOME>/pci_web.war
5. Open war_home\WEB-INF\classes\log4j.properties.
6. Edit the log4j.category.com.sungardsct property as follows:
7. Save the change.
8. From war_home execute the following command to rebuild the Web archive file.
jar cvf <EAR_HOME>/pci_web.war META-INF/* WEB-INF/* ui/* index.jsp
9. From <EAR_HOME> execute the following command to rebuild the enterprise archive file.
jar cvf pci_services_weblogic.ear *.war META-INF/* legal/* APP-INF/*
The rebuilt ear file is used for installation. Original value: INFO
Step 2 Define the adapter data source
A data source provides the connection properties to the Banner database. By default, the adapter needs a data source with lookup name jdbc/bannerws. Use the following steps to define the data source.
1. Connect to the Oracle WebLogic Server Administration Console:
http://<host>:<port>/console
The Home Page is displayed.
3. In the Domain Structure pane, expand and click Services -> JDBC -> Data Sources.
4. Click New. The Create a New JDBC Data Source page is displayed.
5. Enter the following data source properties:
Name BannerWS
JNDI Name jdbc/bannerws
Database Type Oracle
Database Driver Appropriate database driver that is used to create database connections:
• If your database is RAC-based, select Oracle's Driver
(Thin) for RAC Service -Instance connections; Versions:10,11.
• Otherwise, select Oracle's Driver (Thin) for Instance
6. Click Next. The next page is displayed.
6.1. In some domains, the Transaction Options are displayed. Clear the Supports
Global Transactions check box and click Next to display the Connection
6.2. In some domains, the Transaction Options are skipped and the Connection Properties are displayed. Go directly to step 7.
7. Enter the following connection properties:
Database Name Name of the database to which you are connecting
Host Name IP address of the database server
Port Port on the database server that is used to connect to the database
Database User Name integmgr
Password Password for the integmgr user
8. Click Next. The next page is displayed with the properties that you entered.
9. Verify the property values.
10. Click Test Configuration. The page is redisplayed with a success or failure message.
10.1. If the test succeeds, continue with the next step.
10.2. If the test fails, ensure that the connection URL and credentials are correct. Continue testing until the connection is successful.
11. Click Finish. The Summary of JDBC Data Sources page is displayed with the new data source.
12. In the Change Center pane, click Activate Changes.
13. On the Summary of JDBC Data Sources page, click the name of the new data source. The Settings for BannerWS page is displayed.
14. Select the Targets tab.
15. In the Change Center pane, click Lock & Edit.
16. On the Settings for BannerWS page, select the server where the data source should be deployed.
17. Click Save.
19. In the Domain Structure pane, expand and click Services -> JDBC -> Data Sources.
The Summary of JDBC Data Sources page is displayed.
20. Verify that the new data source is associated with the server.
Step 3 Define the Banner Translation Service data source
By default, the adapter needs a data source with lookup name jdbc/transsvc. Use the following steps to define the data source.
1. In the Change Center pane, click Lock & Edit.
2. Ensure that the Summary of JDBC Data Sources page is displayed. (If it is not displayed, expand and click Services -> JDBC -> Data Sources in the Domain Structure pane.)
3. Click New on the Summary of JDBC Data Sources page. The Create a New JDBC Data Source page is displayed.
4. Enter the following data source properties:
5. Click Next. The next page is displayed.
5.1. In some domains, the Transaction Options are displayed. Clear the Supports
Global Transactions check box and click Next to display the Connection
Properties. Then go to step 6.
5.2. In some domains, the Transaction Options page is skipped and the Connection Properties are displayed. Go directly to step 6.
6. Enter the following connection properties:
7. Click Next. The next page is displayed with the properties that you entered.
8. Verify the property values.
Name transsvc
JNDI Name jdbc/transsvc
Database Type Oracle
Database Driver Appropriate database driver that is used to create database connections:
• If your database is RAC-based, select Oracle's Driver
(Thin) for RAC Service -Instance connections; Versions:10,11.
• Otherwise, select Oracle's Driver (Thin) for Instance
connections; Versions:9.0.1, 9.2.0,10,11.
Database Name Name of the database to which you are connecting
Host Name IP address of the database server
Port Port on the database server that is used to connect to the database
Database User Name integmgr
Password Password for the integmgr user
9. Click Test Configuration. The page is redisplayed with a success or failure message.
9.1. If the test succeeds, continue with the next step.
9.2. If the test fails, ensure that the connection URL and credentials are correct. Continue testing until the connection is successful.
10. Click Finish. The Summary of JDBC Data Sources page is displayed with the new data source.
11. In the Change Center pane, click Activate Changes.
12. On the Summary of JDBC Data Sources page, click the name of the new data source. The Settings for transsvc page is displayed.
13. Select the Targets tab.
14. In the Change Center pane, click Lock & Edit.
15. On the Settings for transsvc page, select the server where the data source should be deployed.
16. Click Save.
17. In the Change Center pane, click Activate Changes.
18. In the Domain Structure pane, expand and click Services -> JDBC -> Data Sources. The Summary of JDBC Data Sources page is displayed.
19. Verify that the new data source is associated with the server.
Step 4 Install the adapter
Use the following steps to install the adapter to the Oracle WebLogic Server.
1. In the Change Center pane, click Lock & Edit.
The Summary of Deployments page is displayed.
4. Click upload your file(s). The next installation page is displayed.
5. Select the file to be uploaded:
5.1. In the Deployment Archive field, click Browse and navigate to
pci_services_weblogic.ear.
5.1. Select the file and click Open.
Note
A deployment plan is not needed.
7. Select the pci_services_weblogic.ear file from the list.
8. Click Next. The next installation page is displayed.
9. Select Install this deployment as an application.
10. Click Next. The next installation page is displayed.
10.1. In some domains, the following page is displayed. Select the server where the application should be deployed and click Next to display the next installation page. Then go to step 11.
10.2. In some domains, the preceding page is skipped and the next installation page is displayed. Go directly to step 11.
11. Enter a name for the application (for example, Payment_Transaction_Service) in the
Name field.
12. Select Advanced: Use a custom model that you have configured on the realm’s
configuration page.
14. Click Next. The next installation page is displayed.
15. Select No, I will review the configuration later.
16. Click Finish to start the deployment. When deployment is completed, the Summary of Deployments page is redisplayed with the newly deployed adapter.
18. Start the newly deployed application as follows:
18.1. Select the newly deployed adapter.
18.2. Click Start -> Servicing all requests. The Start Application Assistant page is displayed.
Step 5 Configure the security group and user
Use the following steps to add the bannerwsGroup group and an administrative user to the adapter. This group and user protect the defined endpoint.
1. In the Domain Structure pane, click Security Realms.
The Summary of Security Realms page is displayed.
2. Click myrealm. The Settings for myrealm page is displayed.
4. Select the Groups sub-tab. A table of existing groups is displayed.
6. Enter the following information to create a group:
7. Click OK. The table of groups is redisplayed with the new group.
Name bannerwsGroup
Description Banner Web Services Administrative Group
8. Select the Users sub-tab. A table of existing users is displayed.
10. Enter the following information to create a user:
11. Click OK. The table of users is redisplayed with the new user.
12. Click the name of the user that you just created. The Settings page for the user is displayed.
Name payment_vendor
(This is an example. Enter the name of your choice.)
Description Payment Processor Connection Administrator
Provider DefaultAuthenticator
Password Password for the user being created
13. Select the Groups tab.
14. In the Parent Groups section, select bannerwsGroup in the Available list and move it to the Chosen list.
15. Click Save.
Step 6 Enable schema validation (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 enable schema validation, you must set system property BANNERWS_SCHEMA_VALIDATION with a value of true for the Managed Server where the adapter is installed. Use the following steps to enable schema validation.
1. In the Domain Structure pane, click the name of the domain.
The Settings page is displayed.
2. Select the EJBs tab.
3. Add the following value in the Append Java Compiler Options field:
-DBANNERWS_SCHEMA_VALIDATION=true
4. Click Save.
5. Restart the server for the changes to take effect.
Step 7 Verify the deployment
Use the following steps to verify that the adapter is deployed successfully.
1. Use a Web browser to access the URL mapped in the following URL:
2. Log in with the name and password configured in Step 5, “Configure the security group and user”. An information page for the adapter is displayed. This page shows the version of the adapter and provides a link to the Web service’s WSDL.
3. Click the link on the information page to display the associated WSDL. The <soap:address location> attribute under the <service> tag at the bottom of the WSDL identifies the URL that you should always use to invoke the Web service.
Example:
<soap:address location="http(s)://<middle tier host>.school.edu:<port>/pci/v1_0"/>
In some situations, you can access the home page via a browser, but payment transactions are not logged in the pci_ws.log or in the redirect log for the container where the adapter is installed. This may be due to a wrong port configuration. The Web service uses the Listen Port for http protocols and the SSL Listen Port for https protocols. These ports are configurable, by institution, via the Oracle WebLogic Server Administration Console and are displayed on the General tab of the Settings for Managed Server page:
Web service operations
After a payment processing vendor processes a payment transaction, the vendor invokes the PaymentTransaction Web service via the URL that is exposed by the adapter. This Web service has two operations:
• If the payment transaction was authorized, the AddAccountTransaction operation
updates Banner with the results of the payment transaction.
• If the payment transaction failed, the ReportTransactionError operation provides
Banner with the reason why the payment transaction failed.
Both operations can be invoked by sending the appropriate request message to the URL that is exposed by the adapter. The URL is similar to the following:
<protocol>://<host>:<port>/<context root>/v1_0
Components of the URL are defined as follows:
Example
http://appserv101.greatvalleyu.com:7019/pci/prod/v1_0
Component Description Default Example
protocol Protocol used to invoke the Web service. Valid values are http and
https.
http http
host Server where the adapter is deployed
None appserv101.greatvalleyu.com
port Location where the adapter can receive messages. For example, the default port for http requests is 80.
None 7019
context root
Root path of URLs that the adapter handles. This can only be changed on OAS 10.1.3.x servers when the adapter is deployed.
AddAccountTransaction operation
The AddAccountTransaction operation allows payment processing 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 processing vendor uses the AddAccountTransaction message to request the update of a payment transaction initially created in Banner. The following diagram shows the structure of the AddAccountTransaction message schema:
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.
ReportTransactionError operation
The ReportTransactionError operation allows payment processing vendors to provide Banner with the results of a failed payment authorization. The type of failure depends on the payment processing 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 processing vendor uses the ReportTransactionError message to report the failed authorization of a payment and to update the account transaction initially created in Banner. 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.
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
ConfirmAddAccountTransaction
ReportTransactionError
ConfirmReportTransactionError
TransactionDate CreditCardAuthorizationDetails CardType GORCCAU_DETAIL AuthorizationNumber GORCCAU_VENDOR_AUTH_CODE MerchantID GORCCAU_MERCHANT_ID VendorReferenceId GORCCAU_VENDOR_REFER_NOElement/Attribute Database Mapping
ConfirmAddAccountTransaction
TransactionStatus Generated/derived
StatusDescription GORCCAU_VENDOR_ERROR_MSG
Element/Attribute Database Mapping
ReportTransactionError
TransactionId Validated against
GORCCAU_PAY_TRANS_ID
FailureReason GORCCAU_VENDOR_ ERROR_MSG
Element/Attribute Database Mapping
ConfirmReportTransactionError
Status Generated/derived
StatusDescription Generated/derived
Setup requirements
The PaymentTransaction Web service uses the following data that must be set up in Banner.
Payment card types
Various payment cards can be used within Banner (for example, American Express, Visa, and MasterCard). You must cross-reference the payment card codes stored in Banner to the payment card codes sent by your payment processing vendor. Refer to “Define payment card types” on page 3-9 for setup instructions.
Accounting information
You must 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. Refer to “Define accounting
3 Common
Implementation
This chapter gives instructions for setting up the following options that are common to payment card processing throughout Banner®:
• Processes that use payment card processing (for example, admissions applications,
registration fees, and gifts).
• Source code for writing account detail records. • Printer code for printing receipts.
• Address hierarchy that determines which address is stored for payments processed
for admissions application fees, transcript request fees, and enrollment verification fees.
• Merchant IDs that tell the payment processing vendor which payment profile to
use. Multiple merchant IDs can be set up to simplify the settlement process for institutions that must separately settle payment card transactions based on level, campus, or college.
• Types of payment cards that can be used for payments (for example, Visa and
MasterCard).
• Accounting information for each combination of process code, payment card code,
system code, and merchant ID.
• Parameters that support connection with the payment processing vendor. • Transaction descriptions that are sent to the payment processing vendor.
• Success and failure URLs used by the payment processing vendor to redirect the
browser after payments are processed.
Implementation steps
The following steps are used to set up the options that are common to payment card processing:
• Step 1, “Define processes that use payment card processing”
• Step 2, “Define source code”
• Step 3, “Define printer code”
