5Configure Payment System Connectivity

This chapter contains the following:

Validations are rules that ensure that transactions are valid before they are printed or submitted electronically to payment systems. You use validations to ensure that disbursement transactions, such as invoices, payments, and payment files meet specific conditions before they can be paid. You can assign validations to payment methods and payment formats. A validation can be executed at the document payable, payment, or payment file level.

In payment processing, it's critical that payment files sent to payment systems and financial institutions are valid and correctly formatted. If this is not done, the payment process is slowed, which results in additional time and cost due to problem resolution. Oracle Fusion Payments helps you achieve straight-through processing by ensuring that payment-related details are valid. To assign validations, you can select from the following options:

  • Assigning validations

  • Creating user-defined validations

  • Selecting from a predefined library of validations

The following table lists the objects you can validate and when validations are executed for the applicable setup.

Object Payment Method-Driven Validations are Enforced When... Payment File Format-Driven Validations are Enforced When...

Document Payable

The invoice is saved in the source product.

The invoice installment is selected for payment.

The invoice installment is selected for payment.

Payment

The payment is created by building related documents payable together.

The payment is created by building related documents payable together.

Payment File

Not applicable.

The payment file is created.

Assigning Validations

You can assign user-defined validations to any:

  • Payment method

  • Payment file format

You can assign a validation to whichever object drives the requirement for validation. For example, if your bank format requires a limited number of characters in a specific field, you can assign that validation to the bank format. By doing this, you ensure that the validation is enforced only when applicable. However, if you want to enforce a general validation that isn't specific to the payment method or format, you can consider timing in your decision.

Payments always validates as early as possible for a given object and setup. Document payable validations that are associated with payment methods are enforced earlier in the process than those associated with formats. If you want validation failures handled by the same person who is entering the invoice, you can associate the validation with the payment method. This method is ideal for business processes where each person has full ownership of the items entered. However, if you want focused invoice entry with validation failures handled centrally by a specialist, you can associate the validation with the format. This method is ideal for some shared service centers.

Creating User-Defined Validations

A user-defined validation explicitly specifies the object to which the validation applies:

  • Document payable

  • Payment

  • Payment file

User-defined validations are basic validations that correspond to simple operations. These validations can be used as components, or building blocks, to build more complex validations. They enable you to validate, for example, the following conditions:

  • Length of a value. Example: Payment Detail must be fewer than 60 characters for your bank-specific payment file format.

  • Whether a field is populated. Example: Remit to bank account is required when payment method is Electronic.

  • Whether content of a field is allowed. Example: Currency must be USD when using your domestic payment file format.

Selecting From a Predefined Library of Validations

Payments provides a library of predefined validations. You can associate these predefined validations with any payment method or payment file format you create. Many of the payment formats provided by Oracle have predefined validations associated with them by default.

Predefined validations are groups of individual validations that are together for a specific purpose. Many of the predefined validations that you can associate with payment formats are country-specific. Predefined validations cannot be modified, although some have parameters you can set to define specific values.

Setting up formats is a mandatory task in Oracle Fusion Payments. A format is a disbursements or a funds capture data file to which an Oracle Business Intelligence Publisher (Oracle BI Publisher) template is applied. Oracle BI Publisher templates contain formatting attributes that format data files. Formatted outputs include printed checks, electronically transmitted payment files, settlement batches, and reports.

The purpose of setting up formats is to enable payment systems, financial institutions, or countries to understand your company's messages, given their specific formatting requirements for disbursements or funds capture transactions. Inbound messages come from a payment system or financial institution to your company. Outbound messages leave your company to your payment system or financial institution.

Setting up formats involves the following actions:

  • Using Oracle BI Publisher templates

  • Using data extracts

  • Using the identity format

  • Considering best practices

  • Setting up formats

  • Understanding associations between format entities

  • Assigning validations to formats

Note: Before you can set up formats, you must set up the corresponding templates in Oracle BI Publisher. For more information on setting up templates, see Oracle Fusion Middleware Report Designer's Guide for Oracle Business Intelligence Publisher at http://docs.oracle.com/cd/E25054_01/bi.1111/e13881/toc.htm.

Using Oracle BI Publisher Templates

Each Payments format corresponds to one Oracle BI Publisher template. BI Publisher templates specify exactly how formatted output is to be generated. BI Publisher templates can also be used to generate fixed-position, machine-readable files through BI Publisher's eText functionality.

Using Data Extracts

Each disbursement or funds capture format is also associated with a disbursement or funds capture Payments' data extract. Each data extract contains transactional data. Oracle BI Publisher templates use data extracts to format transactional data. Transactional data is extracted from Payments' or Oracle Fusion Receivables' transactional tables.

For a disbursements extract, data comes from:

  • Payments

  • Payment files

  • Documents payable tables

For a funds capture extract, data comes from:

  • Funds capture transactions

  • Settlement batches

  • Receivables transactions

For more information on Payments' XML extracts, see How To Generate and View Fusion Payments XML Extract , Document ID 1428249.1, on My Oracle Support.

Using the Identity Format

The Identity format outputs the XML extract provided by Payments. It's intended for diagnostic purposes, but you can also use it to understand how extract fields are populated from transactional and setup entities. This is especially helpful if you intend to create complex configurations using other templates.

The Identity format is an Oracle BI Publisher template called IBY_IDENTITY. It's part of the Funds Capture Authorization and Settlement report. If you want to use the Identity format for a disbursements report, you must download the RTF template and upload it as part of the intended disbursements report. Then, you can set up a modified format in Payments using the newly created format with a payment process profile or a funds capture process profile, and examine the XML output.

Considering Best Practices

