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

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

I. II. III. IV. V. VI. VII. What is iPayment? What are the Payment Processing API’ s? How do the Merchant Payment Processing API’ Work? s How do the Back-end Payment Processing API’ work? s What is the Status Update API? What are the required configuration steps? Conclusion

Please note that this paper does not replace your iPayment 11i Implementation Guide. This paper is intended to give you a deeper understanding of the iPayment functionality , and also to provide the minimal steps needed to use these Payment Processing API's.

For detailed information on all the iPayment features, please read the following references. Oracle iPayment 11i Concepts and Procedures Guide. Oracle iPayment 11i Implementation Guide. I. WHAT IS IPAYMENT? iPayment 11i is an application that creates a standard interface to the Back-end payment processors (for example CyberCash, Checkfree) in such a way that a merchant is completely independent from the Back-end payment processor in use. In addition iPayment 11i provides support for SSL (Secure Socket Layer), and provides capabilities for Risk-Management control through the use of rules. iPayment 11i also provides integration with Oracle Applications 11i , allowing businesses to have payment processing across the enterprise providing a single source of access to the

iPayment Payment Processing API’ s

Oracle iStore

HTTP Listener

3.3 3.4 3.10




iPayment Java API’ s


Payment System Servlet


1.2 3.2

iPayment PL/SQL API’s 1.3 3.1 PL/SQL Business API’s

Oracle Order Management

iStore Java Servlets and API’ s


Back End Payment Processor

iPayment/Apps Schema

Procedure calls HTTP Request or Response

Figure 1 - Payment Processing API’ s

There are several steps through which the transaction passes when using iPayment. See also Figure 1 for reference:


