Using Oracle Payments with External Payment Systems

Overview of Payment System Integration

This chapter explains how to integrate Oracle Payments with an external payment system.

Oracle Payments architecture allows for integration with third party payment systems for both inbound (funds capture) and outbound (disbursements) transaction processing.

In the funds capture flow, the external payment system can be one of two kinds: gateway or processor. For gateway-model payment systems, every transaction is online and involves real-time communication with the payment system. Processor model payment systems support real-time communication for authorizations and batch operation for settlement processing.

In the disbursements flow, there is no concept of real-time transaction processing. Payment processing is performed in batch mode only (usually by FTPing a payment file to the payment system).

Payment System Integration Components

When implementing an integration between Oracle Payments and a custom payment system, you will need to develop a number of integration components. Integration components are building blocks that are invoked by Oracle Payments at different stages of the payment processing cycle.

The list of components to be implemented depends on various factors such as the type of payment flow (whether funds capture or disbursements), the type of the payment system (whether gateway or processor), and the type of the payment instrument, whether credit card, debit card, or bank account.

The table below lists the various integration component types that may be implemented for interfacing with a custom payment system. Your custom implementation may only require a subset of the listed integration components.

Integration Point Type Component Types
Integration Component Description
Format Used in the construction of a payment system-specific message or payment file.
Processor model payment systems typically support two formats: one for online transactions and the other for batch transactions.

Note: Gateway model payment systems typically support online formats only.
Format Validation Contains the set of payment system-specific validations.
Transmission Function Define how to communicate with the payment system.
Acknowledgement Parser Define how Oracle Payments handles a response message from the payment system to a request message, whether online or batch.
Payment System Define attributes for the payment system, which you provide in the setup user interface.
Process Profile Define the attributes of a payment system, which is used to control the payment processing behavior within Oracle Payments.

Note: The process profile can be a funds capture process profile for funds capture or a payment process profile for disbursements.

Note: Several of the integration component types are developed in Java.

Oracle Payments supports both inbound (funds capture) and outbound (disbursement) flows. Therefore, separate sections outline how you can implement a payment system integration for funds capture and for funds disbursement. The sections below explain in detail the tasks you must perform to achieve a custom payment system integration.

For both funds capture and funds disbursement, you must perform some basic setups using the Oracle Payments Setup page. These basic setups are similar for funds capture and funds disbursement and involve the creation of entities, such as payment systems, payment system accounts, and process profiles.

The rest of the integration involves creating integration components, such as format, transmission, validation and acknowledgement. Creation of these components depends on the characteristics of your payment system and are discussed in detail below.

Developing a Custom Payment System Integration for Funds Capture

The list of tasks required to be performed for integration with a custom payment system depends on the following factors:

Implementation guidelines for integrating with a custom payment system include the following:

To determine what tasks you need to perform for your custom integration, see the flowchart below.

Integration Task List for Funds Capture Payment Systems

the picture is described in the document text

The table below lists the tasks that must be completed for integrating a payment system for funds capture.

Basic Setup Tasks for Integrating a Custom Payment System
Task Mandatory Description
Define the payment system. Yes Set up the new payment system.
For information on setting up payment systems, see Step 8. Setting Up Payment Systems.
Define payment system account options. No Set up the options for all accounts with the payment system.
Create funds capture process profile. Yes Define a funds capture process profile specific to the payment instrument (credit card, debit card, or bank account).
The funds capture process profile controls the behavior of all funds capture operations.
For information on setting up payment systems, see Step 21. Setting Up Funds Capture Process Profiles.
Create transaction validation. No Required only if you want to implement payment system-specific validations.
Create batch validation. No Never for gateway model payment system.
For processor model payment system, required only if you want to implement payment system-specific validations.
Seed validation assignments. No Required only if you want to implement payment system-specific validations.
Online Transaction Processing Infrastructure Tasks
Task Mandatory Description
Develop an online authorization/verification format template. No Define a payment system-specific authorization format and develop a template for XML Publisher.
For credit card and debit card processing, it is necessary to implement online authorization formats.
For processing bank account transactions, implementation of online verification formats is payment system dependant.
Create XML Publisher templates using the elements of the funds capture extract.
For information on funds capture extract, see Funds Capture Extract.
Set up the online authorization/verification format template. No Define system data attributes for the new format. Link the newly created XML Publisher template to the format.
For information on setting up formats, see Step 4. Setting Up Formats.
Develop an online authorization/verification transmission function. No Implement a transmission function protocol.
Setup the online authorization/verification transmission protocol. No Define a transmission protocol and associate it with the transmission function code-point that implements it. Also define the protocol parameters.
For information on setting up transmission configurations, see Step 6. Setting Up Transmission Configurations.
Develop an online authorization/verification acknowledgement parser. No Implement an acknowledgement parser.
Setup the online authorization/verification acknowledgement parser. No Define system data attributes for the parser.
Develop a settlement format template. No For gateway model payment system, the format may be identical to the authorization format template.
This task is not relevant for processors.
Create XML Publisher templates using the elements of the funds capture extract.
For information on funds capture extract, see Funds Capture Extract.
Setup the settlement format template. No This task is not relevant for processors.
Link the newly created XML Publisher template to the format.
For information on setting up formats, see Step 4. Setting Up Formats.
Develop a settlement transmission function. No For gateway model payment systems, the transmission function may be identical to the authorization transmission function.
This task is not relevant for processors.
Setup the settlement transmission protocol. No This task is not relevant for processors.
For information on setting up transmission configurations, see Step 6. Setting Up Transmission Configurations.
Develop a settlement acknowledgement parser. No For gateway model payment systems, the acknowledgement parser may be identical to the authorization parser.
This task is not relevant for processors.
Develop a settlement query format template. No Query support is optional for gateway model payment systems.
For most gateway model payment systems, an acknowledgement request message is not defined.
This task is not relevant for processors.
Create XML Publisher templates using the elements of the funds capture extract.
For information on funds capture extract, see Funds Capture Extract.
Setup the settlement query format template. No Optional for gateway model payment systems.
Link the newly created XML Publisher template to the format.
This task is not relevant for processors.
Develop a settlement query transmission function. No Optional for gateway model payment systems.
This task is not relevant for processors.
Setup the settlement query transmission protocol. No Optional for gateway model payment systems.
This task is not relevant for processors.
Develop a settlement query acknowledgement parser. No Optional for gateway model payment systems.
This task is not relevant for processors.

The following note is relevant to the Batch Processing Infrastructure Tasks table shown below.

Note: Batch processing tasks are not relevant for gateways.