Before setting up formats, find out what payment formats your processing bank supports. Consider using standards-based payment formats that can be used with multiple banks:

  • EDIFACT formats, such as PAYMUL, MT100, and MT103

  • NACHA formats, such as Generic, CCD, or PPD

Setting Up Formats

In the Setup and Maintenance work area, use the following to select a predefined format type on the Manage Formats page:

  • Offering: Financials

  • Functional Area: Payments

  • Task: Manage Formats

The format type you select specifies:

  • Type of message created

  • Oracle BI Publisher template used to format the data file

  • Data extract used

On the Create Format page, associate an Oracle BI Publisher template with the format type you selected.

Understanding Associations Between Format Entities

The following table describes the association between format types, templates, and data extracts.

Format Types Oracle BI Publisher Template Data Extracts

Disbursement Payment File Formats

Disbursement Payment File Formats

Disbursement Extract

Disbursement Positive Pay File Formats

Disbursement Positive Pay Formats

Disbursement Positive Pay Extract

Disbursement Separate Remittance Advice Formats

Disbursement Separate Remittance Advice Formats

Disbursement Extract

Disbursement Accompanying Letter Formats

Disbursement Accompanying Letter Formats

Disbursement Extract

Disbursement Payment Process Request Status Report Formats

Disbursement Payment Process Request Status Report

Disbursement Payment Process Request Extract

Disbursement Payment File Register Formats

Disbursement Payment File Register

Disbursement Extract

Funds Capture Settlement Format

Funds Capture Authorization And Settlement Formats

Funds Capture Extract

Funds Capture Accompanying Letter Formats

Funds Capture Accompanying Letter Formats

Funds Capture Extract

Funds Capture Payer Notification Formats

Funds Capture Payer Notification Formats

Funds Capture Extract

Assigning Validations to Formats

After you create a format, you can optionally assign predefined or user-defined payment validations to it on the Edit Format page. Validations ensure that disbursements or funds capture transactions execute according to specified conditions.

Computers use transmission protocols to communicate with each other across a network. To transmit data, such as payment files from Oracle Fusion Payments to a payment system, the implementor defines protocols that the payment system can receive.

Payments offers industry-standard transmission protocols, such as FTP, HTTP, and HTTPS, predefined. They are composed of the following:

  • A code entry point, which the payment system servlet uses to accomplish transmission

  • A list of parameters, such as network address and port, for which the transmission configuration must supply values

  • Transmission protocol entry points, which are independent of payment servlets and may be called from the Payments engine

While the transmission protocol defines which parameters are expected in the communication, the transmission configuration defines what value is supplied for each parameter. Transmission configurations and payment systems are associated on the funds capture process profile for funds capture or on the payment process profile for disbursements.

Note: This note applies only to on-premises customers, and never to Oracle Cloud customers. The preferred file-based transmission protocol is Secure File Transfer Protocol (SFTP). File Transfer Protocol (FTP) is unsecured and should only be used to meet legacy third-party requirements. FTP must be used over a secure link such as a virtual private network or a leased line with data link level encryption enabled.

A transmission configuration is a group of specific transmission details. A transmission configuration defines a value for each parameter in a transmission protocol. The values in a transmission configuration are specific to one payment system or financial institution.

For example, suppose a transmission protocol requires parameter values for a Socket IP Address and a Socket Port Number. Your payment system that accepts that protocol will give you the values that it expects to receive for these parameters. You enter the applicable values in the Socket IP Address and Socket Port Number fields for the transmission configuration. The transmission configuration is then assigned to the payment system within the funds capture process profile for funds capture transactions or within the payment process profile for disbursement transactions.

In the Setup and Maintenance work area, use the following to transmit files to your payment system by setting up transmission configurations:

  • Offering: Financials

  • Functional Area: Payments

  • Task: Manage Transmission Configurations

On the Manage Transmission Configurations page, click Create. The Create Transmission Configuration page appears.

How You Set Up Transmission Configurations

In Oracle Fusion Payments, setting up transmission configurations is mandatory if your company wants to transmit payments to a payment system or a bank. To enable your company to exchange information with your payment system or bank, a preexisting agreement must exist as to how information will be structured and how each side will send and receive it.

Setting up transmission configurations involves the following actions:

  • Understanding protocols

  • Understanding transmission configurations

  • Understanding tunneling configurations

  • Considering best practices

  • Setting up transmission configurations

Understanding Protocols

A transmission protocol is a set of rules or procedures for transmitting data between electronic devices, such as computers. To transmit data, such as a payment file or a settlement batch from Payments to an external payment system, you must define the transmission protocols that the payment system can receive.

Payments offers industry-standard predefined transmission protocols, such as SFTP, HTTP, HTTPS, and AS2. These protocols include the following:

  • A protocol implementation class, which implements the technical details of communication in a generic manner

  • A list of parameters, such as network address and port, for which the transmission configuration must supply values

The transmission protocol defines which parameters are expected in the communication between your company and its payment system or bank.

Understanding Transmission Configurations

A transmission configuration is a group of specific transmission details, which is associated with a specific transmission protocol. A transmission configuration defines a value for each parameter in a transmission protocol. The values in a transmission configuration are specific to one payment system or financial institution. For example, a transmission protocol may require parameters, as well as a Socket IP Address, and a Socket Port Number. Your payment system, which accepts that protocol, will give you the values that it expects to receive for those parameters. You enter those values in the Socket IP Address and Socket Port Number fields.

Understanding Tunneling Configurations

A tunneling configuration is a type of transmission configuration that helps transmit data through a transmission servlet that can securely connect to your payment system or bank without exposing internal data. The transmit servlet acts as a relay or bridge between the different segments of your network infrastructure, some of which are more suitable, such as a DMZ zone, from which to open connections to external systems.