3. The iPayment ECServlet (Java Servlet) processes the request in the server by making a call to the corresponding Java API for the transaction.Create Routing Rule Screen There are three different types of “Routing Rules” that you can combine to meet your needs (see figure 2): amount. iPayment (each Java API) will submit the transaction to the Payment System by using an HTTP request (For details see section IV ahead). 3.A. you can have Payment System A for Credit Card transactions and Payment System B for Purchase Card transactions. When the merchant application calls the PL/SQL API for processing a transaction (for instance a credit card authorization). Host. This package (some times referred as PMT_UTIL) provides procedures to implement each one of the Payment Processing API's provided for merchant applications.zip provided along with Oracle Applications. That transaction request is accomplished by using the Payment Processing API's for Electronic Commerce Applications provided by iPayment.request) . the API submits an HTTP request (by using the UTL_HTTP. The Java API'S also implement each one of the Payment Processing API's provided for merchant applications. to the iPayment ECServlet. those classes are located in the apps. The HTTP request or URL that the iPayment engine will send to the Payment System is defined based on three parts: 1. The Java package oracle. Submission of the transaction from the Merchant Application to iPayment (See Figure 1 for flows 2. 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.OraPmtReq. The URL address to the iPayment ECServlet is retrieved from the iPayment properties.2-1. along with all the parameters for the transaction. Submission of the transaction from the iPayment Engine to the Back End Payment Processor (See figure 1 for flow 3.ecapp contains the specification of all the Java API's provided. For example: IBY_PAYMENT_ADAPTER_PUB. 2.jsp -> Routing Rule -> Select or create).2-3. The Base URL field is defined for the payment system using the iPayment Administration 2 . domain.apps.iby. (See figure 1for flows 3. Step B.10-3. 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. then 3. The payment processing PL/SQL API’ are s implemented using the UTL_HTTP database package.1 or 1. Also you can have Payment System A for Credit Card transactions below $20. iPayment determines which payment system to send the transaction to based on the “Routing Rules” defined (navigate jtflogin.1-1. Host. From other applications in the Oracle Applications eBusiness Suite. For example. Payment System B for Credit Card Transactions over$20.3) B. Generation of the response that will be send back to the Merchant Application.11) Step A.5) C. Reception of the response generated by the Back End Payment Processor (See figure 1 for flow 3. port number Execution engine Parameters for the transaction These parts are described in detail below: 1.1-3. the merchant application submits a transaction request (Example: credit card authorization request) to the iPayment engine.domain and port number are retrieved from the database. instrument type and/or currency. Figure 2 . The property iPaymentURL contains the URL to the iPayment processing engine or the ECServlet. and Payment System C for Purchase Card transactions.8) D. the request to the iPayment engine is sent using the PL/SQL API’ s.

according to the transaction. The reason why there are many implementation alternatives Figure 3 . 3.oracle. In this case you should be using a solution not implemented via java servlets in the Apache/Jserv architecture. or even as a separate web server. HOW DO THE BACK-END PAYMENT PROCESSING API’ WORK? S iPayment does not provide a default implementation for the Back End Payment Processing API’ other than s. This field should contain a string in the following format (see also figure 3): http://MachineName. Using CyberCash’ example iPayment will construct an s URL with the following form: (a) http://MachineName. The Apache/Jserv in an Oracle Applications 11i installation are located is the $APACHE_TOP/Jserv/etc directory. 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). IV. (b) http://MachineName. and assigns the results to the PL/SQL return parameters for the API. and will pass the values in the URL. For documentation of the parameters for every transaction consult the “iPayment Implementation Guide” Appendix D. then the URL will look like: 3 . The iPayment engine will add to the URL the needed parameters. If the merchant application was using the s PL/SQL API then the output parameters back from the Java API’ will be packed into an HTML response page s that will be send back to the database or the PL/SQL engine.com:9999/ as the URL. if using the Jserv execution engine. Implementing these API’ is the s only way to connect iPayment to a Back End Payment Processor. Step C.Payment System Details screen You can also use http://www. In the case that the merchant application was calling the iPayment Java API’ directly.DomainName:port/oramipp_cyb The important point at this step is that the URL: either (a) or (b) needs to be a responsive URL. The implementation of these API’ can be achieved s using a Java Servlet executing in the same environment as the one for the iPayment engine. The merchant application receives the results of the transaction in the output parameters of the call to the PL/SQL API.iPayment Admin . or even using a different web server.com:9999/servlet Servlet should be defined as a servlet zone in your Apache/Jserv configuration files.oracle. Parameters for the transaction. The PL/SQL API unpacks the results coming within the HTML response page. 2. Step D. Each transaction will require a different set of parameters. Rather you will implement the Payment System using other language like Perl.DomainName:port/servlet/oramipp_cyb or if you are not implementing the Payment System with a servlet in the Apache/Jserv architecture. For Example: Suffix for CyberCash will be cyb. Most of the values to be passed were already passed by the Merchant application when calling the merchant API for the transaction. These API’ are meant to be s implemented by the customer or by Back End Payment Processors themselves. 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). The execution engine is automatically built appending oramipp_XXX . It can be done using any other module (for example Perl) of the Apache architecture. DomainName:port/servlet-zone For Example: http://www. it will receive the status s of the transaction in the output parameters of the Java API’ in use.jsp -> Payment System -> Select Payment System to use). CyberCash and Checkfree.Interface (navigate jtflogin.

then you need the following minimal steps: 1? Create an iPayment Administratior user . according to the documentation for that "Payment System Implementation" software. 2? Configure the ECServlet Servlet: Create a servlet zone in jserv.properties file. 3? Configure your Payment System: Payment System configuration using the iPayment Administration screen and the "Payment System Servlet/Implementation". Each transaction is sent along with the type as one of the parameters: off-line or on-line. <application_short_name> is the short name for the application as given when it was registered with iPayment.properties. The only portion missing is the update of the transaction in the Merchant Application Schema. which are defined in the "Back End Payment Processor API's". for more details check the iPayment Implementation Guide). default is online. 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. and Servlet alias in zone-name. When using off-line transactions. into a format and transfer-media that is Native for the BackEnd Payment Processor. The Status API will provide the means needed to update the Merchant Application Schema. WHAT IS THE STATUS UPDATE API? The Status Update API . 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. VI. • Sending back a response as a web page (HTTP Response) containig the output parameters for the transaction.properties file. WHAT ARE THE REQUIRED CONFIGURATION STEPS? There are several steps to cover in order to configure iPayment 11i. In addition.is because the request that is submitted to this Payment System Engine is a standard HTTP request. Since each Payment Processor provides a different interface to initiate their process. • Sending the request and receiving a response from the Back End Payment processor. V. Oracle Order Management. • Translating the request into the Payment Processor specific format. The Status Update API will have to be implemented by every application interacting with iPayment (every application needs to be registered first with iPayment. 7? Configure the Application that you are going to use to capture the credit card information and submit the request to the payment engine. The main function of this Payment System engine is to translate the request that is coming. Oracle Accounts Receivable. 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. 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. 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.even though not a formal part of the Payment Processing API plays a fundamental role for completing the eCommerce cycle when using offline transactions. 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. 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. 3? Configure your Payment System: Payment System configuration using the iPayment Administration screen and the "Payment System Servlet/Implementation". which are defined in the "Back End Payment Processor API's". with a format and transfer-media which is Native to iPayment. 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. it will update the iPayment schema with the results of the process for each transaction. and Servlet alias in zonename. In the CyberCash and Checkfree case the instructions are provided along with the iPayment Implementation Guide. according to the documentation for that "Payment System 4 . 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.

About the Authors Esteban Rodriguez is a Senior Technical Analysts for the eCommerce Support team.4? 5? 6? 7? Implementation" software. as described in the Implementation Guide for iPayment. 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. In the CyberCash and Checkfree case the instructions are provided along with the iPayment Implementation Guide. 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. 5 . and by implementing the Status Update API. either PL/SQL or JAVA. Create one Payee (or Merchant identified by its merchant id or payee id) Register your new Electronic Commerce Application If you are going to take advantage in your merchant application of the Risk Management Features in iPayment you should configure the Risky Instruments. or payment system APIs. You should implement the Electronic Commerce APIs. 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.

Sign up to vote on this title
UsefulNot useful