Both the funds capture and funds disbursement processes have setup tasks in common. The setup tasks described in this section are shared by both funds capture and funds disbursement and represent the first six setup tasks for Payments. Since both funds capture and funds disbursement use these same setup tasks, these shared setup steps must always be performed, whether you are using only the funds capture features of Payments, only the funds disbursement features, or both.
Oracle Payments recommends that you perform the following optional setup steps before setting up other E-Business Suite products or Oracle Payments:
Setting Up Payment Function Access
Setting Up Function Security
A payment function is an attribute on a document payable that indicates the purpose of payment. Examples of payment functions include supplier payments, employee expense payments, and loan payments.
In addition to identifying the purpose of documents payable, payment functions also serve to control the user's ability to process certain documents payable. That is, you can only take actions on payment process requests and payment instructions when all the documents payable and payments within have payment functions for which you have permission.
Payment functions are enabled or disabled in the Oracle Payments Funds Disbursement Process Home page menu. For details on how to add or remove functions from menus, see the Oracle E-Business Suite System Administrator's Guide.
Oracle Payments enables you to perform a variety of sensitive tasks. You can use function security to allow users to perform or disallow them from performing the following tasks:
update Oracle Payments setup
retry funds capture transactions
void funds disbursement payments
stop funds disbursement payments
view sensitive employee data
submit separate remittance advice
To use Oracle Payments, you must perform the setup steps indicated in the table below in other E-Business Suite products. For each application installed, consult the guides for that application to determine the sequence of setup steps.
| Setup Step | Step Type | Oracle Application and Applicable Guide |
|---|---|---|
| Set up internal bank accounts and related payment documents. | required | Oracle Cash Management, Bank and Account Administration: Define Bank Accounts, Oracle Cash Management User Guide. |
| Set up bill-to location and operating units. | required | Legal Entity Configurator, Oracle Financials Implementation Guide. See Legal Associations, Oracle Financials Implementation Guide, Creating Establishments, Oracle Financials Implementation Guide, and Updating Establishments, Oracle Financials Implementation Guide. |
| Set up external bank accounts. | conditionally required
Note: External bank accounts are supplier bank accounts. This step is required if the Payments user and/or the Payables user wants to transfer funds electronically to supplier bank accounts. This step is not required if the Payments user and/or the Payables user only wants to print checks. |
Oracle Cash Management, Creating Banking Details, Oracle iSupplier Portal User's Guide, Oracle iSupplier Portal User's Guide. |
| Set up a tax reporting entity. | required | Oracle Payables, Oracle Payables User Guide. See Reporting Entities, Oracle Payables Implementation Guide. |
| Define conversion rates. | conditionally required when using multiple currencies | Oracle General Ledger, Oracle General Ledger User's Guide. See Defining Conversion RateTypes, Oracle General Ledger User's Guide. |
Before you can setup Oracle Payments, you must perform following prerequisite setup steps:
Set Up Taxes, Oracle E-Business Tax User Guide. See Setting Up Taxes, Oracle E-Business Tax User Guide.
Set Up a Tax Registration, Oracle E-Business Tax User Guide. See Setting Up a Tax Registration, Oracle E-Business Tax User Guide.
Set Up Legal Entities, Legal Entity Configurator, Oracle Financials Implementation Guide. See Creating a Legal Entity, Oracle Financials Implementation Guide.
The table below shows the Oracle Payments setup checklist for features used by both funds capture and funds disbursement. These shared setup steps should be setup in the sequence indicated in the table below.
| Step Number | Setup Step | Step Type | Oracle Application |
|---|---|---|---|
| 1. | Creating Oracle Payments Users | required | Application Object Library |
| 2. | Setting Up System Security Options | optional | Oracle Payments |
| 3. | Setting Up or Updating Oracle XML Publisher Templates for Payment Formats or Reporting Formats.
Note: Many such formats are seeded in Oracle XML Publisher. |
conditionally required | Oracle XML Publisher |
| 4. | Setting Up Formats | conditionally required | Oracle Payments |
| 5. | Setting Up Validations | optional | Oracle Payments |
| 6. | Setting Up Transmission Configurations | conditionally required | Oracle Payments |
| 7. | Configuring Tunneling | conditionally required | Oracle Payments |
| 8. | Setting Up Payment Systems | conditionally required | Oracle Payments |
| 9. | Configuring Oracle Payments Sample Servlet | optional | Oracle Payments |
| 10. | Setting Up SSL Security for Payment System Servlet Communication | optional | Oracle Payments |
| 11. | Configuring the XML Framework | required | Oracle Payments |
The table below shows the main user interfaces that Oracle Payments provides that serve different purposes, along with their corresponding responsibilities.
| Main User Interfaces | Corresponding Responsibilities |
|---|---|
| Funds Capture Setup | Funds Capture Setup Administrator |
| Funds Disbursement Setup | Funds Disbursement Setup Administrator |
| Funds Capture Process Dashboard | Funds Capture Process Manager |
| Funds Disbursement Process Dashboard | Funds Disbursement Process Manager |
| Credit Card Processing Analytics | Credit Card Processing Analytics |
A user can be assigned multiple responsibilities and roles.
Note: To access Credit Card Processing Analytics, login using the JTF (Java Technology Foundation) user interface.
You can assign multiple responsibilities and roles to an existing user or to a new user. To create a user, see Step 1. Creating Oracle Payments Users.
The table below lists seeded Oracle Payments responsibilities and their description.
| Responsibility | Description |
|---|---|
| Payments Setup Administrator | Setup for Shared, Funds Capture, and Funds Disbursement
Note: The Payments Setup Administrator responsibility is used only if one user sets up the three functionality pieces listed above. |
| Funds Capture Setup Administrator | Setup for Shared and Funds Capture |
| Funds Disbursement Setup Administrator | Setup for Shared and Funds Disbursement |
| Funds Capture Process Manager | Funds Capture Process Dashboard |
| Funds Disbursement Process Manager | Funds Disbursement Process Dashboard |
| Credit Card Processing Analytics | Credit card Processing Analytics |
If a user is assigned the Credit Card Processing Analytics responsibility, you must assign the role indicated in the table below to the user with its corresponding permissions.
| Responsibility | Role | Permissions |
|---|---|---|
| Credit Card Processing Analytics | IBY_DBC_ROLE (specific to JTF technology stack) | IBY_DBC_ROLE IBY_DBC_VIEW_PERMISSION |
System security options enable you to set security options for payment instrument encryption, masking, and credit card control. These options are used for both funds capture and funds disbursement processes. Payments uses the settings to handle security issues, such as encrypting payment instrument sensitive data, payment instrument masking, and credit card owner verification controls.
For payment instrument encryption, Payments uses a chained key approach. To simplify, the chained key approach is where A encrypts B and B encrypts C. In Oracle Payments, the system key encrypts the subkeys and the subkeys encrypt the payment instrument data. This approach allows easier rotation of the system key. The system key is the encryption master key for the entire installation. It is stored in a wallet file and is used to encrypt Oracle Payments subkeys.
Before you can set up security options, you must set up a wallet. To set up a wallet, see Setting Up the Wallet.
Payments performs system key management using features from Oracle Wallet Manager.
The wallet is a file, which stores the system key. The contents of the wallet file are managed by Oracle Wallet Manager. The wallet file has two functions:
to perform HTTP client authentication of your middle-tier server for payment systems that require this level of security
When used for client authentication, the wallet contains the private key of the entity authorized to send transactions to the payment system (usually the counterpart to the middle-tier server's public certificate). This is sensitive data and, depending on how much trust is placed in the ability to authenticate as the certificate's subject, potentially damaging if compromised.
to store the system (master) security key used to encrypt sensitive data
Storing the system key in the wallet file provides greater security for the encrypted payment instrument data since the system key resides outside the Oracle Payments database. As this key is used to secure such data as credit card numbers, compromise of the wallet is highly damaging.
The purpose of setting up the wallet in the Wallet Setup page is to:
specify the location of the wallet file
define the password for the wallet file
specify whether to generate the system key yourself or let the system do it
To create a wallet file, you must start the Oracle Wallet Manager program. On UNIX systems this is done with the following command:
owm
If the wallet will contain only the system security key, it is sufficient to create an empty wallet file. If the wallet is to contain a private key for client authentication, it must be imported here. Once the wallet file is accessible to the middle-tier server, it is initialized with the system security key using the following Oracle Payments navigation: Oracle Payments Setup > System Security Options. You have the option of importing your own 24-bit system security key (stored in a binary file whose location is specified through the user interface) or you can generate a random one. Once the wallet setup process is complete, a system security key exists in the wallet, and a passwordless version of the wallet named cwallet.sso is created in the same directory as the original wallet file.
To define the password for the wallet file in the Wallet Setup page, enter any string. This password is used to encrypt the wallet file.
In the Wallet Setup page, you can provide the system key by specifying the location of the system key file or you can let the system generate the system key for you. In either case, the specified or generated key is put into the wallet file and encrypted with the password you provide.
In the System Security Options setup page, you specify whether you want to enable or disable encryption of payment instruments and whether you wish the encryption to occur immediately when new payment instruments are registered or be performed on a regularly scheduled basis for performance reasons.
In the System Security Options setup page, credit card numbers and external bank account numbers can be masked by selecting the number of digits to mask and display. For example, a credit card number of XXXX8012 represents a display of the last four digits and a masking of all the rest. These settings specify masking for payment instrument numbers in the user interfaces of many applications.
This option enables you to require users to enter the credit card security code and/or credit card statement billing address. This information is passed to the payment system, which in turn, checks with the credit card issuer to confirm the credit card owner's security code and/or statement billing address.
Payments uses Oracle XML Publisher templates to correctly format funds capture and funds disbursement transactions and to enable you to easily manage the formats. These payment templates can be created new or modified with minimal effort by using a standard text editor, such as Microsoft Word. Consequently, when a payment system or financial institution requires a change to its payment instruction format, the change can be made quickly by modifying the appropriate Oracle XML Publisher template.
Special consideration has been given by Payments to the complexity of creating fixed position and delimited formats. Oracle XML Publisher's eText feature is used for these format types. eText allows the format layout to be presented in an understandable tabular structure.
Several payment-related templates are provided out of the box. You may want to use or modify an existing template to meet your format requirements.
The purpose of setting up Oracle XML Publisher's templates is to create and register templates in Oracle XML Publisher. These templates are required by Oracle Payments to format payment instructions.
Related Topics
For detailed information on creating, registering, and using Oracle XML Publisher's formatting templates, see Oracle XML Publisher User's Guide.
Financial institutions, payment systems, and/or countries have specific formatting requirements for funds capture transactions, funds disbursement transactions, payment documents, and payment-related reporting. Formats are created within Oracle Payments to represent these requirements. Each format in Oracle Payments corresponds to one Oracle XML Publisher template. Oracle Payments uses Oracle XML Publisher templates to format funds capture and funds disbursement transactions according to the formatting requirements of specific financial institutions or payment documents.
In the Create Format setup page, formats are associated with specific Oracle XML Publisher templates and can also be assigned validation sets to validate transactions that use that format. Multiple formats can be used for a single payment system.
One format is provided out of the box for each of the payment-related templates in Oracle XML Publisher.
Before you can set up formats, you must perform the following setup step:
Oracle XML Publisher templates
The purpose of setting up formats is to define formats within Oracle Payments, associate them with your XML Publisher templates, and assign validation sets.
Note: Before you can create a format in Payments, the corresponding XML Publisher template must be available. To see if the corresponding XML Publisher template is available, you can search for it in the Search region of the XML Publisher templates setup page.
Validations ensure that funds capture and funds disbursement transactions are valid, in addition to being correctly formatted before they are printed or submitted to payment systems.
In the Validations page, you can view seeded validations. For each validation, you can view the parameters of the validation and the formats and payment methods to which it is assigned.
You can assign pre-defined or user-defined validations to a format of type Disbursement Payment Instruction or to a funds disbursement payment method. You can assign pre-defined validations to a format of type Funds Capture Settlement Batch.
Related Topics
For detailed information on validations, see Understanding Validations.
For information on formats, see Step 4. Setting Up Formats.
For information on funds disbursement payment methods, see Step 12. Setting Up Funds Disbursement Payment Methods.
A transmission configuration implements a specific transmission protocol, which allows the delivery of a transaction to a specific payment system or financial institution.
Each transmission protocol has parameters that require values. The values defined for the parameters comprise the transmission configuration for that transmission protocol. For example, the payment system, PaymentTech, may require a Socket IP Address of X and a Socket Port Number of Y. Together, X and Y represent Transmission Configuration A for a given transmission protocol.
The purpose of setting up transmission configurations in the Create Transmission Configuration setup page is to enable electronic connectivity with payment systems by specifying parameter values.
Related Topics
For additional information on transmission protocols, see Understanding Transmission.
Tunneling is a transmission feature in Oracle Payments whereby data, such as a payment instruction, is delivered using two protocols, one of which encapsulates the other. Tunneling is also referred to as delegated transmission, since the initial transmission from Oracle Payments is a request to an external module, that is, the Transmission Servlet, to deliver data using an independent transmission protocol. The name of the transmission protocol, its parameters, and the actual data which must be delivered by it are encapsulated within the body of the tunneling transmission protocol.
The purpose of tunneling is to allow connectivity between Oracle Payments and external payment systems without compromising network security. Processor payment systems, for example, often require protocols, such as FTP or raw IP socket connectivity to receive payment instruction files. Instead of creating breaches in their firewall to accommodate these connectivity requirements, users can instead deploy the Payments Transmission servlet on a host outside their firewall and then tunnel, or delegate, requests to it from the Oracle Payments engine. The Oracle Payments Transmission Servlet, by design, makes no use of the applications database, and can be completely isolated from the deployer's intranet.
Oracle Payments uses a customized tunneling protocol called the Oracle Payments Tunneling Protocol (code= IBY_DELIVERY_ENVELOPE). This protocol uses HTTP POST as its underlying transmission mechanism (HTTPS is supported as well) and sends within the body of the request an XML message header identifying the tunneled or encapsulated protocol, as well as the parameters to use when invoking it, such as host name, user name, and password for FTP. After the XML message header is the data to be delivered.
As a transmission protocol code-point, the Oracle Payments Tunneling Protocol implements the oracle.apps.iby.net.TunnelingFunction interface.
The table below presents the parameters and descriptions of the Oracle Payments Tunneling Protocol.
| Parameter | Description |
|---|---|
| WEB_URL | the HTTP/HTTPS URL of the Transmission Servlet executing the protocol |
| USERNAME/PASSWORD | the username and password used to access the servlet if its URL is secured by HTTP authentication |
The Oracle Payments Transmission Servlet is the module which executes tunneled or delegated transmission requests sent from the Oracle Payments engine. The servlet receives Payments HTTP XML Delivery Envelope requests and parses them into XML message header and transmission data components. The format of the XML message header is defined by an XML DTD file named DeliveryEnvelope.dtd. This message header specifies both the parameters to pass to the tunneled/encapsulated transmission protocol, as well as the transmission protocol, itself, by means of its Java code-point class name and entry function name. The Transmission Servlet then attempts to dynamically load the Java class implementing the tunneled protocol and invokes it by passing to it the transmission parameters parsed from the XML message header, as well as the transmission data. This behavior is identical to that of the Oracle Payments engine. Any protocol can be tunneled, as long as it implements the oracle.apps.iby.net.TransmitFunction interface. Therefore, any custom-defined protocol can be tunneled or encapsulated to the servlet, provided the Java class which implements its code-point is in the CLASSPATH of the servlet's application container.
Class oracle.apps.iby.bep.TransmitServlet implements the Oracle Payments Transmission Servlet and is aliased to URL /OA_HTML/ibytransmit on the middle-tier iAS application server. To relocate the servlet to a different host, such as the one in a DMZ network zone, the user must copy all the Applications-specific Java files from the E-Business Suite installation to a class repository accessible by the Transmission Servlet's new servlet container. Any new transmission protocols that you develop must have their Java code copied to this repository if you want the servlet to support that protocol.
Tunneling is configured through the Oracle Payments transmission configuration user interface. A tunneling transmission configuration is specified as any other transmission configuration, but the protocol is always the Payments HTTP XML Delivery Envelope protocol. Once the tunneling protocol is configured, any regular, non-tunneling transmission configuration can use or be encapsulated by it, by specifying a value for the tunneling configuration field in the transmission configuration user interface.
Tip: Oracle Payments does not support the tunneling or encapsulation of a tunneling protocol.
A payment system is an organization that provides financial settlement services. Companies that deploy Payments typically choose payment systems to process their funds captures and, sometimes, their electronic funds disbursements payment instructions. A payment system can be the bank at which the deploying company has its bank accounts or it can be a third party processor that connects deploying companies with financial institutions. The latter is commonly the case for credit card processing. Payment systems are not required for printed funds disbursement payments, but may be required for related services, such as positive pay or other reporting.
Before you can set up payment systems, you must perform the following setup steps:
formats
transmission configurations
The purpose of setting up payment systems is to:
define the external organizations that Oracle Payments collaborates with to process your funds capture and funds disbursement transactions
define the deploying company's relationships with its payment systems
When creating a payment system on the Create Payment System setup page, you:
specify payment instruments the payment system will support on the funds capture side and/or the funds disbursement side
assign payment instruction formats to the payment system
assign transmission protocols to the payment
In this region, you can define parameters that the payment system requires for each transaction or settlement batch. When you define payment system accounts, you provide the actual payment system-provided values for these parameters.
On the funds capture side, payment systems play a central role in the creation of funds capture process profiles, since the creation of a funds capture process profile is payment system-specific. Funds capture process profiles specify how Payments processes settlements, including how the settlement is to be formatted and how it is to be transmitted.
On the funds disbursement side, the payment system plays a smaller role in the creation of payment process profiles, which are blueprints for payments that contain payment instruction formatting and transmission information, as well as payment grouping, payment limits, and payment sorting details.
The Oracle Payments sample servlet is a gateway model servlet that you can use to test your Oracle Payments implementation without having to register with a real payment system. The sample servlet only supports core Oracle Payments operations, such as authorization, capture, and return for credit cards.
You can use the sample servlet to test the integration between your source product and Oracle Payments. All transactions sent to the sample servlet should succeed, unless the transaction amount matches certain pre-set values, in which case an error is induced. You can use the integration to simulate error scenarios and test error handling in the calling source product.
The table below lists the pre-defined transaction amounts and their associated error codes.
| Transaction Amounts | Error Messages |
|---|---|
| 1001 | Communication error when contacting the gateway. Please try again. |
| 1002 | Given order id used for a previous transaction. |
| 1004 | A parameter to this transaction is either malformed or missing. |
| 1005 | Generic payment system error occurred. Please check error code. |
| 1008 | Transaction type is not valid or not supported for this merchant. |
| 1016 | Internal payment system failure. Please check error code. |
| 1017 | Account does not have sufficient funds to complete this transaction. |
| 1019 | Invalid credit card number/expiration date. |
| 1020 | Authorization declined. |
| 1021 | Voice authorization code incorrect. |
To configure the sample servlet, perform the following steps.
Add the alias statement to the configuration file of the servlet zone you wish the sample servlet to run as specified in the orion-web.xml file which is in the following directory:
$ORA_CONFIG_HOME/10.1.3/j2ee/oacore/application-deployments/oacore/html/
In the same configuration file, provide the following servlet zone-wide parameters listed in the table below, which are set by a statement of the form servlet.default.initArgs=.
| Parameter | Example Value | Description |
|---|---|---|
| errorfile | tmp/error.log | Debug file used to write errors and stack traces. |
| debugfile | tmp/debug.log | Log file used to write debugging messages. |
| debug | true, false | Turns debugging on or off. |
Once the sample servlet is installed and configured, the servlet must be added as a payment system so it can be used. Login to the Oracle Payments Setup Administrator responsibility and create a payment system for the sample servlet with the following values:
Name: Sample Servlet
Suffix: lop
Payment System Type: Gateway
Transmission Servlet Base URL: Example - http://localhost:<port>/OA_HTML, where <port> is the port of your installation
Supported Payment Instrument: Credit Card
Note: The sample payment system already exists in the Oracle Payments setup. You only need to enter the Base URL
For each payee that uses the sample servlet, enter any value for the payment system account name.
To test the sample payment system, create a transaction through the Transaction Testing pages, or from a source product. Verify that you have a routing rule that routes the transaction to the sample payment system and that your transaction matches the routing rule.
The $0 authorization cannot be executed using the sample payment system.
Related Topics
For more information on setting up a routing rule for first party payees, see Step 17. Setting Up First Party Payees.
For more information on configuring Paymentech, see Configuring Paymentech on MetaLink, Note 405996.1.
For more information on configuring FDC North, see Configuring FDC North on MetaLink, Note 405999.1.
For more information on configuring Concord EFSnet, see Configuring Concord EFSnet on MetaLink, Note 406000.1.
For more information on configuring Verisign, see Configuring PayPal Payflow Gateway (formerly Verisign) on MetaLink, Note 406002.1.
For more information on configuring CyberSource, see Configuring CyberSource on MetaLink, Note 406003.1.
When Oracle Payments communicates with the payment system servlets, the information exchanged may be sensitive information such as credit card numbers. If the communication is not secure, it poses a security risk.
The security risk increases under the following circumstances if:
Oracle Payments and the payment system servlets are installed on separate machines.
Oracle Payments is running outside your firewall.
To set up a payment system servlet with secured sockets layer, enable HTTPS on the middle-tier server where the servlet resides.
If there are no funds capture profiles defined yet for the payment system, change the BASE URL parameter of the payment system to use the https: protocol. Otherwise, change the URLs on any transmission configurations set up to be used with that payment system to contain https:.
Oracle Payments incorporates an XML framework, which enables it to communicate with payment systems using XML. The IBY: XML_BASE property and, optionally, the IBY: JAVA_XML_LOG property must have valid values. Both properties can be set by running AutoConfig.