iPayment 11i: How to use iPayment Payment Processing API’s

Esteban Rodriguez
Oracle Corporation
Abstract different Back-end payment processors such as:
CyberCash, CheckFree, etc.
This paper explains how the iPayment Payment
Processing API's work and also describes and explains II. WHAT ARE THE PAYMENT PROCESSING
the steps needed to configure iPayment 11i to use the API’S?
Payment Processing API's. This document does not
cover the flow when integrating with CheckFree for The Payment Processing API's are transactional API's
Bank account transfers. that provide the support for each one of the electronic
commerce transactions. For example: Authorizations of
Scope Credit Cards, Capture, Cancel, Return and other
operations
I. What is iPayment?
II. What are the Payment Processing API’s? III. HOW DO THE MERCHANT PAYMENT
III. How do the Merchant Payment Processing PROCESSING API’S WORK?
API’s Work?
IV. How do the Back-end Payment Processing iPayment 11i is an engine that receives transaction
API’s work? requests from merchant applications and submits that
V. What is the Status Update API? transaction request to the Back End Payment Processor.
VI. What are the required configuration steps? When the response is received back from the Back End
VII. Conclusion Payment Processor, iPayment processes that response
and generates a new response that is returned to the
Please note that this paper does not replace your Merchant application.
iPayment 11i Implementation Guide. This paper is
intended to give you a deeper understanding of the In addition to the Payment Processing capabilities,
iPayment functionality , and also to provide the minimal iPayment provides additional API's/functionality for
steps needed to use these Payment Processing API's. Risk Control, Administration of Payment Instruments,
Credit Card Validation and Status Update for off-line
References payment processing.

For detailed information on all the iPayment features,

please read the following references. iPayment Payment Processing
API’s
Oracle iPayment 11i Concepts and Procedures Guide.
1.1

Oracle iPayment 11i Implementation Guide. Oracle

iStore
HTTP
3.3

3.10
ECServlet
3.4
iPayment
3.5

3.8
Payment
System
3.6

Listener Java API’s

1.4 Servlet 3.7

I. WHAT IS IPAYMENT? 1.2

3.2 APPS DB
3.9
Back End
Payment
iStore iPayment
Processor
3.11
Java PL/SQL API’s
iPayment 11i is an application that creates a standard Oracle
Servlets 1.3
PL/SQL
3.1

and API’s
interface to the Back-end payment processors (for Order
Management 2.1
Business API’s

iPayment/Apps Schema
example CyberCash, Checkfree) in such a way that a Procedure calls
HTTP Request
or Response

merchant is completely independent from the Back-end

payment processor in use. In addition iPayment 11i Figure 1 - Payment Processing API’s
provides support for SSL (Secure Socket Layer), and
provides capabilities for Risk-Management control There are several steps through which the transaction
through the use of rules. iPayment 11i also provides passes when using iPayment. See also Figure 1 for
integration with Oracle Applications 11i , allowing reference:
businesses to have payment processing across the
enterprise providing a single source of access to the