Considering Best Practices

Before selecting a protocol for payment processing, do the following:

  • Find out what your processing bank supports.

  • Favor transmission protocols that are predefined in Payments.

  • Use funds capture process profiles or payment process profiles for greater ease in configuring transmission and formatting.

Before selecting a transmission configuration for payment processing, note the following:

You may need two transmission configurations as follows if you use a protocol that is normally blocked by your network security rules:

  • A tunneling configuration to exit the fire wall

  • A transmission configuration for the payment system server

Your transmission configuration must point to the tunneling configuration.

Caution: It is always a configuration error for the tunneling configuration to point to any other tunneling configuration, including itself.

Setting Up Transmission Configurations

In the Setup and Maintenance work area, use the following to select a protocol, which is the method of transmission, and click Create on the Manage Transmission Configurations page.

  • Offering: Financials

  • Functional Area: Payments

  • Task: Manage Transmission Configurations

On the Create Transmission Configuration page, enable electronic connectivity with your payment system or bank by specifying values for each parameter for the protocol you selected.

The transmission configuration is subsequently assigned to a payment system or bank in the funds capture process profile for funds capture transactions or in the payment process profile for disbursements.

How You Configure Pretty Good Privacy (PGP) Encryption and Digital Signature for Outbound and Inbound Messages

You can secure both outbound and inbound messages using payload security. Payload security is the securing of payment files and other files using payment file encryption and digital signature based on the open PGP standard. You can update existing transmission configurations to use encryption and digital signature for your existing connectivity with banks.

For outbound messages, Oracle Payments Cloud supports encryption and digital signature for:

  • Payment files and positive pay files for disbursements

  • Settlement batch files for funds capture

For inbound messages, the application supports decryption and verification of digitally signed encrypted files for:

  • Funds capture acknowledgment files

  • Bank statements

You can also secure payment data using secured transmission protocols, such as SFTP or HTTPS.

Note: Oracle Applications Cloud supports decryption of payment files that are encrypted using version BCPG 1.45 or lower of the OpenPGP standard.

Configuring encryption and digital signature for outbound and inbound messages includes the following actions:

  • Generating keys

  • Setting up outbound transmission configuration

  • Setting up inbound transmission configuration

  • Uploading the bank-provided public key file

  • Downloading the system-generated public key file

Generating Keys

Encryption and digital signature verification requires a public key. Conversely, decryption and signing a digital signature requires a private key. A private key and public key pair is known as the key pair. The party who generates the key pair retains the private key and shares the public key with the other party. You can generate or receive a public key subject to the agreement with your bank.

The following table provides typical generation details of the public and private key pair:

Key Pair Generated Generates Outbound Messages from Payments Generates Inbound Messages to Payments

PGP Public Encryption Key and PGP Private Signing Key

Bank

Deploying company

PGP Public Signature Verification Key and PGP Private Decryption Key

Deploying company

Bank

If you're generating the key pair, you can automatically generate them within Oracle Applications Cloud.

You must import the public encryption key or the public signature verification key that you receive into the Oracle Application Cloud using UCM.

Setting Up Outbound Transmission Configuration

For outbound messages, such as payment files, positive pay files, and settlement batch files, you must:

  • Encrypt your payment file using the bank-provided public encryption key.

  • Optionally, sign the payment file digitally using the private signing key that you generate.

On the Create Transmission Configuration page, you can see the outbound parameters as described in the following table.

Outbound Parameters Description

PGP Public Encryption Key

A key given to you by your bank that you use to encrypt your outbound payment file.

To upload the bank-provided public encryption key, use UCM by navigating to Tools > File Import and Export.

Lastly, on the Create Transmission Configuration page for the PGP Public Encryption Key parameter, select the public encryption key file from the Value choice list.

PGP Private Signing Key

A key generated by you to digitally sign the outbound payment file.

To generate the private signing key, select Quick Create from the Value choice list for the PGP Private Signing Key parameter. The application:

  • Automatically generates the private signing key and links it to your transmission configuration.

  • Generates a public encryption key file that you can download from UCM and share with your bank. The bank uses your public encryption key file to verify the digital signature of the payment files that you transmit to the bank.

Note: You must provide a key password to generate a private signing key using the Quick Create feature. This password is also used for exporting and deleting this key.

Setting Up Inbound Transmission Configuration

For inbound payment messages, such as acknowledgments and bank statements, you must:

  • Verify the digital signature using the bank-provided public signature verification key.

  • Decrypt the file using the private decryption key that you generate.

On the Create Transmission Configuration page, you can see the inbound parameters as described in the following table.

Inbound Parameters Description

PGP Public Signature Verification Key

A key given to you by your bank that you use to validate the digital signature of inbound acknowledgment files or bank statements.

To upload the bank-provided public signature verification key, use UCM by navigating to Tools > File Import and Export.

After uploading the bank-provided public signature verification key using UCM, you can select the key file on the Create Transmission Configuration page. Select it in the Value choice list for the PGP Public Signature Verification Key parameter. After you select the public signature verification key file, it's automatically imported.

PGP Private Decryption Key

A key generated by you to decrypt the inbound encrypted file. To generate the private decryption key, select Quick Create from the Value choice list for the PGP Private Decryption Key parameter. The application:

  • Generates the private decryption key and links it to your transmission configuration.

  • Generates a public signature verification key file that you can download from UCM and share with your bank. The bank uses your public signature verification key file to encrypt acknowledgments and bank statements.

Note: You must provide a key password to generate a private signing key using the Quick Create feature. This password is also used for exporting and deleting this key.