Batch Processing Infrastructure Tasks
Task Mandatory Description
Develop a settlement format template. Yes Define a payment system-specific settlement format message.
Create XML Publisher templates using the elements of the funds capture extract.
For information on funds capture extract, see Funds Capture Extract.
Setup the settlement format template. Yes Link the newly created XML Publisher template to the format.
For information on setting up formats, see Step 4. Setting Up Formats.
Develop a settlement transmission function. Yes Implement the transmission function to communicate with the payment system for settlements.
Setup the settlement transmission protocol. Yes Define a transmission protocol and associate it with the transmission function code-point that implements it. Also define the protocol parameters.
For information on setting up transmission configurations, see Step 6. Setting Up Transmission Configurations.
Develop a settlement acknowledgement parser. Yes Implement the settlement acknowledgement parser.
Setup the settlement acknowledgement parser. Yes Define the system data attributes for the acknowledgement parser.

The following note is relevant to the Batch Query Infrastructure Tasks table shown below.

Note: Batch query tasks are not relevant for gateways.

Batch Query Infrastructure Tasks
Task Mandatory Description
Develop a settlement query format template. No Define a payment system-specific query format message.
Create XML Publisher templates using the elements of the funds capture extract.
For information on funds capture extract, see Funds Capture Extract.
Setup the settlement query format template. No Link the newly created XML Publisher template to the format.
For information on setting up formats, see Step 4. Setting Up Formats.
Develop a settlement query transmission function. No Implement the transmission function to communicate with the payment system for queries.
Setup the settlement query transmission protocol. No Define a transmission protocol and associate it with the transmission function code-point that implements it. Also define the protocol parameters.
For information on setting up transmission configurations, see Step 6. Setting Up Transmission Configurations.
Develop a settlement query acknowledgement parser. No Implement the query acknowledgement parser.
Setup the settlement query acknowledgement parser. No Define the system data attributes for the acknowledgement parser.

Developing a Custom Payment System Integration for Funds Disbursement

Unlike funds capture, funds disbursement integrations are always offline using payment files. There is no concept of online/real-time transaction processing in the funds disbursement flow.

In the funds disbursement flow, your implementation will typically involve the creation of a payment file using data from a payment instruction (also known as a payment batch). The payment file is created in a payment system-specific format, and this file is transferred to the payment system, usually via FTP.

In case the payment system supports query functionality, you will need to implement a query message and an acknowledgment parser.

Use the flowchart below to determine what tasks you need to perform for your custom integration.

Integration Task List for Funds Disbursement Payment Systems

the picture is described in the document text

Below is the Basic Setup Tasks table, which shows the tasks for integrating a custom payment system.

Basic Setup Tasks
Task Mandatory Description
Define the payment system. Yes Set up the new payment system.
Define payment system account options. No Set up the options for all accounts with the payment system.
Create payment process profile. Yes The payment process profiles define how payments are created and disbursed.
The profile controls the behavior of the funds disbursement operations.
Create document validations. No Implement business rules to validate documents payable.
You can validate individual attributes of the document, such as internal bank account, document payment amount, or payee bank account.
Create payment validations. No Implement business rules to validate payments.
You can validate individual attributes of the payment, such as payment amount or payment currency.
Create payment instruction validations. No Implement business rules to validate payment instructions.
You may validate the number of transactions in the payment instruction.
Seed validation assignments. No Link the validation sets to payment methods and payment formats.

The following note is relevant to the Batch Processing Infrastructure Tasks table shown below.

Note: Batch processing tasks are not relevant for gateways.

Batch Processing Infrastructure Tasks
Task Mandatory Description
Develop a settlement format template. Yes Define a payment system-specific settlement format message.
Create XML Publisher templates using the elements of the funds disbursement extract.
For information on funds disbursement extract, see Extract Structure Overview.
Setup the settlement format template. Yes Link the newly created XML Publisher template to the format.
For information on setting up formats, see Step 4. Setting Up Formats.
Develop a settlement transmission function. No Implement the transmission function to communicate with the payment system for settlements.
Configure the settlement transmission protocol. No Define a transmission protocol and associate it with the transmission function code-point that implements it. Also define the protocol parameters.
For information on setting up transmission configurations, see Step 6. Setting Up Transmission Configurations.
Develop a settlement acknowledgement parser. Yes Implement the settlement acknowledgement parser.
Setup the settlement acknowledgement parser. Yes Define the system data attributes for the acknowledgement parser.

Defining a Payment System

The first task in integrating any payment system is defining a payment system. The definition must include both the payment system's attributes as well as the account options, if any, defined for the payment system accounts the users will establish.

Payment System Attributes

The table lists key attributes of the payment system.

Key Attributes of the Payment System
Attribute Description Constraints
Payment System The name of the payment system. Required.
Supported Instruments The instrument types supported by the payment system. Must be one of the following instrument types:

  • Credit Card

  • Purchase Card Level II/Level III

  • PINless debit card

  • Bank Account
Type Payment system model type. See Understanding Gateway-Model and Processor-Model Payment Systems for a discussion of the differences between the processor and gateway payment system models. Must be processor or gateway model payment system.
Suffix Unique three-letter identifier for the payment system. Must not be any of the following reserved suffixes seeded in Oracle Payments:

  • lop (sample gateway system)

  • efs (Concord EFSnet)

  • ptk (Paymentech)

  • fdb (FDC North)
Servlet Base URL The URL of the payment system servlet. Must be an URL in this form: http://<host>:<post>/<servlet zone>

All of these attributes can be set in the Create/Update Payment System page.

Related Topics

For information on setting up payment systems, see Step 6. Setting Up Payment Systems.

Account Options

Account options are attributes defined by the payment system for its user accounts. First, you must define the parameters in the Payment System page. Then, you enter the actual values when you create a payment system account in the Payment System Account page. Account options are used for payment instruction file generation and are represented in the funds capture extract.

Note: To implement the custom payment system integrations, ensure that you document the values.

Related Topics

To enable payment system accounts, see Enabling Payment System Accounts.

Formats

A payment system uses different formats during transaction processing. For example, there may be one format for authorization and another for settlement batch. Before creating a format in Oracle Payments, a corresponding Oracle XML Publisher template entity must be available.

Developing a Format Template

The table below describes the Oracle XML Publisher template attributes fixed by Oracle Payments:

Oracle XML Publisher Template Attributes Fixed by Oracle Payments
Attribute Description Constraint
Data Definition The template's data definition determines the structure of the data to which the template is applied. Always equal to: IBY_FNDCPT_INSTRUCTION_1_0 for funds capture.
Always equal to: IBY_FD_INSTRUCTION_1_0 for funds disbursement.

For implementing the custom payment system integrations, a payment instruction template must be developed for XML Publisher using one of the supported XML Publisher template types such as eText (RTF) or XSL. You will need to seed your XML Publisher template and link your format to the seeded template.

Setting Up a Format Template

Once an Oracle XML Publisher template is created, the corresponding formats entity must be created in Oracle Payments, using the Create Format page.

Extract Generator

The extract generator produces the payment file extract document, a superset of all data pertaining to the transaction. A format template is applied to the extract to produce a final payment file.