1
A. Submission of the transaction from the Merchant
Application to iPayment (See Figure 1 for flows 2.1
or 1.1-1.2-1.3, then 3.1-3.2-3.3)
B. Submission of the transaction from the iPayment
Engine to the Back End Payment Processor (See
figure 1 for flow 3.5)
C. Reception of the response generated by the Back
End Payment Processor (See figure 1 for flow 3.8)
D. Generation of the response that will be send back to
the Merchant Application. (See figure 1for flows
3.10-3.11)
Step A, the merchant application submits a transaction
request (Example: credit card authorization request) to
the iPayment engine. That transaction request is
accomplished by using the Payment Processing API's
for Electronic Commerce Applications provided by
iPayment. iPayment 11i provides two types of Payment
Processing API's:
a) PL/SQL API's
b) Java API's
The PL/SQL API's in iPayment are implemented in the
"IBY_PAYMENT_ADAPTER_PUB" package. This
package (some times referred as PMT_UTIL) provides
procedures to implement each one of the Payment
Processing API's provided for merchant applications.
The Java API'S also implement each one of the Payment
Processing API's provided for merchant applications.
The Java package oracle.apps.iby.ecapp contains the
specification of all the Java API's provided, those
classes are located in the apps.zip provided along with
Oracle Applications.
The payment processing PL/SQL API’s are
implemented using the UTL_HTTP database package.
For example:
IBY_PAYMENT_ADAPTER_PUB.OraPmtReq.
When the merchant application calls the PL/SQL API
for processing a transaction (for instance a credit card
authorization), the API submits an HTTP request (by
using the UTL_HTTP.request) , along with all the
parameters for the transaction, to the iPayment
ECServlet. The URL address to the iPayment ECServlet
is retrieved from the iPayment properties. The property
iPaymentURL contains the URL to the iPayment
processing engine or the ECServlet. The iPayment
ECServlet (Java Servlet) processes the request in the
server by making a call to the corresponding Java API
for the transaction.
When calling the Java API directly from your merchant
application you will avoid the additional HTTP request
generated when using the PL/SQL API’s.
From other applications in the Oracle Applications
eBusiness Suite, the request to the iPayment engine is
sent using the PL/SQL API’s.
Step B, iPayment (each Java API) will submit the
transaction to the Payment System by using an HTTP
request (For details see section IV ahead). iPayment
determines which payment system to send the
transaction to based on the “Routing Rules” defined
(navigate jtflogin.jsp -> Routing Rule -> Select or
create).
Figure 2 - Create Routing Rule Screen
There are three different types of “Routing Rules” that
you can combine to meet your needs (see figure 2):
amount, instrument type and/or currency. For example,
you can have Payment System A for Credit Card
transactions and Payment System B for Purchase Card
transactions. Also you can have Payment System A for
Credit Card transactions below $20, Payment System B
for Credit Card Transactions over$20, and Payment
System C for Purchase Card transactions.
The HTTP request or URL that the iPayment engine
will send to the Payment System is defined based on
three parts:
1. Host, domain, port number
2. Execution engine
3. Parameters for the transaction
These parts are described in detail below:
1. Host,domain and port number are retrieved from
the database. The Base URL field is defined for the
payment system using the iPayment Administration
2
Interface (navigate jtflogin.jsp -> Payment System ->
Select Payment System to use). This field should
contain a string in the following format (see also figure
3):
http://MachineName. DomainName:port/servlet-zone
For Example:
http://www.oracle.com:9999/servlet
Servlet should be defined as a servlet zone in your
Apache/Jserv configuration files, if using the Jserv
execution engine. The Apache/Jserv in an Oracle
Applications 11i installation are located is the
$APACHE_TOP/Jserv/etc directory.
Figure 3 - iPayment Admin - Payment System Details screen
You can also use http://www.oracle.com:9999/ as the
URL. In this case you should be using a solution not
implemented via java servlets in the Apache/Jserv
architecture. Rather you will implement the Payment
System using other language like Perl, or even using a
different web server.
2. The execution engine is automatically built
appending oramipp_XXX . XXX is the suffix or short
name specified in the Payment Systems screen of the
iPayment Administration Interface for the payment
system (See Figure 3). For Example:
Suffix for CyberCash will be cyb.
Using CyberCash’s example iPayment will construct an
URL with the following form:
(a)
http://MachineName.DomainName:port/servlet/oramipp_cyb
or if you are not implementing the Payment System with a
servlet in the Apache/Jserv architecture, then the URL will
look like:
(b)
http://MachineName.DomainName:port/oramipp_cyb
The important point at this step is that the URL: either (a) or
(b) needs to be a responsive URL.
3. Parameters for the transaction. Each transaction
will require a different set of parameters. The iPayment
engine will add to the URL the needed parameters,
according to the transaction, and will pass the values in
the URL. Most of the values to be passed were already
passed by the Merchant application when calling the
merchant API for the transaction.
For documentation of the parameters for every
transaction consult the “iPayment Implementation
Guide” Appendix D.
Step C, the Payment System Servlet (or Payment
System Implementation) returns a response to the
iPayment Engine in the form of an HTML page or
HTTP response (For details see section IV ahead). In
the case that the merchant application was calling the
iPayment Java API’s directly, it will receive the status
of the transaction in the output parameters of the Java
API’s in use. If the merchant application was using the
PL/SQL API then the output parameters back from the
Java API’s will be packed into an HTML response page
that will be send back to the database or the PL/SQL
engine.
Step D, The PL/SQL API unpacks the results coming
within the HTML response page, and assigns the results
to the PL/SQL return parameters for the API. The
merchant application receives the results of the
transaction in the output parameters of the call to the
PL/SQL API.
IV. HOW DO THE BACK-END PAYMENT
PROCESSING API’S WORK?
iPayment does not provide a default implementation for
the Back End Payment Processing API’s, other than
CyberCash and Checkfree. These API’s are meant to be
implemented by the customer or by Back End Payment
Processors themselves. Implementing these API’s is the
only way to connect iPayment to a Back End Payment
Processor.
The implementation of these API’s can be achieved
using a Java Servlet executing in the same environment
as the one for the iPayment engine. It can be done using
any other module (for example Perl) of the Apache
architecture, or even as a separate web server. The
reason why there are many implementation alternatives
3
is because the request that is submitted to this Payment
System Engine is a standard HTTP request.
The main function of this Payment System engine is to
translate the request that is coming, with a format and
transfer-media which is Native to iPayment, into a
format and transfer-media that is Native for the Back-
End Payment Processor.
Since each Payment Processor provides a different
interface to initiate their process, the only way
iPayment has to generalize is to provide the definition
of a standard interface for every Back End Payment
processor (or Payment System) to implement: standard
Input Parameters and standard output Parameters. When
implementing the payment system the payment system
implementation needs to be capable of:
• Receiving an HTTP (Url) request along with the
parameters defined for the transaction, which are
defined in the "Back End Payment Processor
API's".
• Translating the request into the Payment Processor
specific format.
• Sending the request and receiving a response from
the Back End Payment processor.
• Sending back a response as a web page (HTTP
Response) containig the output parameters for the
transaction, which are defined in the "Back End
Payment Processor API's".
V. WHAT IS THE STATUS UPDATE API?
The Status Update API ,even though not a formal part
of the Payment Processing API plays a fundamental role
for completing the eCommerce cycle when using off-
line transactions. Each transaction is sent along with the
type as one of the parameters: off-line or on-line, default
is online. When using off-line transactions, the
Scheduler Servlet will pick those off-line transactions
and will contact the Payment System Implementation
for processing the transaction the same way as
described. In addition, it will update the iPayment
schema with the results of the process for each
transaction. The only portion missing is the update of
the transaction in the Merchant Application Schema.
The Status API will provide the means needed to update
the Merchant Application Schema. The Status Update
API will have to be implemented by every application
interacting with iPayment (every application needs to be
registered first with iPayment, for more details check
the iPayment Implementation Guide). Every application
should create a PL/SQL package called
<application_short_name>_ecapp_pkg that will be
called by the scheduler when updating the status of a
transaction. <application_short_name> is the short name
for the application as given when it was registered with
iPayment.
VI. WHAT ARE THE REQUIRED
CONFIGURATION STEPS?
There are several steps to cover in order to configure
iPayment 11i. Depending on what your needs are you
might need to configure some components but not
others
A) If you are going to use Oracle iStore, Oracle Order
Management, Oracle Accounts Receivable, or any other
application that belongs to the Oracle Applications 11i
product then you need to follow the following minimal
steps:
1? Create an iPayment Administrator user.
2? Configure the ECServlet Servlet: Create a servlet
zone in jserv.properties, and Servlet alias in zone-
name.properties file.
3? Configure your Payment System: Payment System
configuration using the iPayment Administration
screen and the "Payment System
Servlet/Implementation", according to the
documentation for that "Payment System
Implementation" software. In the CyberCash and
Checkfree case the instructions are provided along
with the iPayment Implementation Guide.
4? Create one Payee (or Merchant identified by its
merchant id or payee id)
5? Create one routing rules for processing
6? Optionally you can enable the "Risk Management"
features.
7? Configure the Application that you are going to use
to capture the credit card information and submit
the request to the payment engine. Please see
individual manuals for:
• Configuring iStore 11i
• Configuring Order Management 11i
• Configuring Accounts Receivables 11i
B) If you are not using any Oracle Applications as your
merchant application, then you need the following
minimal steps:
1? Create an iPayment Administratior user .
2? If you are going to use the PL/SQL API to access
iPayment engine you should configure ECServlet
Servlet: Create a servlet zone in jserv.properties,
and Servlet alias in zone-name.properties file.
3? Configure your Payment System: Payment System
configuration using the iPayment Administration
screen and the "Payment System
Servlet/Implementation", according to the
documentation for that "Payment System
4
 Implementation" software. In the CyberCash and
Checkfree case the instructions are provided along
with the iPayment Implementation Guide.
4? Create one Payee (or Merchant identified by its
merchant id or payee id)
5? Register your new Electronic Commerce
Application
6? If you are going to take advantage in your merchant
application of the Risk Management Features in
iPayment you should configure the Risky
Instruments.
7? You should implement the Electronic Commerce
APIs, either PL/SQL or JAVA.

In addition to the steps described for A) and B) you can

also configure the Scheduler capabilities in iPayment
by:

1? Configuring the Scheduler Servlet

2? Configuring the Scheduler, and by implementing
the Status Update API.

If you are not going to use the out-of-the-box payment

systems provided with iPayment then you need to
Implement the Back End processing APIs, or payment
system APIs, as described in the Implementation Guide
for iPayment.

Conclusions

It is our hope that this paper will help you to understand

how the Payment Processing API's for iPayment works,
and that using this a reference you should be able to
implement iPayment with more success.

About the Authors

Esteban Rodriguez is a Senior Technical Analysts for
the eCommerce Support team.