Creating Private Keys Using the Advanced Create Feature

You can also generate private keys by selecting Advanced Create from the Value choice list. Advanced Create feature lets you configure certain properties to generate stronger keys. This enhances the security of payment files transmitted to your bank. Here are the properties you can configure for PGP private signing keys:

Option Description

Key Type

The type of private signing key generated.

  • RSA: Key is generated using the RSA algorithm.

Length

The number of bits in the private signing key (or key size).

  • 2048: 2048-bit key

  • 3072: 3072-bit key

  • 4096: 4096-bit key

Expiration Date

The date when this private signing key expires.

Encryption Algorithm

The encryption algorithm of the private signing key.

  • AES128: 128-bit cryptographic key generated using Advanced Encryption Standard.

  • AES192: 192-bit cryptographic key generated using Advanced Encryption Standard.

  • AES256: 256-bit cryptographic key generated using Advanced Encryption Standard.

  • 3DES: Cryptographic key generated using Triple Data Encryption Standard.

Hashing Algorithm

The hashing algorithm of the private signing key.

  • SHA256: 256-bit hash computed using Secure Hash Algorithm.

  • SHA384: 384-bit hash computed using Secure Hash Algorithm.

Compression Algorithm

The compression algorithm of the private signing key.

  • ZIP: Cryptographic key compression using ZIP algorithm.

  • ZLIB: Cryptographic key compression using ZLIB algorithm.

  • BZIP2: Cryptographic key compression using BZIP2 algorithm.

Configuring these properties lets you meet bank-specific payment file security requirements. When you generate a private key using the Advanced Create option, a corresponding public key is exported to UCM from where you can download it. Similar to Quick Create, you must provide a key password when you use Advanced Create to generate a private key.

Uploading the Bank-Provided Public Key File

To upload or import the bank-provided PGP Public Encryption Key or the PGP Public Signature Verification Key into Oracle Applications Cloud, perform these steps:

  1. Rename the bank-provided key file by including _public.key as the suffix. Ensure that the key file name doesn't have any special characters other than the underscore.

  2. Navigate to: Navigator > Tools > File Import and Export.

  3. Import the bank-provided key file into account fin/payments/import.

  4. Navigate to the Create Transmission Configuration page.

  5. From the Value choice list for the applicable parameter, select the uploaded key file.

    Tip: The key name in the choice list is the same as the one you uploaded using UCM.
  6. After you select the key and save the transmission configuration, the key is automatically imported into the Payments.

Downloading the System-Generated Public Key File

To download the system-generated public key file from Payments to share with your bank, perform the follow steps:

  1. On the Create Transmission Configuration page, select Quick Create for the applicable parameter.

  2. Click the Save and Close button.

  3. Navigate to: Navigator > Tools > File Import and Export.

  4. From the Account choice list, select fin/payments/import and search for the system-generated public key file.

  5. Download the system-generated public key file.

    Tip: The file name is similar to the private key file that was generated and attached to the transmission configuration.
Note: SSH (Secure Socket Shell) key-generation for SFTP two-factor authentication is generated by Oracle Support based on a service request.

Exporting and Deleting Keys

The Export and Delete option lets you securely export a selected private or public key. This lets you use the same key for different environments. When you export a key using this feature, the key is exported to UCM from where you download it. If the selected key is a private key, you must provide the key password that was used while generating the key. No key password is required for exporting public keys.

You can also use this feature to delete PGP. However, you can't delete a key that's currently attached to a transmission configuration. When you delete a system-generated private key, the corresponding public key is also deleted. Just like how exporting works, deleting a key also requires the key password, if the selected key is a private one. No password is required for deleting a public key.

The Export and Delete feature works not only for the application-generated keys but also for imported keys.

How You Configure Two-Factor Authentication Using A Security Key File

You can enable security key file-based authentication in addition to the user credential-based authentication for more secured transmission. The key pair can be generated within Payments or can be generated externally and imported. You can use the private key within Payments and share the public key with your bank.

Importing an Externally-Generated Security Key File

Before you import the security key file, ensure that these conditions are met:

  • The Master encryption key has already been configured using the Manage System Security Options task.

  • Ensure that the key file name doesn’t have any special characters other than the underscore (_).

  • Ensure that the key file has the SSH extension (file name has .ssh as suffix).

  • Ensure that file name length (including the extension) doesn't exceed 26 characters.

Here’s how you import externally generated private security key file:

  1. Upload the file in UCM using the File Import and Export utility. Use this UCM account: fin/payments/import.

  2. Create or update the SFTP transmission configuration.

  3. Select the private key file that should now be available in the Client Private Key File choice list.

  4. Enter the applicable password for this key file in the Client Private Key Password field and then click Save.

Generating a Key File

Perform these steps to generate a key file within the Payments application:

  1. In the Setup and Maintenance work area, go to the Manage Transmission Configurations task:

    • Offering: Financials

    • Functional Area: Payments

    • Task: Manage Transmission Configurations

  2. Select the transmission protocol for which the key pair must be generated.

  3. Create a new transmission configuration or select an existing one.

  4. Enter the transmission details.

  5. In the Value choice list for the Client Private Key File, select Quick Create to generate a key pair.

    Note: You must enter the password for private key file in the Client Key File Password field.

The application generates the key pair and populates the Client Private Key File field with the private key file name. This file name has the SSH extension. You can download the corresponding public key file from the UCM account /fin/payments/import. This public key has the same file name as the private key. However, it has a PUB extension (file name has .pub as suffix). Share the public key file with the bank to deploy it on the SFTP server.

Creating Private Keys Using the Advanced Create Feature

