Embed Size (px)
Citation preview
1
iPayment 11i: How to use iPayment Payment Processing API’s
Esteban RodriguezOracle Corporation
Abstract
This paper explains how the iPayment PaymentProcessing API's work and also describes and explainsthe steps needed to configure iPayment 11i to use thePayment Processing API's. This document does notcover the flow when integrating with CheckFree forBank account transfers.
Scope
I. What is iPayment?II. What are the Payment Processing API’s?III. How do the Merchant Payment Processing
API’s Work?IV. How do the Back-end Payment Processing
API’s work?V. What is the Status Update API?VI. What are the required configuration steps?VII. Conclusion
Please note that this paper does not replace youriPayment 11i Implementation Guide. This paper isintended to give you a deeper understanding of theiPayment functionality , and also to provide the minimalsteps needed to use these Payment Processing API's.
References
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 standardinterface to the Back-end payment processors (forexample CyberCash, Checkfree) in such a way that amerchant is completely independent from the Back-endpayment processor in use. In addition iPayment 11iprovides support for SSL (Secure Socket Layer), andprovides capabilities for Risk-Management controlthrough the use of rules. iPayment 11i also providesintegration with Oracle Applications 11i , allowingbusinesses to have payment processing across theenterprise providing a single source of access to the
different Back-end payment processors such as:CyberCash, CheckFree, etc.
II. WHAT ARE THE PAYMENT PROCESSINGAPI’S?
The Payment Processing API's are transactional API'sthat provide the support for each one of the electroniccommerce transactions. For example: Authorizations ofCredit Cards, Capture, Cancel, Return and otheroperations
III. HOW DO THE MERCHANT PAYMENTPROCESSING API’S WORK?
iPayment 11i is an engine that receives transactionrequests from merchant applications and submits thattransaction request to the Back End Payment Processor.When the response is received back from the Back EndPayment Processor, iPayment processes that responseand generates a new response that is returned to theMerchant application.
In addition to the Payment Processing capabilities,iPayment provides additional API's/functionality forRisk Control, Administration of Payment Instruments,Credit Card Validation and Status Update for off-linepayment processing.
iPayment Payment ProcessingAPI’s
OracleOrder
Management
HTTP
ListenerECServlet iPayment
Java API’s
APPS DB
iPaymentPL/SQL API’s
iPayment/Apps Schema
PaymentSystemServlet
Back EndPaymentProcessor
OracleiStore
PL/SQLBusiness API’s
iStoreJava
Servletsand API’s
Procedure calls
HTTP Request or Response
1.1
1.2
1.3
2.1
1.4
3.1
3.2
3.33.4
3.5 3.6
3.7
3.83.10
3.11
3.9
Figure 1 - Payment Processing API’s
There are several steps through which the transactionpasses when using iPayment. See also Figure 1 forreference:
2
A. Submission of the transaction from the MerchantApplication to iPayment (See Figure 1 for flows 2.1or 1.1-1.2-1.3, then 3.1-3.2-3.3)
B. Submission of the transaction from the iPaymentEngine to the Back End Payment Processor (Seefigure 1 for flow 3.5)
C. Reception of the response generated by the BackEnd Payment Processor (See figure 1 for flow 3.8)
D. Generation of the response that will be send back tothe Merchant Application. (See figure 1for flows3.10-3.11)
Step A, the merchant application submits a transactionrequest (Example: credit card authorization request) tothe iPayment engine. That transaction request isaccomplished by using the Payment Processing API'sfor Electronic Commerce Applications provided byiPayment. iPayment 11i provides two types of PaymentProcessing API's:
a) PL/SQL API'sb) Java API's
The PL/SQL API's in iPayment are implemented in the"IBY_PAYMENT_ADAPTER_PUB" package. Thispackage (some times referred as PMT_UTIL) providesprocedures to implement each one of the PaymentProcessing API's provided for merchant applications.
The Java API'S also implement each one of the PaymentProcessing API's provided for merchant applications.The Java package oracle.apps.iby.ecapp contains thespecification of all the Java API's provided, thoseclasses are located in the apps.zip provided along withOracle Applications.
The payment processing PL/SQL API’s areimplemented using the UTL_HTTP database package.For example:IBY_PAYMENT_ADAPTER_PUB.OraPmtReq.
When the merchant application calls the PL/SQL APIfor processing a transaction (for instance a credit cardauthorization), the API submits an HTTP request (byusing the UTL_HTTP.request) , along with all theparameters for the transaction, to the iPaymentECServlet. The URL address to the iPayment ECServletis retrieved from the iPayment properties. The propertyiPaymentURL contains the URL to the iPaymentprocessing engine or the ECServlet. The iPaymentECServlet (Java Servlet) processes the request in theserver by making a call to the corresponding Java APIfor the transaction.
When calling the Java API directly from your merchantapplication you will avoid the additional HTTP requestgenerated when using the PL/SQL API’s.
From other applications in the Oracle ApplicationseBusiness Suite, the request to the iPayment engine issent using the PL/SQL API’s.
Step B, iPayment (each Java API) will submit thetransaction to the Payment System by using an HTTPrequest (For details see section IV ahead). iPaymentdetermines which payment system to send thetransaction to based on the “Routing Rules” defined(navigate jtflogin.jsp -> Routing Rule -> Select orcreate).
Figure 2 - Create Routing Rule Screen
There are three different types of “Routing Rules” thatyou 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 Cardtransactions and Payment System B for Purchase Cardtransactions. Also you can have Payment System A forCredit Card transactions below $20, Payment System Bfor Credit Card Transactions over$20, and PaymentSystem C for Purchase Card transactions.
The HTTP request or URL that the iPayment enginewill send to the Payment System is defined based onthree parts:
1. Host, domain, port number2. Execution engine3. Parameters for the transaction
These parts are described in detail below:
1. Host,domain and port number are retrieved fromthe database. The Base URL field is defined for thepayment system using the iPayment Administration
3
Interface (navigate jtflogin.jsp -> Payment System ->Select Payment System to use). This field shouldcontain a string in the following format (see also figure3):
http://MachineName. DomainName:port/servlet-zone
For Example:
http://www.oracle.com:9999/servlet
Servlet should be defined as a servlet zone in yourApache/Jserv configuration files, if using the Jservexecution engine. The Apache/Jserv in an OracleApplications 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 theURL. In this case you should be using a solution notimplemented via java servlets in the Apache/Jservarchitecture. Rather you will implement the PaymentSystem using other language like Perl, or even using adifferent web server.
2. The execution engine is automatically builtappending oramipp_XXX . XXX is the suffix or shortname specified in the Payment Systems screen of theiPayment Administration Interface for the paymentsystem (See Figure 3). For Example:
Suffix for CyberCash will be cyb.
Using CyberCash’s example iPayment will construct anURL with the following form:
(a)http://MachineName.DomainName:port/servlet/oramipp_cyb
or if you are not implementing the Payment System with aservlet in the Apache/Jserv architecture, then the URL willlook 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 transactionwill require a different set of parameters. The iPaymentengine will add to the URL the needed parameters,according to the transaction, and will pass the values inthe URL. Most of the values to be passed were alreadypassed by the Merchant application when calling themerchant API for the transaction.
For documentation of the parameters for everytransaction consult the “iPayment ImplementationGuide” Appendix D.
Step C, the Payment System Servlet (or PaymentSystem Implementation) returns a response to theiPayment Engine in the form of an HTML page orHTTP response (For details see section IV ahead). Inthe case that the merchant application was calling theiPayment Java API’s directly, it will receive the statusof the transaction in the output parameters of the JavaAPI’s in use. If the merchant application was using thePL/SQL API then the output parameters back from theJava API’s will be packed into an HTML response pagethat will be send back to the database or the PL/SQLengine.
Step D, The PL/SQL API unpacks the results comingwithin the HTML response page, and assigns the resultsto the PL/SQL return parameters for the API. Themerchant application receives the results of thetransaction in the output parameters of the call to thePL/SQL API.
IV. HOW DO THE BACK-END PAYMENTPROCESSING API’S WORK?
iPayment does not provide a default implementation forthe Back End Payment Processing API’s, other thanCyberCash and Checkfree. These API’s are meant to beimplemented by the customer or by Back End PaymentProcessors themselves. Implementing these API’s is theonly way to connect iPayment to a Back End PaymentProcessor.
The implementation of these API’s can be achievedusing a Java Servlet executing in the same environmentas the one for the iPayment engine. It can be done usingany other module (for example Perl) of the Apachearchitecture, or even as a separate web server. Thereason why there are many implementation alternatives
4
is because the request that is submitted to this PaymentSystem Engine is a standard HTTP request.
The main function of this Payment System engine is totranslate the request that is coming, with a format andtransfer-media which is Native to iPayment, into aformat and transfer-media that is Native for the Back-End Payment Processor.
Since each Payment Processor provides a differentinterface to initiate their process, the only wayiPayment has to generalize is to provide the definitionof a standard interface for every Back End Paymentprocessor (or Payment System) to implement: standardInput Parameters and standard output Parameters. Whenimplementing the payment system the payment systemimplementation needs to be capable of:
• Receiving an HTTP (Url) request along with theparameters defined for the transaction, which aredefined in the "Back End Payment ProcessorAPI's".
• Translating the request into the Payment Processorspecific format.
• Sending the request and receiving a response fromthe Back End Payment processor.
• Sending back a response as a web page (HTTPResponse) containig the output parameters for thetransaction, which are defined in the "Back EndPayment Processor API's".
V. WHAT IS THE STATUS UPDATE API?
The Status Update API ,even though not a formal partof the Payment Processing API plays a fundamental rolefor completing the eCommerce cycle when using off-line transactions. Each transaction is sent along with thetype as one of the parameters: off-line or on-line, defaultis online. When using off-line transactions, theScheduler Servlet will pick those off-line transactionsand will contact the Payment System Implementationfor processing the transaction the same way asdescribed. In addition, it will update the iPaymentschema with the results of the process for eachtransaction. The only portion missing is the update ofthe transaction in the Merchant Application Schema.The Status API will provide the means needed to updatethe Merchant Application Schema. The Status UpdateAPI will have to be implemented by every applicationinteracting with iPayment (every application needs to beregistered first with iPayment, for more details checkthe iPayment Implementation Guide). Every applicationshould create a PL/SQL package called<application_short_name>_ecapp_pkg that will becalled by the scheduler when updating the status of atransaction. <application_short_name> is the short name
for the application as given when it was registered withiPayment.
VI. WHAT ARE THE REQUIREDCONFIGURATION STEPS?
There are several steps to cover in order to configureiPayment 11i. Depending on what your needs are youmight need to configure some components but notothers
A) If you are going to use Oracle iStore, Oracle OrderManagement, Oracle Accounts Receivable, or any otherapplication that belongs to the Oracle Applications 11iproduct then you need to follow the following minimalsteps:
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 Systemconfiguration using the iPayment Administrationscreen and the "Payment SystemServlet/Implementation", according to thedocumentation for that "Payment SystemImplementation" software. In the CyberCash andCheckfree case the instructions are provided alongwith the iPayment Implementation Guide.
4? Create one Payee (or Merchant identified by itsmerchant id or payee id)
5? Create one routing rules for processing6? 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 submitthe request to the payment engine. Please seeindividual manuals for:• Configuring iStore 11i• Configuring Order Management 11i• Configuring Accounts Receivables 11i
B) If you are not using any Oracle Applications as yourmerchant application, then you need the followingminimal 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 ECServletServlet: Create a servlet zone in jserv.properties,and Servlet alias in zone-name.properties file.
3? Configure your Payment System: Payment Systemconfiguration using the iPayment Administrationscreen and the "Payment SystemServlet/Implementation", according to thedocumentation for that "Payment System
5
Implementation" software. In the CyberCash andCheckfree case the instructions are provided alongwith the iPayment Implementation Guide.
4? Create one Payee (or Merchant identified by itsmerchant id or payee id)
5? Register your new Electronic CommerceApplication
6? If you are going to take advantage in your merchantapplication of the Risk Management Features iniPayment you should configure the RiskyInstruments.
7? You should implement the Electronic CommerceAPIs, either PL/SQL or JAVA.
In addition to the steps described for A) and B) you canalso configure the Scheduler capabilities in iPaymentby:
1? Configuring the Scheduler Servlet2? Configuring the Scheduler, and by implementing
the Status Update API.
If you are not going to use the out-of-the-box paymentsystems provided with iPayment then you need toImplement the Back End processing APIs, or paymentsystem APIs, as described in the Implementation Guidefor iPayment.
Conclusions
It is our hope that this paper will help you to understandhow the Payment Processing API's for iPayment works,and that using this a reference you should be able toimplement iPayment with more success.
About the Authors
Esteban Rodriguez is a Senior Technical Analysts forthe eCommerce Support team.