The payment file extract is an XML document whose structure conforms to an XML schema. The funds capture XML schema is defined in file $IBY_TOP/patch115/publisher/defs/IBY_FCI_1_0.xsd. The funds disbursement XML schema is defined in file $IBY_TOP/patch115/publisher/defs/IBY_PPIOUT_1_0.xsd.

The funds capture XML schema supports transactions for all funds capture instrument types, such as credit card, bank account, PINless debit card and all funds capture transaction operation types, such as authorization, online settlement, and settlement batch.

The funds disbursement XML schema contains all disbursement-related payment information, including payment instruction information, a payment process profile, a payment format, and constituent payments.

For implementing the custom payment system integrations, the structure of the extract must be thoroughly understood to create the payment instruction file templates.

Extract Formatter

The extract formatter takes the extract document produced by the extract generator and applies a format template to produce the final payment file. Oracle Payments uses the Oracle E-Business Suite application Oracle XML Publisher (XDO) as its formatting engine.

For implementing the custom payment system integrations, templates must be created for every transaction operation type supported by the payment system. If the integration model for the payment system does not conform to one of formatted payment file delivery, you can use a ordinary formatting template that produces the unchanged extract documents as its output, deliver the extract to a servlet using HTTP, and then extract document to the payment system's native payment request mechanism in the servlet map. An ordinary template is already seeded by Oracle Payments with a template code IBY_IDENTITY. IBY_IDENTITY is a special case of a template that does no formatting and, instead, returns the extract as is.

Transmission Functions

The transmission function is responsible for delivering the payment file to the payment system and implements a particular transmission protocol.

For implementing the custom payment system integrations, transmission function code-points must be created for each transmission protocol for communicating with the payment system.

One component of a payment system specification is the transmission protocol used to deliver payment files to the payment system. A transmission protocol has transmission parameters associated with it that define the required system data when making a communication attempt. A transmission protocol also has a defined transmission function code-point, which is a self-contained unit of code implementing the protocol and conforming to the interface: oracle.apps.iby.net.TransmitFunction.

Developing a Transmission Function

A transmission protocol is implemented through a Java class which must implement the interface oracle.apps.iby.net.TransmitFunction. To implement the interface, the class must define function transmit.

The table explains the signature of the function:

Argument Type Type Description
params java.util.Dictionary The map of protocol parameter names and values representing the transmission configuration. The names are taken from the parameter name definitions for the protocol.
payload iava.io.InputStream The message payload being delivered.
<return> java.io.InputStream The response to the transmission; maybe null.

On implementing the protocol in function transmit, the function should handle any system exception that occurs by the exception of type oracle.apps.iby.exception.PSException such as:

throw new PSException(PSException.COMMUNICATION_ERROR);

If a mandatory transmission protocol parameter is not set, an exception using the same class type should be thrown such as:

throw new PSException(PSException.CODEPOINT_ARG_ERR,

PSException.CODEPOINT_ARG_ERR_TOKEN_ARG,

      <parameter code>);

Because the transmission function is invoked through Java reflection APIs, special action must be taken to preserve any exceptions generated by the transmission function; or else the Oracle Payments engine only sees a generic java.lang.reflect.InvocationTargetException when the function fails. To preserve the original exception for the engine to display, the following function should be called:

oracle.apps.iby.engine.CodePoint.storeException()

Setting Up a Transmission Protocol

When configuring a payment system account for the payment system in the user interface, you will automatically see all transmission protocol parameters defined for the payment system's system payment profile.

The table lists the attributes of a transmission protocol:

Attributes of a Transmission Protocol
Attribute Name Description Constraint
TRANSMIT_PROTOCOL_CODE The unique identifier for the protocol. Must be unique and less than or equal to 30 characters.
TRANSMIT_PROTOCOL_NAME The description of the protocol.  
TRANSMIT_CODE_LANGUAGE The language in which the transmission function code-point for the protocol is implemented. Must be JAVA.
TRANSMIT_CODE_PACKAGE The code-point package. The fully-qualified class name of the transmission function code-point. A fully qualified class name.
TRANSMIT_CODE_ENTRY_POINT The code-point entry-point: the programming language function name that is called. Must equal: transmit.

The table defines the attributes of a transmission protocol's parameters, sub-entities of the protocol.

Attributes of a Transmission Protocol's Parameters
Attribute Name Description Constraints
TRANSMIT_PARAMETER_CODE The identifier for the parameter. Must be unique and less than or equal to 30 characters among all parameters defined for the protocol.
TRANSMIT_PARAMETER_TYPE The datatype of the parameter. Supported values are:

  • VARCHAR2

  • NUMBER
MANDATORY_FLAG Whether the parameter is mandatory; used for user interface validation during transmission configuration. Possible values:

  • Y (Yes)

  • N (No)
TRANSMIT_PROTOCOL_CODE The protocol to which this parameter belongs.  
TRANSMIT_PARAMETER_NAME The name of the parameter.  

A transmission protocol and its parameters can be seeded in Oracle Payments by creating a SQL script to insert them.

Note: Insert all but translatable protocol attribute TRANSMIT_PROTOCOL_NAME name into tables IBY_TRANSMIT_PROTOCOLS_B. Insert the translatable attribute TRANSMIT_PROTOCOL_NAME into IBY_TRANSMIT_PROTOCOLS_TL and call the procedure IBY_PP_MLSUTL_PVT.TRANS_PROT_ADD_LANGUAGE.

Insert all but translatable protocol parameter attribute TRANSMIT_PARAMETER_NAME name into tables IBY_TRANSMIT_PARAMETERS_B. Insert the translatable attribute TRANSMIT_PARAMETER_NAME into IBY_TRANSMIT_PARAMETERS_TL and call the procedure IBY_PP_MLSUTL_PVT. TRANS_PARAM_ADD_LANGUAGE.

Acknowledgment Parser

A payment system sends an acknowledgement upon receiving a funds capture instruction delivery. The task of the acknowledgment parser is to parse the response understandable to Oracle Payments.

For implementing the custom payment system integrations, acknowledgement parsers must be created for every transmission function. If the payment system does not support acknowledgement for a protocol, a default acknowledgement parser must still be created which returns default or trivial values.

Acknowledgement parsers are self-contained code-points that parse responses from the payment system into a form that can be processed by the Oracle Payments engine.

Seeding an Acknowledgement Parser

The table defines the attributes when seeding an acknowledgement parser:

Attributes when Seeding an Acknowledgement Parser
Attribute Name Description Constraint
ACK_READER_CODE The unique identifier for the parser. Must be unique and less than or equal to 30 characters.
READER_CODE_LANGUAGE The language that the transmission function code-point for the parser is implemented. Must be Java.
READER_CODE_PACKAGE The code-point package- the fully-qualified class name of the acknowledgement parser code-point. A fully qualified class name.
READER_CODE_ENTRY_POINT The code-point entry-point: the programming language function name that is called. The method name must be parse.