In addition to the Quick Create feature, you can also generate private keys by selecting Advanced Create from the Value choice list. Advanced Create feature lets you configure certain properties to generate stronger keys. You can configure these properties for client private keys that use SSH encryption:

Option Description

Key Type

The type of SFTP key generated.

  • RSA: Key is generated using the RSA algorithm.

Length

The number of bits in the SFTP key (or key size).

  • 2048: 2048-bit key

  • 3072: 3072-bit key

  • 4096: 4096-bit key

When you generate a private key using the Advanced Create option, a corresponding public key is exported to UCM from where you can download it. Similar to Quick Create, you must provide a key password when you use Advanced Create to generate a private key.

Exporting and Deleting Keys

The Export and Delete option lets you securely export selected private or public keys that use SSH encryption. This lets you use the same key for different environments. When you export a key using this feature, the key is exported to UCM from where you download it. If the selected key is a private key, you must also provide the key password. No key password is required for exporting public keys.

You can also use this feature to delete SSH keys. However, you can’t delete a key that’s currently attached to a transmission configuration. When you delete a system-generated private key, its corresponding public key is also deleted. You must also provide the key password when deleting a private key. You don’t need a password to delete a public key.

The Export and Delete feature works for both application-generated keys and imported keys.

The transmission configuration setup is used to transmit outbound payment files, settlement batch files, and positive pay files to your payment system or financial institution. It's also used to pull funds capture acknowledgment files. The setup captures various parameters, which may be different for different protocols. You can test your transmission configuration to confirm whether your setup of outbound and inbound transmission protocols is correct.

To confirm the accuracy of the setup, click the Test button on the Create or Edit Transmission Configuration page. The Test button is active only when the values associated with all the mandatory parameters are present. Typical transmission configuration parameters that are available to test include:

  • Destination server URL

  • Destination server IP address

  • Destination server port number

  • Remote file directory

  • User credentials

Testing the transmission configuration setup includes reviewing return messages.

Reviewing Return Messages

The Test button action contacts the destination server with the specified parameters, which results in a return message. The return message is a combination of functional text and raw message text. This occurs so both functional and technical users can benefit from the message. For example, suppose the remote file directory is invalid. The return message is: Incorrect remote directory (IBY_Trans_Test_Remote_Dir_Fals).

The following table describes transmission configuration connection tests and test results with their associated return messages.

Test Test Result Return Message

Whether the connection is correct.

  • Connection is successful.

  • Remote file directory is present.

Success (raw message)

Whether the remote file directory is valid.

  • Connection is successful.

  • Remote file directory isn't present or incorrect.

Incorrect remote directory (raw message)

Whether user credentials are correct.

  • Connection is unsuccessful.

  • Destination IP address and port is correct.

  • Incorrect login credentials.

Incorrect user credentials (raw message)

Whether IP address or port is correct.

  • Connection is unsuccessful.

  • Incorrect IP address or port.

Incorrect destination server details (raw message)

Whether two factor key file-based authentication is successful.

  • Connection is unsuccessful.

  • Unsuccessful key file-based authentication.

Unsuccessful authentication (raw message)

Whether the destination server is responsive.

Destination server is down.

Destination server is not responding (raw message)

Not applicable.

Any other failure.

(raw message)

How You Configure a Communication Channel to a Payment System

To transmit payment information to or receive payment information from a payment system, you must configure the channel used to communicate with the payment system. This topic discusses the following concepts:

  • Proxy server

  • Secure sockets layer (SSL) protocol

  • Unsecured protocols

Proxy Server

Payments must communicate through a proxy server to its payment system. You can use the standard Java networking proxy system properties that are in the configuration files when Oracle Fusion Applications were initially set up. Alternatively, you can specify proxy settings for a transmission protocol on the Create Transmission Configuration page by entering a value for the Proxy Host parameter.

Secure Sockets Layer Protocol

When Payments communicates with a payment system, the information exchanged may be sensitive information, such as credit card numbers. If the communication isn't secure, it poses a security risk. The security risk increases when communication to the payment system is across a public network, such as the Internet.

To set up a payment system servlet with a secure sockets layer, enable HTTPS on the application server where the servlet resides. If funds capture process profiles aren't defined for the payment system, change the Transmission Servlet Base URL on the Edit Payment System page to start with HTTPS. If funds capture process profiles are defined, change the value for the Destination URL parameter on the Edit Transmission Configuration page to start with HTTPS.

For secure communication with the payment system, ensure that the most current certification authority (CA) certificates are in the Oracle Fusion secure sockets trust store file. If Payments rejects the payment system's secure sockets certificate, you may have to insert the certificates manually.

The following table lists security actions that are applicable to Cloud and on-premise.

Action Cloud On-premise

Set up a payment system servlet with a secure sockets layer.

Not applicable.

Enable SSL on the servlet's application server.

Insert certification authority certificates.

File a service request with the help desk.

Enter a value in the Value field for the Wallet Location parameter on the Create or Edit Transmission Configuration page.

Unsecured Protocols

The preferred file-based transmission protocol is Secure File Transfer Protocol (SFTP). File Transfer Protocol (FTP) is unsecured and should only be used to meet legacy third-party requirements. FTP must be used over a secure link such as a virtual private network or a leased line with data link level encryption enabled.

If your company wants to transmit electronic payments or funds capture transactions to a payment system or a bank, you must set up a payment system. A payment system defines the organization that Payments uses to process your funds capture and disbursement transactions. Here's what can be considered as a payment system:

  • The bank where your company has its bank accounts

  • A third-party processor or gateway that connects your company to a financial network

Payment systems aren't required for printed disbursement payments, such as checks, but may be required for related services, such as a positive pay report.

