This action might not be possible to undo. Are you sure you want to continue?
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
3.3 3.4 3.10
iPayment Java API’ s
Payment System Servlet
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
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:
The HTTP request or URL that the iPayment engine will send to the Payment System is defined based on three parts: 1. the API submits an HTTP request (by using the UTL_HTTP. Generation of the response that will be send back to the Merchant Application.1-3. iPayment (each Java API) will submit the transaction to the Payment System by using an HTTP request (For details see section IV ahead). This package (some times referred as PMT_UTIL) provides procedures to implement each one of the Payment Processing API's provided for merchant applications.A. (See figure 1for flows 3. The iPayment ECServlet (Java Servlet) processes the request in the server by making a call to the corresponding Java API for the transaction. Reception of the response generated by the Back End Payment Processor (See figure 1 for flow 3. For example.OraPmtReq.5) C. and Payment System C for Purchase Card transactions. The Java package oracle. The URL address to the iPayment ECServlet is retrieved from the iPayment properties.domain and port number are retrieved from the database. to the iPayment ECServlet. The property iPaymentURL contains the URL to the iPayment processing engine or the ECServlet. From other applications in the Oracle Applications eBusiness Suite. When the merchant application calls the PL/SQL API for processing a transaction (for instance a credit card authorization). Also you can have Payment System A for Credit Card transactions below $20. you can have Payment System A for Credit Card transactions and Payment System B for Purchase Card transactions.2-3. Host.1 or 1.11) Step A. Step B. The payment processing PL/SQL API’ are s implemented using the UTL_HTTP database package. iPayment determines which payment system to send the transaction to based on the “Routing Rules” defined (navigate jtflogin. the merchant application submits a transaction request (Example: credit card authorization request) to the iPayment engine. Host.iby.jsp -> Routing Rule -> Select or create).zip provided along with Oracle Applications.10-3. those classes are located in the apps. the request to the iPayment engine is sent using the PL/SQL API’ s.Create Routing Rule Screen There are three different types of “Routing Rules” that you can combine to meet your needs (see figure 2): amount.apps.2-1.request) . Submission of the transaction from the Merchant Application to iPayment (See Figure 1 for flows 2. Payment System B for Credit Card Transactions over$20. then 3.ecapp contains the specification of all the Java API's provided. Submission of the transaction from the iPayment Engine to the Back End Payment Processor (See figure 1 for flow 3. 3. The Base URL field is defined for the payment system using the iPayment Administration 2 .3) B. 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. instrument type and/or currency. The Java API'S also implement each one of the Payment Processing API's provided for merchant applications. 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. That transaction request is accomplished by using the Payment Processing API's for Electronic Commerce Applications provided by iPayment. port number Execution engine Parameters for the transaction These parts are described in detail below: 1. along with all the parameters for the transaction. Figure 2 . domain.1-1. 2.3. For example: IBY_PAYMENT_ADAPTER_PUB.8) D.
DomainName:port/servlet/oramipp_cyb or if you are not implementing the Payment System with a servlet in the Apache/Jserv architecture. Implementing these API’ is the s only way to connect iPayment to a Back End Payment Processor.oracle. then the URL will look like: 3 . 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.oracle. These API’ are meant to be s implemented by the customer or by Back End Payment Processors themselves. or even as a separate web server. It can be done using any other module (for example Perl) of the Apache architecture. The Apache/Jserv in an Oracle Applications 11i installation are located is the $APACHE_TOP/Jserv/etc directory.com:9999/ as the URL. For documentation of the parameters for every transaction consult the “iPayment Implementation Guide” Appendix D.jsp -> Payment System -> Select Payment System to use). Parameters for the transaction. In this case you should be using a solution not implemented via java servlets in the Apache/Jserv architecture. 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).Interface (navigate jtflogin. The merchant application receives the results of the transaction in the output parameters of the call to the PL/SQL API.DomainName:port/oramipp_cyb The important point at this step is that the URL: either (a) or (b) needs to be a responsive URL.Payment System Details screen You can also use http://www. Step C. and will pass the values in the URL. CyberCash and Checkfree. DomainName:port/servlet-zone For Example: http://www. This field should contain a string in the following format (see also figure 3): http://MachineName. 3. For Example: Suffix for CyberCash will be cyb. according to the transaction. Most of the values to be passed were already passed by the Merchant application when calling the merchant API for the transaction. The PL/SQL API unpacks the results coming within the HTML response page. Using CyberCash’ example iPayment will construct an s URL with the following form: (a) http://MachineName. it will receive the status s of the transaction in the output parameters of the Java API’ in use. 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. 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).com:9999/servlet Servlet should be defined as a servlet zone in your Apache/Jserv configuration files. The iPayment engine will add to the URL the needed parameters.iPayment Admin . IV. (b) http://MachineName. or even using a different web server. if using the Jserv execution engine. Rather you will implement the Payment System using other language like Perl. 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 reason why there are many implementation alternatives Figure 3 . The execution engine is automatically built appending oramipp_XXX . In the case that the merchant application was calling the iPayment Java API’ directly. 2. Step D. Each transaction will require a different set of parameters. and assigns the results to the PL/SQL return parameters for the API.
VI. The main function of this Payment System engine is to translate the request that is coming. for more details check the iPayment Implementation Guide). which are defined in the "Back End Payment Processor API's". Oracle Accounts Receivable. Since each Payment Processor provides a different interface to initiate their process. which are defined in the "Back End Payment Processor API's". 3? Configure your Payment System: Payment System configuration using the iPayment Administration screen and the "Payment System Servlet/Implementation". The only portion missing is the update of the transaction in the Merchant Application Schema. 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. • Sending the request and receiving a response from the Back End Payment processor. and Servlet alias in zonename. When using off-line transactions. 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. it will update the iPayment schema with the results of the process for each transaction. 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. WHAT IS THE STATUS UPDATE API? The Status Update API . 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. • Sending back a response as a web page (HTTP Response) containig the output parameters for the transaction. 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. <application_short_name> is the short name for the application as given when it was registered with iPayment. into a format and transfer-media that is Native for the BackEnd Payment Processor. 2? Configure the ECServlet Servlet: Create a servlet zone in jserv. 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. with a format and transfer-media which is Native to iPayment. according to the documentation for that "Payment System Implementation" software.properties file.properties. • Translating the request into the Payment Processor specific format. 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. Oracle Order Management. V. according to the documentation for that "Payment System 4 . The Status API will provide the means needed to update the Merchant Application Schema. and Servlet alias in zone-name.even though not a formal part of the Payment Processing API plays a fundamental role for completing the eCommerce cycle when using offline transactions. Each transaction is sent along with the type as one of the parameters: off-line or on-line. 7? Configure the Application that you are going to use to capture the credit card information and submit the request to the payment engine. 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. default is online.properties. then you need the following minimal steps: 1? Create an iPayment Administratior user .properties file. 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. In the CyberCash and Checkfree case the instructions are provided along with the iPayment Implementation Guide.is because the request that is submitted to this Payment System Engine is a standard HTTP request. The Status Update API will have to be implemented by every application interacting with iPayment (every application needs to be registered first with iPayment. In addition. 3? Configure your Payment System: Payment System configuration using the iPayment Administration screen and the "Payment System Servlet/Implementation".
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. About the Authors Esteban Rodriguez is a Senior Technical Analysts for the eCommerce Support team. You should implement the Electronic Commerce APIs. either PL/SQL or JAVA. In the CyberCash and Checkfree case the instructions are provided along with the iPayment Implementation Guide. 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. 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. 5 . Conclusions It is our hope that this paper will help you to understand how the Payment Processing API's for iPayment works.4? 5? 6? 7? Implementation" software. as described in the Implementation Guide for iPayment. and that using this a reference you should be able to implement iPayment with more success.