After the attributes for an acknowledgement parser are defined, they can be seeded in Oracle Payments by creating a SQL script to insert them into the table IBY_ACK_READERS.

For implementing the custom payment system integrations, the Java class implementing an acknowledgment parser must be distributed to the user and then place it in the CLASSPATH of the application server hosting the Oracle Payments engine.

Developing an Acknowledgement Parser

All acknowledgement parsers must sub-class the interface: oracle.apps.iby.bep.ACKParser. The interface has a single function, parse, with these interface:

Argument Name Type Description
ackFile java.io.InputStream The acknowledgment message or file.
hints java.util.Dictionary Collection of name-values providing information about the transaction the acknowledgement is for. For example, the instrument type used, or credit card issuer.
<return> bep.ACK A corresponding object for the acknowledgment.

The hints argument to the acknowledgement parser is a collection of name-value pairs providing information about the transaction the response was created for.

The table below lists the possible values in this collection:

Possible Values in a Collection of Name-Value Pairs
Hint Key Description Value
ACKParser.CARD_ISSUER_HINT The card issuer; for acknowledgments where the structure of the response varies based upon the card issuer. One of the following card issuer codes:

  • AMEX

  • DINERS

  • DISCOVER

  • ENROUTE

  • JCB

  • MASTERCARD

  • UNKNOWN

  • VISA
ACKParser.INSTR_TYPE_HINT The transaction instrument type. One of the following values:

  • BANKACCOUNT

  • CREDITCARD

  • PINLESSDEBITCARD

  • PURCHASECARD
ACKParser.TRXN_TYPE_ID_HINT The type of transaction. One of the following values:

  • 2 (Auth only)

  • 3 (Auth capture)

  • 5 (Return)

  • 8/9 (Capture/Settlement)

  • 11 (Credit)

    Value data-source is IBY_TRXN_SUMMARIES_ALL.TRXNTYPEID

Note: The hints are populated only for certain transaction types. For example, the hints will be not be populated for a batch close operation.

The result of an acknowledgement parser returns is an object derived from class: oracle.apps.iby.bep.ACKParser. This class is a record intended to hold various response fields mapped from the payment system response.

ACK

The abstract class oracle.apps.iby.bep.ACK defines the most basic acknowledgement attributes inherited by all sub-classes. The table describes the structure of this class and all derived sub-classes.

Note: Implicity, for each attribute listed for a particular class there exists get<AttributeName> and set<AttributeName> functions for accessing the attributes. The get<AttributeName> returns an object of the attribute's type and the set<AttributeName> takes an object of the attribute's type as its single argument.

Attribute Name Type Description
BEPErrorCode String Payment system error code.
BEPErrorMessage String Payment system error message.

TrxnACK

The abstract class oracle.apps.iby.bep.TrxnACK defines common attributes for transaction acknowledgements. It is a subclass of oracle.apps.iby.bep.ACK and hence inherits its attributes as well.

Attribute Name Type Description
OrderId String Order identifier for this transaction.
TrxnStatus int Status of the transaction. The possible values are:

  • 0 (Success)

  • 1 (Communication error)

  • 2 (Duplicate order id)

  • 3 (Duplicate batch id)

  • 4 (Required field missing)

  • 5 (Payment system error)

  • 8 (Operation not supported)

  • 11 (Pending)

  • 20 (Declined)
TrxnDate java.util.Date Date the transaction was completed.
TrxnReqType String Transaction request type. The possible values are:

  • ORAPMTCAPTURE (Capture/Settlement)

  • ORAPMTCLOSEBATCH (Batch close)

  • ORAPMTCREDIT (Credit)

  • ORAPMTREQ (Authorization/Auth Capture/Verification/Debit)

  • ORAPMTRETURN (Return)

  • ORAPMTVOID (Void)
ExtensiblitySet oracle.apps.iby.util.NameValuePair[ ] The collection of extensibility name-value pairs.

Attribute ExtensiblitySet is typed as an array of oracle.apps.iby.util.NameValuePair objects and may be optionally set by the parser if the payment system acknowledgement contains important data that do not correspond to any of the attributes in an appropriate acknowledgements object. Any name values returned by the ExtensiblitySet attributed are stored in table IBY_TRXN_EXTENSIBILITY and are included in the extract document of any follow on transaction using the series of Extend sub-elements which may appear beneath the OriginalCCTransaction or OriginalDCTransaction elements.

The table below explains the attributes of the oracle.apps.iby.util.NameValuePair class.

Attribute Name Type Description
Name String Name/key.
Value String Value.

CreditCardTrxnACK

The class oracle.apps.iby.bep.CreditCardTrxnACK holds acknowledgment information for a single credit card transaction. The table lists the attributes (not including ones derived from its parent class oracle.apps.iby.bep.TrxnACK).

Attribute Name Type Description
AuthCode String Authorization code.
AVSResponse String Address verification system response from the payment system.
SecurityCodeCheck String Payment system response for the credit card security code (CVV2) check.
RefCode String Reference code.

BankAccountTrxnACK

The class oracle.apps.iby.bep.BankAccountTrxnACK holds acknowledgment information for a single bank account transaction. The table below lists the attributes (including inherited ones from oracle.apps.iby.bep.TrxnACK).

Attribute Name Type Description
RefCode String Bank reference code.
TrxnAmount oracle.apps.iby.ecapp.Price Actual amount of the transfer.
PostDate java.util.Date Date funds will be posted.
FundsCommitted Boolean Indicates whether funds were committed.

BatchACK

The abstract class oracle.apps.iby.bep.BatchACK defines common attributes of batch acknowledgments. The table below list the attributes, in addition to those inherited from class oracle.apps.iby.bep.ACK.

Attribute Name Type Description
BatchId String Identifier of the batch.
BatchStatus int Status of the batch. The possible values are:

  • 0 (Success)

  • 1 (Communication error)

  • 3 (Duplicate batch id)

  • 5 (Payment system error)

  • 11 (Pending)
BatchDate java.util.Date Date of batch submission.
TrxnACKs bep.TrxnACK[ ] Collection of acknowledgments for the individual transactions in this batch.
TrxnACKType String Enumerated value indicating transaction acknowledgments. The values are:

  • BatchACK.TRXN_ACK_ALL (All transactions in the batch have an acknowledgement)

  • BatchACK.TRXN_ACK_POSITIVE (All transactions missing an acknowledgement assumed failed)

  • BatchACK.TRXN_ACK_NEGATIVE (All transactions missing an acknowledgement assumed successful)

Note: All batch statuses except pending (11) are final. In case a batch acknowledgement does not exist, for example immediately after a batch close, or during a batch query which occurs before the batch has been processed, a batch acknowledgement object with batch status 0 should be created although there is no existing acknowledgement file.

CreditCardBatchACK

The class oracle.apps.iby.bep.CreditCardBatchACK extends oracle.apps.iby.bep.BatchACK and contains attributes for credit card batch acknowledgments. The table below explains the attributes.