Set up a payment system by completing these actions:

  • Selecting a gateway or processor payment system

  • Considering best practices

  • Defining a payment system

  • Specifying payment system settings

  • Understanding payment system accounts

Selecting a Gateway or Processor Payment System

Payments supports both gateway and processor payment systems. A gateway is a service provider that acts as an intermediary between a first party payee and a payment processor. A processor is a service provider that interacts directly with banks and card institutions to process financial transactions. Examples of payment processors include Visa, MasterCard, and American Express.

Your choice of integrating with a gateway or a processor payment system is generally determined by your:

  • Type of business

  • Number of transactions per day

  • Your bank

This table describes the differences between gateway and processor payment systems.

Factors Gateways Processors

Connectivity and Security

Provide easy connection, often using SSL-based internet connectivity.

Provide more rigorous security, connectivity, and testing requirements.

Additional Fees

Charge additional fees, including per-transaction fees, beyond what processors charge.

Not applicable.

Volume of Transactions

Favor lower-volume merchants or merchants who are willing to pay a per-transaction premium for easier setup and connectivity.

Often favor higher-volume merchants who are willing to exert more effort for processor connectivity.

Online or Offline

Takes all transactions online.

Enables authorizations in real-time and follow-up transactions, such as settlements and credits offline.

  • Offline transactions must be batched together and sent as a single request to the payment system.

  • All transactions other than authorizations are, by default, performed offline.

  • Offline transactions are sent when the next settlement batch operation is attempted.

Considering Best Practices

Before you set up a payment system, use your current banking or processing relationship. Determine whether your bank or processor can process transactions or has a partnership with a processor.

Defining a Payment System

To define a payment system, go to Financials > Payments > Manage Payment Systems page in the Setup and Maintenance work area.

On the Manage Payment Systems page, click Create. The Create Payment System page appears.

When you set up a payment system on the Create Payment System page, specify these values:

  • Types of payment instruments the payment system supports for funds capture transactions

  • Data file formats and transmission protocols accepted by the payment system

  • Settings required by the payment system

  • Settings required by the tokenization provider if your company has enabled tokenization

Note: Setting up a payment system may be required, even for transmitting a payment file offline by downloading it to your local drive and then emailing it to your payment system or bank. The payment system and payment system account setup capture several attributes, which are passed in the payment file or settlement batch message. Without these attributes, a payment file is invalid and rejected by bank.

Specifying Payment System Settings

In the Settings Required by Payment System section, specify the settings that the payment system requires from each internal payer or payee. These settings can be used to identify the internal payer or payee as a client of the payment system or to provide other processing information. You can specify the type of data required for each setting and decide whether it's advisable to secure the setting's values by masking.

Tip: The payment system generally provides the values for the payment system settings, which you enter as part of the payment system account.

Understanding Payment System Accounts

You define your company's account with the payment system on the Edit Payment System Accounts page. The payment system account contains a value for each of the attributes required by the payment system. For example, the payment system may require a Submitter ID and Submitter Password to be included in any message sent to it.

You can configure a secure payment system account by entering a password. For secured settings, the values captured in the payment system account are masked.

Tip: You can set up multiple payment system accounts in Payments for a single payment system.

A payment system account is an account identifier that's composed of values for parameters. The payment system provides you with the values that it requires to identify each payment or settlement batch file. Stored in the payment system account are values for settings and your company's identifiers. Your company can have multiple payment system accounts with a single payment system.

Payment system accounts are associated with the following setup objects:

The following table lists setup objects and the action they perform relative to the payment system.

Setup Object Setup Object Action

Payment system

  • Tells Payments where to send the funds capture transactions.

  • Tells Payments where to send the disbursements transaction.

Payment system account

Tells Payments how to identify itself to the payment system

Transmission configuration

Tells Payments how to transmit the transaction to the payment system

Internal Payees

You can set up routing rules that are assigned to an internal payee. Routing rules specify which payment system account a transaction is transmitted to, based on the values of various transaction attributes.

If you don't need granular routing rules to determine which payment system account is the right one for a transaction, or if you want a fallback value should none of the routing rules apply, you can set up one default payment system account on each internal payee for each payment method.

Funds Capture Process Profiles

The funds capture process profile tells Oracle Fusion Payments how to process a funds capture transaction and how to communicate with the payment system. A funds capture process profile is specific to one payment system and its payment system accounts.

For each payment system account that's enabled on the funds capture process profile, you can select up to three transmission configurations, one each for authorization, settlement, and acknowledgment.

Payment Process Profiles

The payment process profile tells Payments how to process a disbursement transaction and how to communicate with the payment system to transmit a payment file or a positive pay file. When an electronic transmission is required, a payment process profile is specific to one payment system and its payment system accounts. For each payment system account that's enabled on the payment process profile, you select a transmission configuration.

Setting Up Payment System Connections for Multiple Business Units: Explained

When you implement credit card functionality in different countries, you can configure separate merchant account and secure acceptance profile combinations for each business unit in each country. A merchant account is a merchant identifier that you set up with CyberSource, the tokenization service provider. A secure acceptance profile represents connection settings that merchants use for their credit card transactions. You can set up payment system connections at both the payment system level and at the payment system account level. The payment system level captures parameters that are necessary to connect with CyberSource. You can also capture the same parameters at the payment system account level, as well as additional parameters, such as the business unit. With these connection options, you can configure separate payment system accounts for each merchant account in CyberSource.

For multiple business units, you first set up connection settings for each merchant account and secure acceptance profile combination in CyberSource for each business unit in a country. Then, you must enter corresponding connection settings in Oracle Payments at the payment system account level. In this scenario, the parameters configured at the payment system level act as the default connection setup. If, however, there is no payment system account for a business unit, the application uses the parameter values from the payment system level. Similarly, if you have only one merchant account, then you configure payment system connections at the payment system level.

