Skip Headers

Oracle Payments Implementation Guide
Release 12.1
Part Number E13416-05
Go to Table of Contents
Go to previous page
Go to next page

Shared Setup Tasks for Funds Capture and Funds Disbursement


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.

Recommended Setup Steps

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

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.

Setting Up Function Security

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:

Setup Checklist for E-Business Suite Products

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 Checklist for E-Business Suite Products
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:

Setup Checklist for Shared Oracle Payments Setup Tasks

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.

Oracle Payments Setup Checklist for Features Used by Both Funds Capture and Funds Disbursement
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

Step 1. Creating Oracle Payments Users

The table below shows the main user interfaces that Oracle Payments provides that serve different purposes, along with their corresponding responsibilities.

Oracle Payments User Interfaces with 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.

Assigning Responsibilities and Roles to an Oracle Payments User

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.

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.

Credit Card Processing Analytics Responsibility and its Corresponding Required Role and Permissions
Responsibility Role Permissions
Credit Card Processing Analytics IBY_DBC_ROLE (specific to JTF technology stack) IBY_DBC_ROLE IBY_DBC_VIEW_PERMISSION

Step 2. Setting Up System Security Options

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.

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:

The purpose of setting up the wallet in the Wallet Setup page is to:

Creating a Wallet File

To create a wallet file, you must start the Oracle Wallet Manager program. On UNIX systems this is done with the following command:


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.

Defining the Wallet File Password

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.

Specifying or Generating the System Key File Location

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.

Encrypting Payment Instruments

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.

Masking Payment Instruments

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.

Verifying Credit Card Owners

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.

Step 3. Setting Up Oracle XML Publisher Templates

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.

Step 4. Setting Up Formats

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:


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.

Step 5. Setting Up Validations

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.

Step 6. Setting Up Transmission Configurations

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.

Step 7. Configuring Tunneling

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.

Tunneling Protocol

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 interface.

The table below presents the parameters and descriptions of the Oracle Payments Tunneling Protocol.

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

Transmission Servlet

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

Configuring Tunneling

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.

Step 8. Setting Up Payment Systems

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:


The purpose of setting up payment systems is to:

Specifying Supported Capabilities

When creating a payment system on the Create Payment System setup page, you:

Settings Required by Payment System

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.

Payment Systems on the Funds Capture Side

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.

Payment Systems on the Funds Disbursement Side

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.

Step 9. Configuring Oracle Payments Sample Servlet

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.

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.

Installing the Sample Servlet

To configure the sample servlet, perform the following steps.

  1. 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:

  2. 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=.

    Zone-Wide Parameters
    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.

Configuring Sample Servlet as a Payment System

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:

Note: The sample payment system already exists in the Oracle Payments setup. You only need to enter the Base URL

Adding a Payment System Account

For each payee that uses the sample servlet, enter any value for the payment system account name.

Testing the Sample Payment System

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.

Step 10. Setting Up SSL Security for Payment System Servlet Communication

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:


  1. To set up a payment system servlet with secured sockets layer, enable HTTPS on the middle-tier server where the servlet resides.

  2. 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:.

Step 11. Configuring the XML Framework

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.