Attribute Name Type Description
AuthTotal oracle.apps.iby.ecapp.Price Total authorizations completed.
CaptureTotal oracle.apps.iby.ecapp.Price Total settlements completed.
CreditTotal oracle.apps.iby.ecapp.Price Total credits completed.

BankAccountBatchACK

The class oracle.apps.iby.bep.BankAccountBatchACK extends oracle.apps.iby.bep.BatchACK and contains attributes for credit card batch acknowledgments. The table below describes the attributes.

Attribute Name Type Description
CreditTotal ecapp.Price Total credits completed.
DebitTotal ecapp.Price Total debits completed.

Creating Custom Disbursement Validation Sets

Validation sets are pieces of code that are executed at various processing points by the Build Payments program. Each validation set applies a set of business rules and determines whether the payment entity in consideration passes all the rules or not. Unless all rules are passed, the validation set returns a failure status to the Build Payments Program.

Validation Set Level

Before you create a validation set, you must determine at what level the validation applies. The validation set level, also known as the validation point determines the entity that needs to be validated. The three validation levels are as follows:

Validation Code Entry Point

The Build Payments program dynamically invokes the validation set linked to a particular entity. The validation set entry point is seeded in the IBY_VALIDATION_SETS_VL view. The important columns pertaining to validation code entry point are listed in the table below, which stores seeded validation sets.

IBY_VALIDATION_SETS_VL
Column Name Example Meaning
VALIDATION_SET_CODE PT_CHECK_GEN Unique name of the validation set used for querying.
VALIDATION_LEVEL_CODE DOCUMENT This validation is applicable to documents payable (invoices).
VALIDATION_CODE_PACKAGE IBY_VALIDATIONSETS_CALLS_PUB This validation set is stored in this package.
VALIDATION_CODE_ENTRY_POINT PT_CHECK_GEN This validation set has this method name.
VALIDATION_CODE_LANGUAGE PL/SQL This validation set is implemented in PL/SQL.

For the same validation set data shown in the table above, the Build Payments program invokes the PL/SQL validation set IBY_VALIDATIONSETS_CALLS_PUB. PT_CHECK_GEN dynamically to validate a document payable.

Note: You should create the custom validation set in a custom package. You should not add your custom validation sets into the IBY_VALIDATIONSETS_CALLS_PUB package, since this package is meant for Oracle Payments only.

Linking a Validation Set To a Payment Entity

Typically, validation sets are linked to one of two payment entities as follows:

Validation sets linked to the payment method can also be applied online, such as validating the invoice in Oracle Payables at the time of invoice creation. Online validations do not fail the document, but present the user with warning messages before submitting the document to Oracle Payments. This provides you with the ability to correct errors before the document is submitted to Oracle Payments in the document validation cycle. When online validations are performed on an invoice, it is put on hold if there are validation errors. The errors generated during online validation are shown as hold reasons, and the selection program will not pick up the invoice until the hold reasons are corrected. Validation sets linked to payment methods are re-applied when the documents payable are submitted to Oracle Payments.

The vast majority of seeded validation sets are linked to formats. The link between validation sets and payment methods/formats is stored in the IBY_VAL_ASSIGNMENTS table, which stores the link between a validation set and a payment entity.

IBY_VAL_ASSIGNMENTS
Column Name Example Meaning
VALIDATION_SET_CODE PT_CHECK_GEN Unique name of the validation set used for querying.
VAL_ASSIGNMENT_ENTITY_TYPE FORMAT Type of payment entity to which this validation set is linked. This will be FORMAT or METHOD.
ASSIGNMENT_ENTITY_ID IBY_PAY_CHK_PT The actual entity to which this validation set is linked. In this example, the entity is the format IBY_PAY_CHK_PT.
TERRITORY_CODE PT If null, this validation set is applicable, regardless of the payment country. If not null, this validation is applicable only to the specified country.

The preceding table shows that the validation set PT_CHECK_GEN is linked to the payment format IBY_PAY_CHK_PT. Since the validation set PT_CHECK_GEN is applicable at the document level, the Build Payments program executes this validation whenever a document payable comes in with the format IBY_PAY_CHK_PT.

Validation Set Signature

All validation sets contain the same five-argument signature. The third parameter is the payment entity to be validated. It can be a document payable, a payment, or a payment instruction, depending on the validation level for which you have coded your validation.

Document Level Validation Set

Document-level validations will be implemented in PL/SQL and must have the following signature:

Name Data Type Type Description
p_validation_assign_id NUMBER IN The validation assignment id. This value is from IBY_VAL_ASSIGNMENTS validation_assignment_id.
p_validation_set_code VARCHAR2 IN The validation set that needs to be invoked. This value is from IBY_VALIDATION_SETS_VL validation_set_code.
p_document_id NUMBER IN Unique id of the document to be validated. This value is from IBY_DOCS_PAYABLE_ALL document_payable_id.
p_is_online_val VARCHAR2 IN Y/N flag indicating whether this is an online validation call.
x_result NUMBER OUT Numeric value indicating the result of the applied validations. Zero (0) indicates that all validations were successful; 1 indicates that at least one validation failed. 
PROCEDURE MY_VALIDATION_SET(
    p_validation_assign_id  IN          
        IBY_VAL_ASSIGNMENTS.
            validation_assignment_id%TYPE,
    p_validation_set_code   IN   
        IBY_VALIDATION_SETS_VL.
            validation_set_code%TYPE,
    p_document_id           IN 
        IBY_DOCS_PAYABLE_ALL.
            document_payable_id%TYPE,
    p_is_online_val         IN VARCHAR2,
    x_result                OUT NOCOPY NUMBER
    );

The preceding example shows a validation set called MY_VALIDATION_SET that is applicable at the document level. When you create your document level validation, you need to use the same signature.

Payment Level Validation Set

Payment level validations will be implemented in PL/SQL and must have the following signature:

Name Data Type Type Description
p_validation_assign_id NUMBER IN The validation assignment id. This value is from IBY_VAL_ASSIGNMENTS validation_assignment_id.
p_validation_set_code VARCHAR2 IN The validation set that needs to be invoked. This value is from IBY_VALIDATION_SETS_VL validation_set_code.
p_payment_id NUMBER IN Unique id of the document to be validated. This value is from IBY_PAYMENTS_ALL payment_id.
p_is_online_val VARCHAR2 IN Y/N flag indicating whether this is an online validation call.
x_result NUMBER OUT Numeric value indicating the result of the applied validations. Zero (0) indicates that all validations were successful; 1 indicates that at least one validation failed. 
PROCEDURE MY_VALIDATION_SET(
    p_validation_assign_id  IN          
        IBY_VAL_ASSIGNMENTS.
            validation_assignment_id%TYPE,
    p_validation_set_code   IN   
        IBY_VALIDATION_SETS_VL.
            validation_set_code%TYPE,
    p_document_id           IN 
        IBY_DOCS_PAYABLE_ALL.
            document_payable_id%TYPE,
    p_is_online_val         IN VARCHAR2,
    x_result                OUT NOCOPY NUMBER
    );