This figure shows how the setup in CyberSource relates to the setup in the application.

This figure shows the setup of connections for
multiple business units in CyberSource and Oracle Payments.

Prerequisite

Before you can set up payment system connections for multiple business units, you must enable tokenization on the Manage System Security Options page.

Setting Up Multiple Merchant Account and Secure Acceptance Profile Combinations

Before you can use credit card features in Oracle Public Cloud Applications, you must follow these steps in CyberSource:

  1. Establish a merchant account with CyberSource.

  2. Create an active CyberSource Secure Acceptance profile.

Setting Up Payment System Connections

If you have only one merchant account and secure acceptance profile combination, then you must set up connection information on the Create Payment System page.

The following table contains the connection settings that you enter in the Value fields in the Tokenization Payment System Settings section on the Create Payment System page and on the Create Transmission Configuration page.

CyberSource Payments Setting Payments Page Payments Field

Secure Acceptance profile generates the Secure Acceptance Access Key

Secure Acceptance Access Key

Create Payment System page

Securely cut and paste the Secure Acceptance Access Key in the Value field.

Secure Acceptance profile generates the Secure Acceptance Signature Key

Secure Acceptance Signature Key

Create Payment System page

Securely cut and paste the Secure Acceptance Signature Key in the Value field.

CyberSource Secure Acceptance Web/Mobile Configuration Guide

Tokenization Servlet Base URL

Create Payment System page

Copy this constant value from the CyberSource Secure Acceptance Web/Mobile Configuration Guide and paste the Tokenization Servlet Base URL in the Value field.

Note: Tokenization Servlet Base URL is referred to as iFrame Create Payment Token Endpoint in CyberSource documentation.

Secure Acceptance profile automatically generates the Profile ID when the profile is saved.

Client Identifier, which is the same as the Profile ID.

Create Payment System page

Enter the Profile ID in the Value field.

Not applicable

Token Creation Module

Create Payment System page

Select CyberSource Secure Acceptance Web from the Value choice list.

CyberSource Secure Acceptance Web/Mobile Configuration Guide

Tokenization Payment URL

Create Payment System page

Copy this constant value from the CyberSource Secure Acceptance Web/Mobile Configuration Guide and paste the Tokenization Payment URL in the Value field.

Note: Tokenization Payment URL is referred to as iFrame Transaction Endpoint in CyberSource documentation.

CyberSource SOAP Tool Kits for Web Services Developer Guide

SOAP Transaction URL

Create Transmission Configuration page

Copy this value from the CyberSource SOAP Tool Kits for Web Services Developer Guide and paste the SOAP Transaction URL in the Value field.

Setting up Merchant Connections

If you have multiple merchant account and secure acceptance profile combinations, then you set up connection information on the Edit Payment System Accounts page.

The following table contains connection settings that you enter in the Value fields in the Settings section on the Edit Payment System Accounts page.

CyberSource Payments Setting Payments Page Payments Field

Not applicable

Commerce Indicator

Edit Payment System Accounts page

Enter internet in the Value field.

Transaction Security Key page generates the Transaction Security Key.

SOAP API Security Key

Edit Payment System Accounts page

Enter the Transaction Security Key in the Value field that you downloaded previously.

Secure Acceptance profile generates the Secure Acceptance Access Key

Secure Acceptance Access Key

Edit Payment System Accounts page

Note: If this connection is configured at the payment system account level, it is captured here. If this connection is configured at the payment system level, it is captured there.

Securely cut and paste the Secure Acceptance Access Key in the Value field.

Secure Acceptance profile generates the Secure Acceptance Signature Key

Secure Acceptance Signature Key

Edit Payment System Accounts page

Note: If this connection is configured at the payment system account level, it is captured here. If this connection is configured at the payment system level, it is captured there.

Securely cut and paste the Secure Acceptance Signature Key in the Value field.

Secure Acceptance profile automatically generates the Profile ID when the profile is saved.

Client Identifier, which is the same as the Profile ID.

Edit Payment System Accounts page

Note: If this connection is configured at the payment system account level, it is captured here. If this connection is configured at the payment system level, it is captured there.

Enter the Profile ID in the Value field.

Import and Export Tokenization Setup Data

Your tokenization setup data is comprised of values, or keys, that are set up on the Create Payment System and Payment System Accounts pages. On these pages in your test environment, you enter values for the Secure Acceptance Access Key and the Secure Acceptance Signature Key in the applicable Value fields. Values for the keys come from your CyberSource test account. Both keys are used to authenticate with the CyberSource data center. They are required to perform tokenization.

This figure shows the steps to complete to export tokenization setup data from your test environment, copy tokenization setup data from your production environment to your test environment, and after you complete credit card testing, import the same tokenization setup data that you exported.

Note: Credit card services are currently not available in Oracle Financials Cloud implementations.
Steps you complete to import and export tokenization
setup data.

To test credit cards and tokenization setup data in a production-like environment, complete these steps:

  1. Export tokenization setup data from your test environment to your local drive and save it as a file.

  2. Copy your production tokenization setup data to your test environment, which overwrites the test environment with production-like tokenization setup data.

  3. Import the same tokenization setup data file you previously exported into the production-like environment to restore it to the original test environment.

Exporting Tokenization Setup Data