The preceding example shows a validation set called MY_VALIDATION_SET that is applicable at the payment level. When you create your payment level validation set, you need to use the same signature.

Payment Instruction Level Validation Set

Payment instruction-level validations are implemented in PL/SQL and must have the following signature:

Name Data Type Type Description
p_validation_assign_id NUMBER IN The validation assignment id. This value is from IBY_VAL_ASSIGNMENTS validation_assignment_id.
p_validation_set_code VARCHAR2 IN The validation set that needs to be invoked. This value is from IBY_VALIDATION_SETS_VL validation_set_code.
p_instruction_id NUMBER IN Unique id of the payment instruction to be validated. This value is from IBY_PAY_INSTRUCTIONS_ALL payment_instruction_id.
p_is_online_val VARCHAR2 IN Y/N flag indicating whether this is an online validation call.
x_result NUMBER OUT Numeric value indicating the result of the applied validations. Zero (0) indicates that all validations were successful; 1 indicates that at least one validation failed. 
PROCEDURE MY_VALIDATION_SET(
    p_validation_assign_id  IN          
        IBY_VAL_ASSIGNMENTS.
            validation_assignment_id%TYPE,
    p_validation_set_code   IN   
        IBY_VALIDATION_SETS_VL.
            validation_set_code%TYPE,
    p_instruction_id           IN 
        IBY_PAY_INSTRUCTIONS_ALL.
            payment_instructionid%TYPE,
    p_is_online_val         IN VARCHAR2,
    x_result                OUT NOCOPY NUMBER
    );

The preceding example shows a validation set called MY_VALIDATION_SET that is applicable at the payment instruction level. When you create your payment instruction level validation set, you need to use the same signature.

Important Notes Regarding Validation Sets

Note: The p_is_online_val is only relevant for document level validation sets. It should be ignored when implementing payment and payment instruction level validation sets. When validating an invoice in Oracle Payables, either manually or via invoice interface import program, Payables invokes the validation sets attached to the payment method on the document. Oracle Payables invokes the validation set as an online validation to catch possible errors when the invoice is created. Therefore, Oracle Payables invokes the validation set with the p_is_online_val set to Y. This means that the validation error messages are displayed in the schedule payment of the invoice as warnings and the schedule payment is put on hold. This is applicable only to validations assigned to payment methods as it is known at invoice time and Oracle Cash Management validations attached to bank accounts.

Note: The x_result parameter is the return value of the validation set that is passed back to the Build Payments program. A value of zero (0) indicates the validation was successful. A value of 1 indicates the payment entity failed validation.

Storing Errors Generated by a Validation Set

The error messages generated by applying the business rules encapsulated within the validation set needs to be displayed to the user.

The IBY_TRANSACTION_ERRORS table shown below stores error messages generated by a validation set. Since you can have multiple error messages associated with the payment entity being validated, this table can contain multiple rows for a given payment entity id.

IBY_TRANSACTION_ERRORS
Column Name Example Meaning
TRANSACTION_ERROR_ID 21412 Unique sequence number for this error message.
TRANSACTION_TYPE DOCUMENT_PAYABLE Type of payment entity for which this error message has been generated. Possible values include DOCUMENT_PAYABLE, PAYMENT, and PAYMENT_INSTRUCTION.
TRANSACTION_ID 631 Actual payment entity to which this error message is linked. In this example, the entity is a document payable with id 631.
ERROR_CODE IBY_DOC_INVALID_PROFILE This error code is used to retrieve a seeded FND error message.
VALIDATION_SET_CODE CORE_DOC_VALIDATION The validation set that generated this message.

Implementing a Document Level Validation Set

A document level validation set needs to follow the following process:

  1. Retrieve all attributes of the provided document. The document id is provided as an input parameter to document level validation sets.

  2. Create an error record for inserting into the IBY_TRANSACTION_ERRORS table.

  3. Apply business rule using the relevant document attributes.

  4. If the document has failed validation, populate an error record to reflect that.

  5. Repeat Steps 3 and 4 until all business rules are applied.

  6. If all validations have been successfully passed, return 0.

  7. If any validation has failed, insert the error records into the IBY_TRANSACTION_ERRORS table and return 1.

Helper Functions

IBY has implemented a number of helper functions for some of the preceding steps. You can use these functions to shorten your coding time.

Implementing a Payment Level Validation Set

A payment level validation set needs to follow the following process:

  1. Retrieve all attributes of the provided document. The document id is provided as an input parameter to payment level validation sets.

  2. Create an error record for inserting into the IBY_TRANSACTION_ERRORS table.

  3. Apply business rule using the relevant payment attributes.

  4. If the document has failed validation, populate an error record to reflect that.

  5. Repeat Steps 3 and 4 until all business rules are applied.

  6. If all validations have been successfully passed, return 0.

  7. If any validation has failed, insert the error records into the IBY_TRANSACTION_ERRORS table and return 1.

Helper Functions

Oracle Payments has implemented a number of helper functions for some of the preceding steps. You can use these helper functions to shorten your coding time.

Implementing a Payment Instruction Level Validation Set

A payment instruction level validation set needs to follow the following process:

  1. Retrieve all attributes of the provided payment instruction. The payment id is provided as an input parameter to payment instruction level validation sets.

  2. Create an error record for inserting into the IBY_TRANSACTION_ERRORS table.

  3. Apply business rule using the relevant payment instruction attributes.

  4. If the payment has failed validation, populate the error record and insert it into memory.

  5. Repeat Steps 3 and 4 until all business rules are applied.

  6. If all validations have been successfully passed, return 0.

  7. If any validation has failed, insert the error records in memory into the IBY_TRANSACTION_ERRORS table and return 1.

Helper Functions

Oracle Payments has implemented a number of helper functions for some of the preceding steps. You can use these helper functions to shorten your coding time.

Implementing Custom Validation Logic

As much as possible, use the method IBY_VALIDATIONSETS_PUB.evaluateCondition for all your basic validations. By passing the appropriate token value to this method, you can cover most of the common validation conditions, such as checking if a field is null or not null and verifying that an amount value is less than or greater than a specified limit.

In case the validation required is complex and cannot be implemented using the normal token operators, then use the special token CUSTOM in the call to evaluateCondition. When the CUSTOM token is used, the evaluateCondition dynamically invokes a specified validation method. The method to be invoked should be passed as an argument to evaluateCondition.

Example

The following is an example of invoking evaluateCondition with a CUSTOM token.

IBY_VALIDATIONSETS_PUB.evaluateCondition
(
'PAYEE_BANK_SWIFT_CODE',
l_payee_bank_swift_code,
'CUSTOM',   /* token (operator) is 'CUSTOM' */
'DFPML.VAL_SWFT_CD', /* custom method to be invoked */
null, 
l_valResult, 
l_docErrorRec
);

The field name and field value parameters to evaluateCondition will be passed to your custom validation method. These are the first two arguments to the evaluateCondition method. The custom validation method should specify the success or failure of the validation using the third parameter which is an out parameter. If the out parameter is 0, it means that the custom validation was a success (failure otherwise).

Your custom validation method should follow this signature:

PROCEDURE <custom validation name>(
    p_fieldName VARCHAR2,
    p_fieldValue VARCHAR2,
    l_chr OUT NOCOPY VARCHAR2
    );

For example, your custom validation method could look like:

PROCEDURE VAL_SWFT_CD(
    p_fieldName VARCHAR2,
    p_fieldValue VARCHAR2,
    l_chr OUT NOCOPY VARCHAR2
    ) 
IS
BEGIN
    /*
     * Do some validations here on the field value.
     */

    :
    :
   
    /*
     * Return '0' if everything is Ok. Else
     * return '1'.
     */
    l_chr := '0'; /* success */
END VAL_SWFT_CD;

Example Code

For examples of how validation sets are implemented, note the following files:

$IBY_TOP/patch/115/sql/ibyvalcs.pls 
$IBY_TOP/patch/115/sql/ibyvalcb.pls

The above two files are the PL/SQL specification and body for the validation sets seeded by Oracle Payments. The body contains validation sets at document, payment and payment instruction levels. You are encouraged to reuse as much of the code as possible.

Seed Your Validation Sets

After you create a validation set, remember to seed your validation set in the IBY_VALIDATION_SETS_VL table.

You cannot directly insert your newly created validation set into IBY_VALIDATION_SETS_VL because it is a view. You need to perform the insert using the following steps:

  1. Insert your validation set into the IBY_VALIDATION_SETS_B table. This is the base table that does not contain any translatable text.

    Example:

    insert into iby_validation_sets_b (validation_set_code,validation_level_code,validation_code_package,validation_code_entry_point,validation_code_language,created_by,creation_date,last_updated_by,last_update_date,last_update_login, object_version_number) values 
('paymul_pmt_validations','PAYMENT','mis_iby_val_pkg','mis_iby_gen_val_pmt_pml','plsql','294110',sysdate,'294110',sysdate,'294110',1);

  2. Insert your validation set into the IBY_VALIDATION_SETS_TL table. This table contains translatable text. The validation set name is translatable.

    Example:

    insert into iby_validation_sets_tl (validation_set_code,language,source_lang,validation_set_display_name,created_by,creation_date,last_updated_by,last_update_date,last_update_login,object_version_number) values 
('paymul_pmt_validations','us','us','paymul eft validation-payment level','294110',sysdate,'294110',sysdate,'294110',1);

Now your validation sets will be visible in the Oracle Payments Setup page. The navigation path is Oracle Payments Setup > Payments Setup > Shared Setup > Validations.

You can link your validation set to appropriate payment entities like payment methods and payment formats. After this point, you should be able to test your validation logic by running the Build Payments Program.

Important Notes for Validation Set Implementers

The following are important notes for validation set implementers:

Your validation set should also contain the following two calls.

/*   
 * Inserts the error generated by a single 
 * validation within the validation set into 
 * the l_docErrorTab temporary PLSQL table.  
 *
 * Similarly, you can have l_pmtErrorTab
 * for payments.
 *
 * This call should be invoked once after each 
 * validation to accumulate all the error
 * messages in l_docErrorTab.
 */
IBY_VALIDATIONSETS_PUB.insertIntoErrorTable(l_docErrorRec, l_docErrorTab);

/*
 * Permanently inserts all the error messages 
 * in l_docErrorTab into the
 * IBY_TRANSACTION_ERRORS table.
 *
 * This call should be invoked only once at 
 * the end of your validation set.
 */
IBY_VALIDATIONSETS_PUB.insert_transaction_errors(p_is_online_val,l_docErrorTab);

Creating Custom Funds Capture Validation Sets

A validation set is a program unit which performs a set of validations against a payment processing entity, typically a fund capture order (payment transaction) or a payment batch. Each validation sets applies a set of business rules and determines whether the payment entity in consideration passes all the rules or not. Funds capture validation sets can be implemented as Java functions or PL/SQL procedures. They are invoked dynamically by the payments engine.

Validation Set Level

Before you create a validation set, you must determine at what level the validation applies. The validation set level, also known as the validation point, determines the entity that needs to be validated. The two validation levels are as follows:

Order level validations are transaction level validations. Instruction level validations are batch level validations. Order level validations are implemented in Java and instruction level validations are implemented in PL/SQL.

Validation Code Entry Point

The payments engine dynamically invokes the validation set linked to a particular entity. The validation set entry point is seeded in the IBY_VALIDATION_SETS_VL view. Columns that are concerned with the validation code entry point are listed in the table below. The IBY_VALIDATION_SETS_VL table stores seeded validation sets.

IBY_VALIDATION_SETS_VL
Column Name Example Meaning
VALIDATION_SET_CODE PTK_ONLINE_7_2_BATCH_2_1_0 Unique name of the validation set used for querying.
VALIDATION_LEVEL_CODE ORDER This validation is applicable to orders (transactions).
VALIDATION_CODE_PACKAGE oracle.apps.iby.bep.proc.paymentech.FundsCaptureValidationSet This validation set is implemented in this Java class.
VALIDATION_CODE_ENTRY_POINT validate This validation set has this function name.
VALIDATION_CODE_LANGUAGE JAVA This validation set is implemented in Java.

For the same validation set data shown in the table above, the payments engine invokes the Java validation set oracle.apps.iby.bep.proc.paymentech.FundsCaptureValidationSet. validate dynamically to validate a transaction

Note: You can create the validation set in your own class. You should not add your custom validation sets in the oracle.apps.iby.bep.proc.paymentech.FundsCaptureValidationSet. class. This class is meant for Oracle Payments only.

The IBY_VALIDATION_SETS_VL table below, which stores seeded validation sets, illustrates a seeded validation set entry point for a PL/SQL validation.

IBY_VALIDATION_SETS_VL
Column Name Example Meaning
VALIDATION_LEVEL_CODE PTK_BATCH_2_1_0 Unique name of the validation set used for querying.
VALIDATION_LEVEL_CODE INSTRUCTION This validation is applicable to instructions (payment batches).
VALIDATION_CODE_PACKAGE IBY_FNDCPT_VLD_PUB This validation set is implemented in this PL/SQL package.
VALIDATION_CODE_ENTRY_POINT Validate_Paymentech_Batch This validation set has this procedure name.
VALIDATION_CODE_LANGUAGE PL/SQL This validation set is implemented in PL/SQL.

For the same validation set data shown in the preceding table, the payments engine invokes the PL/SQL validation set IBY_FNDCPT_VLD_PUB.Validate_Paymentech_Batch dynamically to validate a payment instruction (payment batch).