To export tokenization setup data from your test environment to your local drive, complete these steps:

  1. Navigate to Tools > Scheduled Processes.

  2. On the Overview page, click Schedule New Process.

  3. On the Schedule New Process page, search and select the Import Security Credential Job.

  4. From the Credential File Type choice list, select Export Tokenization Setup.

  5. Click Submit.

  6. Navigate to Tools > File Import and Export.

  7. From the Account choice list, select fin/payments/import.

  8. Click Search.

  9. In the Search Results section, click your file and save it to your local drive.

Copying Production Tokenization Setup Data to Test Environment

To copy your production tokenization setup data to your test environment, follow your standard practice. Your copy procedure overwrites your test environment with production tokenization setup data. Now you can test your credit cards in a production-like environment.

Uploading Exported Tokenization Setup Data

Before you can import the tokenization setup data, you must upload the file you previously downloaded from your local drive to UCM. To upload the file, complete these steps:

  1. Navigate to Tools > File Import and Export.

  2. Click on the + icon in the Search Results section.

  3. In the Upload File dialog box, click Choose file to browse to the file you want to upload.

  4. From the Account choice list, select fin/payments/import.

  5. Click Save and Close.

Importing Tokenization Setup Data

To import tokenization setup data from your local drive to your production-like environment, complete these steps:

  1. Navigate to Tools > Scheduled Processes.

  2. On the Overview page, click Schedule New Process.

  3. On the Schedule New Process page, search and select the Import Security Credential Job.

  4. From the Credential File Type choice list, select Import Tokenization Setup.

  5. From the UCM File Name choice list, select the file that you uploaded.

  6. Click Submit.

Import a Security Credential File

To secure your electronic transmissions, you can upload, import, and assign a security credential file to transmission configurations. A security credential file is a digital file that stores your security key. The application uses this key to encrypt or authenticate data transmitted to remote third-party systems such as banks. The security credential file can be used for transmission security by any future process that runs and references the transmission configuration. The application understands which credential files are used by which protocols and displays only the appropriate ones in the setup pages.

Payments supports a variety of security-related credential files, including wallet files, trust store files, and digital certificates.

Note: This procedure is applicable to Oracle Cloud implementations only.

Before you can import a security credential file with its key into Payments, you must first create a Payments master encryption key.

Creating a Wallet File and a Master Encryption Key Automatically

To create a wallet file and a master encryption key automatically, complete these steps:

  1. In the Setup and Maintenance work area, go to Financials > Payments > Manage System Security Options.

  2. On the Manage System Security Options page, click Apply Quick Defaults.

  3. Select the Automatically create wallet file and master encryption key check box.

  4. Click the Save and Close.

Uploading the Wallet Security Credential File

Before you can import the security credential file, you must first upload it to Payments.

Caution: Ensure that the credential file is password-protected when you create it. It must be deleted from Oracle Fusion Applications as soon as the import process completes.
  1. Go to Tools > File Import and Export.

  2. Click the Upload icon to open the Upload File dialog box

  3. Browse to the file you created and stored locally.

  4. From the Account choice list, select fin/payments/import.

  5. Click the Save and Close button.

Importing the Wallet Security Credential File

To import security-related credential files, use the Import Security Credential Job process. These files include wallets and private keys used in advanced security features.

  1. Go to Tools > Scheduled Processes to open the Scheduled Processes page.

  2. Click the Schedule New Process button to open the Schedule New Process dialog box.

  3. Search and select the case-sensitive Import Security Credential Job to open the Process Details dialog box.

  4. From the Credential File Type choice list, select the appropriate file type for your credential.

  5. In the Security Credential Name field, enter a name for the credential file.

  6. From the UCM (Universal Content Management) File Name choice list, select the file you previously uploaded.

  7. Click the Submit button.

    A confirmation message indicates the process ran successfully.

  8. Click the Close button.

  9. Click the Refresh icon. The Import Security Credential Job appears in the Search Results section with a status of Succeeded.

Assigning the Wallet File to a Transmission Configuration

To assign the credential file to a transmission configuration, complete these steps:

  1. In the Setup and Maintenance work area, go to Financials > Payments > Manage Transmission Configurations.

  2. On the Manage Transmission Configurations page in the Search section, select your protocol from the Protocol choice list and click Search.

  3. In the Search Results section, click the applicable configuration link to open the Edit Transmission Configuration page.

  4. In the Value field for your protocol's applicable parameter, select the file you created, uploaded, and imported.

    The name of the specific parameter used to import a security credential file depends upon the protocol.

You can now securely transmit electronic files using this transmission configuration.

FAQs for Configure Payment System Connectivity

A type or categorization that indicates what a format is used for. Examples of format types include payment file, remittance advice, and bank statement. Each format that you create in Oracle Fusion Payments is associated with a format type so the application knows how the format is used. Format types are either disbursement formats that relate to payment files or funds capture formats that relate to settlements or reports.

The following table lists several examples of format types.

Disbursement Format Types Funds Capture Format Types

Disbursement separate remittance advice

Funds capture authorization and settlement

Disbursement positive pay file

Funds capture accompanying letter

Disbursement payment process request status report

Funds capture payer notification

The format type you associate with a format specifies the following:

  • Type of message that is created

  • Data extract that is used by the template to format the transaction data

Can I Set Up Payment System Connections for Multiple Business Units?

Yes. When you implement credit card functionality in different countries, you can configure separate merchant account and secure acceptance profile combinations in CyberSource for each business unit in each country. Then, you enter corresponding connection settings in Oracle Payments at the payment system account level. You can set up payment system connections at both the payment system level and at the payment system account level. The payment system level captures parameters that are necessary to connect with CyberSource. The payment system account level captures the same parameters as the payment system level, as well as additional parameters, such as the business unit. With these connection options, you can configure separate payment system accounts for each merchant account in CyberSource.