Linking a Validation Set To a Payment Entity

Funds capture validation sets are linked to only one payment entity as follows:

The linkages between the validation sets and payment entities are stored in the IBY_VAL_ASSIGNMENTS table shown below.

IBY_VAL_ASSIGNMENTS
Column Name Example Meaning
VALIDATION_SET_CODE PTK_ONLINE_7_2_BATCH_2_1_0 Unique name of the validation set used for querying.
VAL_ASSIGNMENT_ENTITY_TYPE FORMAT Type of payment entity to which this validation set is linked. This will always be FORMAT for funds capture validation sets.
ASSIGNMENT_ENTITY_ID PTECH_ONLINE_7_2 Actual entity to which this validation set is linked. In this example, the entity is the format PTECH_ONLINE_7_2.
TERRITORY_CODE null If null, this validation set is applicable, regardless of the payment country. If not null, this validation is applicable only to the specified country.

The preceding example from the IBY_VAL_ASSIGNMENTS table shows that the validation set PTK_ONLINE_7_2_BATCH_2_1_0 is linked to the payment format PTECH_ONLINE_7_2. Since the validation set PTK_ONLINE_7_2_BATCH_2_1_0 is applicable at the order level, the payments engine executes this validation whenever a transaction comes in with the format PTECH_ONLINE_7_2.

Validation Set Signature

Payment system format-specific validations are performed within the payments engine by validation set code-points implemented in Java and PL/SQL and then associated with particular payment system formats.

Transaction Level Validation Set

Transaction level Java validation set implementations must conform to the following class interface:

oracle.apps.iby.payment.FndCptValidationSet.

This interface class has a single method called validate with the signature shown in the table below.

Method Parameters
Name Type Description
ecappId int Electronic commerce application id for the current transaction.
payee Payee Transaction payee.
pmtInstr PmtInstr Payment instrument used.
p_is_online_val IN Y/N flag indicating whether this is an online validation call.
order Tangible Order.
trxn Transaction The transaction performed.
<return> ValidationSetResult Results of the validation.

The validate method returns the result of the validation via the ValidationSetResult object. The ValidationSetResult object contains the following elements:

ValidationSetResult Elements
Name Type Description
Valid boolean Results of the validation. If passed then true, otherwise false.
Message String An encoded Oracle Payments error message string of the form: MESSAGE_NAME#TOKEN_NAME1=TOKEN_VAL1#….
Code String Error code for the validation, if any.

Batch Level Validation Set

Batch level validations are implemented in PL/SQL and must have the following signature:

Batch Level Validation Set Signature
Name Data Type Type Description
p_api_version NUMBER IN Version of the API called; should be ignored.
p_init_msg_list VARCHAR2 IN Whether to initialize the message list.
p_mbatchid NUMBER IN The identifier of the batch (in table IBY_BATCHES_ALL).
x_return_status VARCHAR2 OUT Status of the call.
x_msg_count NUMBER OUT Number of error messages on the stack.
x_msg_data VARCHAR2 OUT Message stack of errors.

Implementing a Transaction Level Validation Set

A transaction level validation set needs to follow the following process:

  1. Your validation set should be coded in a class that implements the oracle.apps.iby.payment.FndCptValidationSet interface. That is, your validation set class must contain the validate method.

  2. The validate method is invoked with input parameters that encapsulate the payee, payment instrument, tangible, and transaction attributes. Apply business rule on the relevant attributes.

  3. If any attribute has failed validation, populate the oracle.apps.iby.engine.ValidationSetResult object with the error code and error message and return.

  4. If all validations successfully pass, set the result code to SUCCESS in the ValidationSetResult object.

  5. The following payment system-specific implementations of the oracle.apps.iby.payment.FndCptValidationSet interfaces can be used for reference. Each is listed with its associated payment system format in the table below.

Seeded Payment System Validation Sets
Payment System-Specific Implementations of the payment.FndCptValidationSet Interfaces Associated Payment System Format
Paymentech Online and Batch Specifications oracle.apps.iby.bep.proc.paymentech.FundsCaptureValidationSet
First Data North Authorization and Batch Specifications oracle.apps.bep.proc.fdcnorth.FundsCaptureValidationSet

Implementing a Batch Level Validation Set

A batch level validation set needs to follow the following process:

  1. Implement your batch level validation set using the signature mentioned in section 2.1.5.2.

  2. The parameter mbatchid provided as an input parameter to the validation set, is the primary key to the IBY_BATCHES_ALL table. You can use this parameter to pull the details of the batch from the IBY_BATCHES_ALL table and also join to the IBY_TRXN_SUMMARIES_ALL table to pull the transaction details.

  3. Apply business rule on the relevant payment attributes.

  4. If any attribute fails validation, set the x_return_status output parameter to FND_API.G_RET_STS_ERROR. Populate the error message on the FND message stack and return.

  5. If all validations have been successfully passed, set x_return_status to FND_API.G_RET_STS_SUCCESS and return.

  6. For a reference implementation of batch level validations, you can look at the package IBY_FNDCPT_VLD_PUB ($IBY_TOP/patch/115/sql/ibypfcvb.pls). The method Validate_Paymentech_Batch is used for validating credit card batches sent to Paymentech. Similarly, the method Validate_FDCNorth_Batch is used for validating credit card batches sent to the FDC North payment system.

Seed Your Validation Sets

After you create a validation set, remember to seed your validation set in the IBY_VALIDATION_SETS_VL table.

You cannot directly insert your newly created validation set into IBY_VALIDATION_SETS_VL because it is a view. You need to perform the insert using the following steps:

  1. Insert your validation set into the IBY_VALIDATION_SETS_B table. This is the base table that does not contain any translatable text.

    Example:

    insert into iby_validation_sets_b (validation_set_code,validation_level_code,validation_code_package,validation_code_entry_point,validation_code_language,created_by,creation_date,last_updated_by,last_update_date,last_update_login, object_version_number) values 
('my_cc_validations','ORDER', 'oracle.apps.iby.bep.proc.myproc.FundsCaptureValidationSet,'validate','JAVA','294110',sysdate,'294110',sysdate,'294110',1);

  2. Insert your validation set into the IBY_VALIDATION_SETS_TL table. This table contains translatable text. The validation set name is translatable.

    Example:

    insert into iby_validation_sets_tl (validation_set_code,language,source_lang,validation_set_display_name,created_by,creation_date,last_updated_by,last_update_date,last_update_login,object_version_number) values 
('my_cc_validations','us','us','My credit card validatons','294110',sysdate,'294110',sysdate,'294110',1);

Now your validation sets will be visible in the Oracle Payments Setup page. The navigation path is Oracle Payments Setup > Payments Setup > Shared Setup > Validations.

You can link your validation set to appropriate payment entities like funds capture payment methods and formats.

Now you can test your validation logic by creating transactions and submitting batches.

Important Notes for Validation Set Implementers

The following are important notes for validation set implementers: