Oracle iPayment · iPayment consists of the following servlets: ... 4 Oracle iPayment Concepts and Procedures ... Understanding Credit Card Transactions iPayment handles both credit

Oracle iPayment

Concepts and Procedures

Release 11i

April 2000

Part No. A83641-01

Oracle iPayment Concepts and Procedures, Release 11i

Part No. A83641-01

Copyright © 2000, Oracle Corporation. All rights reserved.

The Programs (which include both the software and documentation) contain proprietary information of Oracle Corporation; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is error free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Oracle Corporation.

If the Programs are delivered to the U.S. Government or anyone licensing or using the programs on behalf of the U.S. Government, the following notice is applicable:

Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercial computer software" and use, duplication, and disclosure of the Programs, including documentation, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement. Otherwise, Programs delivered subject to the Federal Acquisition Regulations are "restricted computer software" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR 52.227-19, Commercial Computer Software - Restricted Rights (June, 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065.

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and Oracle Corporation disclaims liability for any damages caused by such use of the Programs.

Oracle is a registered trademark, and Oracle iPayment is a trademark or registered trademark of Oracle Corporation. Other names may be trademarks of their respective owners.

Contents

Send Us Your Comments ................................................................................................................... vii

Preface............................................................................................................................................................. ix

Intended Audience ................................................................................................................................. ixStructure................................................................................................................................................... ixConventions.............................................................................................................................................. x

Understanding iPayment

Welcome to Oracle iPayment ................................................................................................................. 1iPayment Architecture Overview.......................................................................................................... 2Understanding Credit Card Transactions ............................................................................................ 4Understanding Terminal-Based and Host-Based Merchants ............................................................ 5Understanding Bank Account Transfers .............................................................................................. 6Understanding Offline and Online Payments..................................................................................... 8How the Scheduling System Works...................................................................................................... 9Understanding Risk Management ....................................................................................................... 11Risk Factors Shipped with iPayment ................................................................................................... 12

Risky Instruments Upload Utility ................................................................................................. 14iPayment Routing and Operation ........................................................................................................ 15Understanding iPayment Security ....................................................................................................... 16

Implementing iPayment

Development Overview......................................................................................................................... 19Overview of Electronic Commerce APIs............................................................................................. 24 Java APIs for Electronic Commerce Applications............................................................................. 24Implementing Java APIs for Electronic Commerce Application ..................................................... 28PL/SQL APIs For Electronic Commerce Applications ..................................................................... 33Status Update API for Offline Requests .............................................................................................. 35Integrating Risk Management .............................................................................................................. 38

iii

Error Handling During Payment Processing...................................................................................... 39Risk Management Test Scenarios ......................................................................................................... 41Transaction Types ................................................................................................................................... 48BatchState................................................................................................................................................. 49

Administering iPayment

Administration Overview ..................................................................................................................... 51iPayment Administration User Interface ............................................................................................ 51Payment System...................................................................................................................................... 52Creating a New Payment System......................................................................................................... 52Modifying a Payment System............................................................................................................... 53Updating a Default Payment System................................................................................................... 54Payee......................................................................................................................................................... 54Creating a New Payee............................................................................................................................ 55Modifying a Payee .................................................................................................................................. 56Inactivating a Payee................................................................................................................................ 56Updating Risk Management Status ..................................................................................................... 56Risk Factors.............................................................................................................................................. 57Modifying the Risk Score....................................................................................................................... 57Modifying the Payment Amount Limit Risk Factor.......................................................................... 58Modifying the Payment History Risk Factor...................................................................................... 58Modifying theTransaction Amount Risk Factor................................................................................. 59Modifying the Time of Purchase Risk Factor...................................................................................... 60Modifying the AVS Codes Risk Factor ................................................................................................ 60Modifying the Frequency of Purchase Risk Factor ............................................................................ 61Modifying the Oracle Receivables Risk Codes Risk Factor .............................................................. 62Modifying the Oracle Receivables Credit Rating Codes Risk Factor.............................................. 62Modifying the Risky Instruments Risk Factor.................................................................................... 63Modifying the Ship to/Bill to Address Risk Factor ........................................................................... 63Modifying the Oracle Receivables Transactional Credit Limit Risk Factor ................................... 63Modifying the Oracle Receivables Overall Credit Limit Risk Factor.............................................. 64Risk Formula ........................................................................................................................................... 64Creating a Risk Formula ........................................................................................................................ 64Updating a Risk Formula ...................................................................................................................... 65Deleting a Risk Formula ........................................................................................................................ 65

iv

Routing Rule............................................................................................................................................ 66Changing the Routing Rule Priority .................................................................................................... 66Creating Routing Rules.......................................................................................................................... 67Modifying Routing Rules ...................................................................................................................... 68Deleting Routing Rules .......................................................................................................................... 68iPayment Properties ............................................................................................................................... 68Installing and Configuring iPayment Servlets ................................................................................... 70Installing and Configuring iPayment Cybercash Servlet ................................................................. 71Installing and Configuring Verifone PayWorks Servlet .................................................................... 74Installing and Configuring CheckFree ................................................................................................ 78

v

vi

Send Us Your Comments

Oracle iPayment Concepts and Procedures, Release 11i

Part No. A83641-01

Oracle Corporation welcomes your comments and suggestions on the quality and usefulness of this document. Your input is an important part of the information used for revision.

� Did you find any errors?� Is the information clearly presented?� Do you need more information? If so, where?� Are the examples correct? Do you need more examples?� What features did you like most?

If you find any errors or have any other suggestions for improvement, please indicate the document title and part number, and the chapter, section, and page number (if available). You can send com-ments to us via the postal service.

Oracle Corporation CRM Content Development Manager500 Oracle ParkwayRedwood Shores, CA 94065U.S.A.

If you would like a reply, please give your name, address, telephone number, and (optionally) elec-tronic mail address.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

If you have problems with the software, please contact your local Oracle Support Services.

vii

viii

Preface

Welcome to the Oracle Customer Relationship Management, Release 11i, suite of applications.

This Concepts and Procedures provides information and instructions to help you work effectively with Oracle iPayment.

This preface explains how Concepts and Procedures is organized and introduces other sources of information that can help you.

Intended AudienceThis guide is aimed at the following users:

� System Administrators (SA), Database Administrators (DBA), and others with similar responsibility.

StructureThis manual contains the following chapters:

“Understanding iPayment” provides overviews of the application and its components, explanations of key concepts, features, and functions, as well as the application’s relationships to other Oracle or third-party applications.

“Implementing iPayment” provides general descriptions of the setup and configuration tasks required to implement the application successfully.

“Administering iPayment” provides task-based procedures for required for ongoing system maintenance and includes information on administration tools and utilities.

ix

ConventionsThe following conventions are also used in this manual:

Convention Meaning

. . .

Vertical ellipsis points in an example mean that information not directly related to the example has been omitted.

. . . Horizontal ellipsis points in statements or commands mean that parts of the statement or command not directly related to the example have been omitted

boldface text Boldface type in text indicates a term defined in the text, the glossary, or in both locations.

< > Angle brackets enclose user-supplied names.

[ ] Brackets enclose optional clauses from which you can choose one or none.

x

Understanding iPayment

This topic group provides overviews of the application and its components, explanations of key concepts, features, and functions, as well as the application’s relationships to other Oracle or third-party applications.

Welcome to Oracle iPaymentOracle iPayment provides an integrated electronic payment solution for both electronic commerce applications and client-server applications. It provides integrated, user friendly access, and control of payment processing to these applications. iPayment supports two electronic payment methods: credit card payments and bank account transfers. iPayment also supports payment partners like Cybercash, Verifone, and CheckFree.

iPayment offers easy installation, administration, and extension capabilities. The Risk Management functionality of iPayment can quantify and identify the fraudulent online transactions for both business to business and business to consumer models.

Because there are few standards in electronic commerce and payment processing, iPayment supports several routing options, payment methods, processing models, and security features.

Key Benefits of iPayment1. Integrates with many payment processing systems. This feature allows

businesses to offer several payment options to their customers and thus reduce implementation and maintenance costs.

2. Provides rules based payment processing. This feature allows businesses to incorporate their existing business operations, rules, and procedures and lower costs by controlling relationships with payment processing vendors.

Understanding iPayment 1

iPayment Architecture Overview

3. Provides security through support for industry standards such as SSL (Secure Socket Layer), and SET (Secure Electronic Transaction).

4. Integrates with other Oracle applications, such as, Oracle iStore, Order Management, and Oracle Receivables and a single, open application programming interface (API) to integrate with any web-based, or client-server application.

5. Provides support for both single and multi-site installations of electronic commerce or client-server applications. iPayment also allows both stand-alone businesses and internet service providers to offer electronic payment processing.

iPayment Architecture OverviewiPayment can be integrated with any electronic commerce or client-server application. The integrated iPayment component can communicate with Oracle database and other servlets to provide payment processing.

iPayment Architecture

2 Oracle iPayment Concepts and Procedures

iPayment Architecture Overview

iPayment APIsiPayment provides two application programming interfaces (APIs) to simplify the integration of existing or new applications with iPayment for payment processing.

� Electronic Commerce APIElectronic commerce applications can use this API to integrate their applications with iPayment. The electronic commerce application can be a servlet that plugs into any application server, or it can be a stand-alone application that communicates with iPayment via Java APIs or via PL/SQL APIs.

� Payment System APIDevelopers can use this API to create payment system servlets. These servlets are usually interfaces that link the payment system software to iPayment to facilitate electronic payment processing.

iPayment ServletsiPayment consists of the following servlets:

� ECServlet

The ECServlet provides an interface to the iPayment engine to process payment related operations like authorization, capture, return etc. This servlet is basically used for the PL/SQL APIs provided by iPayment.

� Payment System servlets

iPayment provides a complete payment solution, bundling payment system servlets developed by Oracle and its payment system partners. The payment systems communicate with the payment processors and the acquirers/banks to process payment transactions. iPayment includes payment system servlets for Cybercash and Verifone Payworks.

� Field-Installable servlets

iPayment supports field-installable servlets. These are payment system servlets not bundled with iPayment. This feature allows a payee to acquire a new, additional, or upgraded payment system servlet and configure it in the same way as the payment system servlets bundled with iPayment.

The ability to add field-installable servlets provides payment flexibility and allows new releases of iPayment and the payment systems to be independent of each other. It also enables electronic commerce applications to customize the payment system for their specific needs and regions.


Understanding Credit Card Transactions

Field-installable payment system servlets for iPayment are usually available from Oracle’s payment system partners.

Understanding Credit Card TransactionsiPayment handles both credit card transactions and bank account transfers. The following information explains the process flow for a typical credit card transaction.

Traditional Credit Card TransactionsTraditional credit card transaction processing involves a customer, a payee, an acquiring bank or processor, and an issuing bank.

A traditional credit card transaction consists of three phases: authorization, settlement, and reconciliation.

� Authorization

The customer purchases goods or services and sends credit card information and payment instructions to the payee or business.

The payee accepts the authorization request and sends it to the credit card processor through iPayment and the payment system.

The processor matches the information with a database maintained by the card issuer (such as Visa or MasterCard) to determine if the customer has enough funds available to cover the transaction. If the funds are available, then the processor reserves the funds and sends back an authorization code.

� Settlement

Settling transactions includes capturing authorized transactions, processing voids and returns, and batch administration.

The payee issues capture, void, return, credit, and close-batch functions to the processor through iPayment and the payment system.

The processor settles the payment with the issuing bank and causes the funds to transfer to the acquiring bank.

� Reconciliation

Depending on the agreement between the payee and the acquiring bank, the acquiring bank sends daily, weekly, or monthly reports to the payee for reconciliation.


Understanding Terminal-Based and Host-Based Merchants

The payee cross-checks transaction information in the database with the bank statement for reconciliation.

SET Credit Card TransactionsThe Secure Electronic Transaction (SET) 1.0 protocol is an open standard developed jointly by Visa and MasterCard to ensure the privacy and security of credit card transactions over open networks such as the internet. By using special encryption techniques and digital certificates issued by financial institutions, SET ensures that the customer is authorized to use the specified credit card and the payee is authorized to accept payment from the specified credit card. SET also maintains the customer’s privacy by sending information in an encrypted form based on the certificate, without disclosing credit card information to the payee.

SET credit card transactions follow the same basic process as a traditional credit card, except that digital certificates are exchanged and verified at the beginning of each operation. For example, when the customer authorizes payment for an order, the customer’s software first requests the payee’s digital certificates. After verifying the authenticity of the certificates, the customer’s software sends the order information and encrypted payment instructions to the payee. SET also requires that all authorization transactions are initiated by the customer.

To use SET with iPayment, the electronic commerce application and payment system must be SET-compliant. When configuring iPayment, you must specify whether or not a payment system uses SET. In addition, the customer should have a SET-compliant electronic wallet application running with the browser. The electronic wallet contains the customer’s credit card information, digital certificates, and cryptographic keys.

Understanding Terminal-Based and Host-Based MerchantsThe financial industry uses two processing models for credit card transactions: terminal-based merchant and host-based merchant. iPayment supports both. The following information describes these two processing methods.

� Terminal-Based Merchant Description

Note: iPayment does not have out of the box payment system that supports SET. This needs to be done by custom implementations using the payment system APIs that are published by iPayment.


Understanding Bank Account Transfers

The payee or business determines when to close batches of transactions for clearing and settlement and is responsible to perform close batch operation.The payee or business has more flexibility.

� Host-Based Merchant Description

In this model, the processor’s host maintains all the transactions and is usually responsible for close-batch operation at a predetermined frequency. The payee or business does not have to perform close-batch operations. Corrections, such as returns and voids, are sent as new transactions to the host.

Why Is This Important?The choice of being a terminal-based or host-based merchant is generally determined by the business type, number of transactions per day, and the model supported by the acquiring bank. The processing model you choose affects how you perform the settlement operations. For a terminal-based merchant model, you have to perform close batch operations periodically. Consult your acquirer for more information at the time of signing up.

Understanding Bank Account TransfersiPayment supports bank account transfers for both business-to-consumer and business-to-business models. Account transfer functionality facilitates electronic transfer of payment amounts from a customer’s bank account to the payee’s bank account using the ACH (Automated Clearing House) network. Electronic commerce applications use iPayment as their interface to payment processors that provide connectivity to the ACH networks. iPayment integrates with CheckFree and CyberCash’s PayNow service to provide this new feature.

The number of operations supported in bank account transfers are fewer than those supported for credit card payments because of the current practices and processes involved in processing account transfers. You cannot receive real time response for bank account transfers due to the current practices in account transfer processing. The only status that can be provided is whether the payment was submitted to the processing network or not. iPayment only supports Offline payments for account transfers. See Understanding Offline and Online Payments for more information.

Interface with Electronic Commerce ApplicationsElectronic commerce applications can use the same API for both credit card payments and bank account payments. iPayment routes the request to the correct back-end payment system.


Understanding Bank Account Transfers

The operations that are supported for bank account transfers are merged into the same framework of operations that are supported for credit card payments. The following operations are supported for bank account transfers:

� Payment Request

� Payment Modification

� Payment Cancellation

� Payment Inquiry

� Payment Query Transaction Status

Process flow of Bank Account Payment Request:1. The electronic commerce application calls the iPayment API to schedule an

Offline bank account transfer payment request.

2. All bank account transfer payments need some lead time before the settlement date. At the time of an API call, iPayment determines whether the payment request can be settled on the requested date or not, based on the lead time of the payment system.

3. If it can be settled, then iPayment accepts the payment request. Otherwise, based on the API parameters, iPayment either rejects the payment request or accepts the payment request with a different settlement date.

4. A scheduled Offline payment request can either be modified or canceled before it is routed to the payment system.

5. Once a request is routed to the payment system, the electronic commerce application can neither modify nor cancel the request.

6. The Payment system routes the payment to the ACH network.

7. If there is any failure on the ACH network or at the payment system site while processing the payment, then the payment system updates iPayment with those errors.

8. Finally, iPayment updates the electronic commerce application with all the status changes of the payment request.

Note: Certain credit card operations are not supported for bank account transfers.


Understanding Offline and Online Payments

Two payment systems, Checkfree and Cybercash’s Pay Now support bank account transfers. These are bundled with iPayment. See Installing and Configuring iPayment Cybercash Servlet and Installing and Configuring Checkfree for more information.

Understanding Offline and Online PaymentsiPayment supports two models of payment processing:

� Online Payment Processing

� Offline Payment Processing

Online Payment ProcessingOnline payment processing is the model in which payment processing is immediately forwarded to the back-end payment processor. The results from the processor are immediately returned to the electronic commerce application.

Offline Payment ProcessingOffline payment processing is a new feature in iPayment. In this model, payment requests are not immediately forwarded to back-end payment processors. When an electronic commerce application makes a payment processing request in an Offline mode, the payment information is saved in the iPayment database and is sent to the payment processor later.

The Offline method uses a Scheduler, a utility that functions at regular intervals. The Scheduler browses the stored requests and sends requests to the back-end payment systems and updates to the electronic commerce applications.

An Offline bank account payment request in iPayment, at any given time, can be in one of the following states:

� Pending: After the electronic commerce application schedules and before routing to the payment system.

� Scheduled: After routing to the payment system.

� Submitted: Once the payment system submits the request on to banking network, for example, ACH network.

� Canceled: When a pending payment is canceled.

� Failed: Failed due to technical errors.

� Unpaid: Insufficient funds.


How the Scheduling System Works

The status of a payment is determined on the status of the payment request. To obtain the status of a payment request, electronic commerce applications can call the Query Transaction Status API.

The following diagram shows the state diagram of an Offline Payment Request.

State Transition diagram of an Offline Payment Request

How the Scheduling System WorksiPayment allows the electronic commerce applications to submit payment related requests for scheduling. iPayment’s scheduling system periodically checks the


How the Scheduling System Works

database for pending payment processing requests and routes them to the appropriate payment system.

Scheduling System Flow 1. When iPayment receives a payment request, it determines which payment

system should be used to process this payment request, based on routing rules.

2. iPayment stores the payment request in the database to schedule the payment at a later time.

3. At a configured time, the scheduling system scans the database for pending requests which have to be scheduled based on the settlement date. The Scheduler also creates a list of the payments to be made and the payment system to be used for each request. The time interval can be configured in a cron job. The payments are scheduled depending on the requested dates.

4. The scheduling system sends the payment request to the appropriate back-end payment system.

5. The back-end payment system processes the payment request and sends the response containing the payment status back to the Scheduler.

6. The Scheduler updates the payment status in iPayment database and updates the electronic commerce application via the Updatestatus API implemented by the electronic commerce application.

Configuring the Scheduler as a Cron JobThe scheduling system runs at configured intervals to send payment requests to the back-end payment system.

Steps1. Use the crontab command available in the UNIX system.

2. The UNIX cron command starts a process that executes commands at specified dates and times. Regularly scheduled commands can be specified according to instructions found in crontab files in the following directory:/var/spool/cron/crontabs.

3. Users submit their own crontab file using the crontab command. For example, to invoke the Scheduler at 12 AM everyday, enter the following line in the user’s crontab file:

0 0 * * * <JAVA_PATH>/java -classpath <AU_TOP>/java/apps.zip:<JAVA_CLASSPATH> \oracle.apps.iby.scheduler.SchedInitiator \


Understanding Risk Management

http://<ipayment_site_hostname.com>:<portnumber>/

� <JAVA_PATH> is the path where the java executables are located.

� <AU_TOP> is the actual path where the apps.zip file is located.

� <JAVA_CLASSPATH> is the standard java classpath for the current installation where classes.zip files are located.

For example: /usr/java/lib/classes.zip

� <ipayment_site_hostname.com> contains the value for the host where iPayment is installed. For example: www.myipayment.com

� <portnumber> contains the actual portnumber. For example: 8000.

4. Set the crontab using the following command:

crontab <filename_in_which_above_line_is_placed>

5. Now the Scheduler is invoked at 12 AM everyday.

Understanding Risk ManagementiPayment provides Risk Management functionality for electronic commerce applications for both business-to-business and business-to-consumer models. iPayment includes a number of built-in risk factors and provides the option to the payees to run or not run the risk evaluation functionality for each payment operation. Payees can also run the risk evaluation for operations which handle amounts exceeding a specified amount.

A risk factor includes any information which a payee wants to use to evaluate the risk of the customer wanting to buy goods or services from the payee. Examples of risk factors are: Address Verification, Time of Purchase, Payment Amount, etc. These risk factors can be configured for each payee (merchant or biller).

Risk Management functionality enables payees and electronic commerce service providers to manage the risk involved in processing transactions online. It allows businesses to have any number of predefined risk factors to verify the identity of their customers, assess their customer credit rating, and risk rating in a secure environment.

A payee can associate the risk factors with different weights as a formula and define any number of risk formulas in iPayment based on his/her business model. When Payment Request API is called, the electronic commerce application can specify which formula to be evaluated to verify the identity of their customers, assess their


Risk Factors Shipped with iPayment

customer credit rating, and risk rating in a secure environment. Depending on the response from iPayment, electronic commerce application has to decide whether to process the payment request or to reject it.

Risk Management helps businesses in reducing manual operational overheads to handle bad transactions and in avoiding costly penalties like charge backs from banks. For more information, see Integrating Risk Management.

Risk Factors Shipped with iPaymentThe following is a list of basic risk factors shipped with the Risk Management component. These risk factors can be configured per payee.

1. Payment Amount Limit is the amount involved in the payment request. It varies from business to business and the risk factor score can be configured for different amount ranges based on the business model.

2. Time of Purchase is the time at which the payment request is made by the customer. Statistics reveal that most of the fraudulent purchases are made at midnight. Site administrators can define the time duration during which the payment requests are high risk and assign the risk factor scores for each duration.

3. Ship To/Bill To Address is used to match the ship to address to the bill to address in the payment request. A payment request is considered high risk if these two addresses do not match.

4. Risky Payment Instruments are a list of payment instruments that are considered risky by each payee. These include the instruments that were used by customers earlier and had resulted in fraud or chargebacks. Such a list can be generated internally by the payee or obtained from other sources. If these instruments are reused in a payment request, then the payee may again face fraud or chargeback. Risk Management functionality can detect if risky payment instruments are being used during processing by looking at the risky instrument repository. If the instrument being used for the payment is found in the repository, then the payment is considered a high risk payment. The Risky Instruments Upload Utility adds and deletes a list of risky instruments from the database. See Risky Instruments Upload Utility for more information.

5. Transaction Amount is the total amount of payments made by a customer using the same instrument in a specified duration of time. The duration of time is setup by the user. This is related to the Payment Amount Limit risk factor. A customer can make payments in smaller amounts, which are not captured by the Payment Amount Limit risk factor but can be captured by the Transaction



Amount risk factor. Transaction Amount risk factor sums up the total amount of payments in a specific duration of time and captures the risk on that amount. The Transaction Amount is an amount limit for a specified duration of time. The total number of payments made during a specific time period can be checked by looking at the payment history. The site administrator can set up a time duration and a Transaction Amount. In evaluating this risk factor, if the total payment amount exceeds the Transaction Amount within the specified time duration, then the payment is considered a high risk payment.

6. Payment History is the frequency with which a customer makes payments in a time duration setup by the user. The risk score depends on that frequency. By looking at the payment history, you can determine the frequency with which a customer makes payments or purchases. Based on the frequency value, risk score values can be configured. If the customer has made many payments in the last few months, then he/she is a reliable customer and has a low risk score.

7. Address Verification Service (AVS) Check is the risk involved on the AVS code that is returned by the credit card network. Address Verification Service is provided by Mastercard and Visa credit card networks to match the billing address with the address that is maintained for the cardholder by the issuing bank. Various AVS codes are returned based on the complete address match, zipcode match, street address match, etc. A site administrator can configure all AVS codes returned by the payment systems and their corresponding risk factor scores. This service is only provided in US.

8. Frequency of Purchase determines the frequency of payments in a specific time duration. When a payment request is received, the Risk Management module can determine the frequency at which a customer is buying in the specific time duration by looking at the payment history. If the frequency value increases more than the configured value, the payment becomes a high risk payment for a consumer who did not have a similar pattern before. The site administrator can setup the time duration, the frequencies, and their corresponding risk factor scores through the iPayment administration user interface.

Oracle Receivables Risk FactorsFor customers who have both iPayment and Oracle Receivables installed and registered, more risk factors are available. These risk factors are setup in iPayment and the values of these risk factors are setup in Oracle Receivables. Oracle Receivables stores credit management information about customer accounts like credit rating, risk rating, etc. These are used in risk analysis.

1. Credit Limit is an overall credit limit associated with a customer’s account. If a customer has an outstanding balance and the total amount of payment made by



the customer exceeds the overall credit limit, then the payment becomes a high risk payment. Overall credit limit varies from business to business. It can be set up as an overall credit limit at the customer or site level through Oracle Receivables.

2. Transaction Credit Limit is the credit limit per transaction associated with a customer’s account. When a payment request exceeds the transaction credit limit, it becomes a risky payment. The transaction credit limit varies from business to business. It can be set up at the customer or site level through Oracle Receivables.

3. Credit Rating is the information that enables payees to effectively manage financial terms with their customers. It is useful for online financing or in evaluating purchases of a large amount by a new customer. It is a user defined field and the information can be taken from Oracle Receivables. A payee associates risk scores to credit rating. A higher risk score implies that selling goods/services to the customer is risky.

4. Risk Code is a user defined risk assessment field in Oracle Receivables. It is useful for online financing or for evaluating purchases of a large amount for a new customer. The information is available from Oracle Receivables. A payee associates risk scores to all the risk codes. A higher risk score implies that selling goods/services to the customer is risky.

Risky Instruments Upload UtilityThe upload utility is a Java application used to store risky payment instruments. It is called RiskyInstrUtil.

Requirements1. Java Developer Kit 1.1.6

2. <AU_ TOP>/java/apps.zip has to be in the CLASSPATH

Java Commands java oracle.apps.iby.irisk.admin.RiskyInstrUtil [add/delete] [filename]

This command requires an operation and a filename. It modifies the risky instrument table in the database depending on the entries in the file.

Or

java oracle.apps.iby.irisk.admin.RiskyInstrUtil delete all


iPayment Routing and Operation

This command deletes all the risky instruments in the table.

File Format � Each line corresponds to one risky instrument.

� The fields are comma separated and are in the following order: Payee identifier (PayeeID), instrument type, and creditcard number. Instrument type has to be CREDITCARD. For example:

� payee1, CREDITCARD, 4500234023453345

� For the add operation, each risky instrument in the file, that has a valid payee identifier, instrument type, and a new credit card number is added to the table.

� For the delete operation, each risky instrument that matches the payee identifier, instrument type, and the credit card fields is deleted from the table.

� The command prints the results of the operation on each risky instrument in the file.

iPayment Routing and OperationiPayment accepts payment instructions from the electronic commerce application and routes them to the appropriate payment systems. The customer uses a web browser or client application to exchange data with a web or server-based electronic commerce application. This application sends payment requests to iPayment. Finally, iPayment routes the payment requests to the appropriate payment systems.

How Routing WorksRouting of a payment transaction is based on a set of routing rules set up on the iPayment user interface by the iPayment Administrator. A routing rule can have two conditions:

� One is based on the amount of the payment request.

� Other is based on the instrument type used in the payment request.

Routing rules are prioritized by an administrator. During processing, the rules are evaluated in the order in which they are prioritized.

If the values of a transaction satisfy both conditions of a rule, then the transaction is routed to the payment system associated with that rule. The rest of the rules are not evaluated for that particular payment request.


Understanding iPayment Security

If none of the rules match the transaction values, then the transaction is routed to a default payment system, set up by the administrator, based on the instrument type used in the payment request.

If an electronic commerce application needs to override the routing scheme, then it could process its own routing logic and send a routing rule name to iPayment. iPayment uses that routing rule name to find a payment system. In this case, a rule can be set up without any conditions and this rule is not used during evaluation.

The rule name should be the name of one of the routing rules which the administrator has set up. If the rule name is not the name of one of the routing rules that have been set up, then the transaction is routed to a default payment system.

iPayment supports credit card payments and bank account transfers. The payment methods available depends on the payment system that you decide to use.

Payees and businesses can customize how iPayment routes transactions to the payment systems using routing rules based on their business rules and the available payment methods. For example:

� A business sends all electronic payment transactions to a single payment system: Payment System A.

� A payee sends all small or micropayment transactions to Payment System A and all credit card transactions to Payment System B.

� A business sends all bank account transfers under $10 to Payment System A, and all other transactions to another payment system B.

Understanding iPayment SecurityThe following security features are recommended to guard against unauthorized access to data and iPayment services. In addition, Apache Server provides several types of authentication that you can use to secure servers, listeners, and servlets.

1. Firewall Protection

2. Secure Socket Layer (SSL) using Oracle Wallet

3. Basic Authentication for Payment Systems

4. IP Address Restriction

Firewall ProtectionOracle strongly recommends that you install iPayment and the payment system servlets on a machine inside the firewall.



Oracle also recommends that you use one of the following two configuration options to further reduce the risk of data being intercepted as it passes between different parts of iPayment:

� Install all the following components on the same machine:

� iPayment

� Payment system servlet

� Electronic commerce application

� Or, use Secure Socket Layer (SSL) to connect distributed components

Secure Socket Layer Using Oracle Wallet If either iPayment (or its components) or the electronic commerce application is installed in a distributed environment, then Oracle recommends configuring SSL between iPayment and the payment system components.

Setting Up SSL SecurityWhen iPayment communicates with payment system servlets, the information exchanged may be sensitive information such as credit card numbers. If the communication is not secured, it poses a security risk.

The security risk increases in the following circumstances:

� If iPayment and the payment systems are installed on separate machines

� If iPayment is running outside your firewall

Steps� To Set up a back-end payment system servlet with Secured Sockets Layer follow

the procedures in Apache Server documentation (http://www.apache.org/docs) or SSL documentation. Make sure that your SSL server has a complete certificate chain to the root certificate. SSL’s client toolkit requires it.

� Set up the BASE URL parameter of back-end payment system with https.

Basic Authentication for Payment SystemsFor setting up security for basic authentication, you have to perform some tasks both in iPayment administration user interface and in Apache Server administration tool. While configuring iPayment for a particular payment system using the iPayment administration user interface, you have to assign the payment system



username and password in the Payment System Configuration screens. You have to assign the same username and password in Apache Server.

For details on setting up basic authentication in Apache Server, refer to your Apache Server documentation.

IP Address RestrictionIn addition to using the merchant username and password, you can restrict access to iPayment and payment systems through IP address restriction. By using IP address restriction, a feature of the Apache Server, you can specify one or both of the following parameters:

� The IP addresses of all trusted hosts (machines whose requests of iPayment the web server should accept).

� The IP addresses of some non-trusted hosts (machines whose request of iPayment the web server should refuse).

If a request is from a machine on the trusted list, iPayment processes the requested transaction. If the request is from a machine on the non-trusted list, Apache Server denies the request and prevents iPayment from processing it.

Through IP address restriction, you can limit access to all operations from non-trusted machines.

For more information about IP address restriction, including how to specify trusted hosts, see Apache Server documentation.

Other Security Related Information1. iPayment is bundled with electronic commerce applications, executing as one

application through the use of Java APIs. This prevents network transfer of sensitive information between electronic commerce applications and iPayment.

2. Separate HTTP ports for site administration and iPayment administration increases security.

3. Communication with back-end payment systems is via SSL.

4. Bank account transfers are supported via account transfers interface. The payment system must be implemented using Java APIs directly and executed in the same process space to avoid network transfer of sensitive information between iPayment and payment systems.


Development Overview

Implementing iPayment

This topic group provides general descriptions of the setup and configuration tasks required to implement the application successfully.


What to Do Before You CodeBefore you begin using the APIs, you must make several key decisions:

� Which APIs should electronic commerce applications handle?

� Does your application need to present information in different languages?

The following sections help you find answers to these questions. Your answers determine which APIs you should use, which parameters you must pass, and which code samples are relevant to your applications.

Which APIs should electronic commerce applications handle?iPayment provides Payment Instrument Registration APIs for registering payment instruments such as credit cards and bank accounts. It also provides Payment Transaction APIs that can perform credit card operations, like, authorization, settlement, reconciliation, and bank account transfers. Based on your requirements, you have to decide which operations your electronic commerce applications need to implement.

� Payment Instrument Registration APIs

These APIs are mandatory if you decide to use the Offline payment processing feature of iPayment Payment APIs in your electronic commerce application. Electronic commerce applications can implement registration of payment instruments using Payment Instrument Registration APIs, and instrument identifiers, that are generated, during payment requests with iPayment.

� Payment Transaction APIs

You have to decide whether to

� implement Online or Offline payment processing or both.

� accept credit card payments or bank account transfers or both.

Implementing iPayment 19


� integrate the risk functionality to detect fraudulent transactions.

The following information describes some of the decisions you have to make in case you are accepting bank account transfer payments or in case you are accepting credit card payments.

Which Bank Account Transfer Operations should you implement?iPayment only supports Offline bank account payment requests. Besides payment requests for bank account transfers, iPayment also supports modification, cancellation, and inquiry operations. For more information about bank account support and APIs, see Understanding Bank Account Transfers and Overview of Electronic Commerce Application APIs.

Which Credit Card Operations to Implement?iPayment provides APIs for authorization, settlement, and reconciliation. You do not have to use all these APIs. You can choose to have your electronic commerce application handle only authorization, thus reducing development costs but requiring the payee to do more work for settlement and reconciliation.

The following table compares the two approaches.

Is Your Merchant Terminal Based or Host Based The choice of being a terminal-based or host-based merchant is generally determined by the business type, number of transactions per day, and the model supported by the acquiring bank. As a developer of an electronic commerce application, you only need to know the type of payee for which you’re developing the application, so that you can choose the appropriate APIs.

Comparison of Authorization Only with Authorization and Settlement

Authorization Only Authorization and Settlement

The integration effort is relatively minimal because you have to use no more than two APIs.

The integration effort is significant because you have to use several APIs.

The payee has to settle transactions through the native payment system administration tool. (For example, by going to the payment system’s web page).

The payee can settle transactions directly through the electronic commerce application.

The payee has to perform synchronization or query because the iPayment database is not completely up-to-date.

Reconciliation can be performed through the iPayment database.



If your payee is terminal-based, then you may want to integrate the Close Batch API into the electronic commerce application, thus enabling the payee to do close batches through the electronic commerce application instead of the payment system’s native interface. If, your payee is host-based, then you may want to ignore the Close Batch API because the processor automatically closes batches at predetermined intervals.

If the payee is host-based, then payment capture takes care of getting the payment, and reconciliation is not necessary. Therefore, the Close Batch API and the Query Batch Status API are not required for host-based payees.

Does Your Application Need to Present Information in Different Languages?If your application needs to present information in different languages or character sets, then you need to know about national language Support (NLS).

Would Your Application Need National Language Support (NLS)?Your application may need to use NLS if either of the following is true:

� The electronic commerce application and the payment system use different languages or character sets. For example, the electronic commerce application may use a Japanese EUC character set while the payment system uses a Japanese Shift-JIS character set.

� Clients of the electronic commerce application use different languages. For example, a web site that is expecting customers from all over the world might want to present its electronic commerce application in different languages for different customers.

To enable character conversion in all these environments, the electronic commerce application and the payment system must convey the language and character set information to iPayment.

How do Applications Convey Language Information to iPayment?To communicate information about the language and character set to iPayment, an electronic commerce application and payment system servlet must pass a special parameter (NlsLang). This parameter is a part of every API included in this guide.

NlsLang is an optional parameter. If your electronic commerce application does not need to handle non-Latin1 character set parameters and does not need to communicate to clients or payment systems in different languages, you do not need to use this parameter.



How does iPayment Use NlsLang?If the electronic commerce application does not pass the NlsLang parameter, iPayment passes information from the electronic commerce application to the payment service servlet without performing any conversion of character sets.

If the electronic commerce application does pass a value for NlsLang to iPayment, then iPayment tries to convert parameters based on the value of NlsLang before sending those parameters to the payment system servlet.

To do so, iPayment first checks its database for the list of preferred and optional languages for that payment system. The information in the database reflects what the iPayment administrator entered using the iPayment administration user interface.

Second, iPayment does one of the following, depending on what it finds in the database:

� If the database lists a language that matches the value of NlsLang, iPayment keeps the value of NlsLang and passes it to the payment system servlet.

� If the database does not list a language matching the value of NlsLang, iPayment uses the language specified as the preferred language for that payment system, thus changing the value of NlsLang before sending it to the payment system servlet.

Finally, iPayment converts the values of other parameters so that they are sent to the payment system servlet in the language specified by NlsLang.

This conversion process works only in one direction. From the electronic commerce application to the payment system servlet. If the payment system sets up NlsLang when it sends the data back, iPayment uses that information only to store the value of OapfVendErrmsg in its database. iPayment does not convert data sent from the payment system servlet back to the electronic commerce application.

Format of the NLS_LANG ParameterThe value of this parameter follows the same format as Oracle Server’s NLS_LANG environment variable:

language_territory.charset

For example, JAPANESE_JAPAN.JA16EUC is a valid value for NlsLang.



Format of the Response Body Data From Payment System ServletsiPayment does not convert the response received from the payment system servlet in the response body. It only treats the data as binary and sends it directly to the electronic commerce application.

However, if any binary information is sent (such as wallet data), then iPayment converts the character set of the binary data to that specified by the value of NlsLang.

Electronic Commerce Application RegistrationAll the APIs that an electronic commerce application calls must pass its identifier. This allows iPayment to track the application from where the requests are coming. The identifier generated during registration must be stored by the application and the electronic commerce application should pass the identifier in the API calls. iPayment provides a ECConfig utility, to add, modify, or list electronic commerce applications.

Requirements for Setting up and Using the ECConfig Utility� Java executable of JDK 1.1.6.

� $AU_TOP/java/apps.zip should be in your CLASSPATH environment variable.

Using the EcConfig Utility� To add an electronic commerce application, use the following command:

java oracle.apps.iby.ecapp.EcConfig add “Ec App Name” “Short Name” Example: java oracle.apps.iby.ecapp.EcConfig add “my ec application” “myapp” � To modify a registered electronic commerce application, use the following

command:

java oracle.apps.iby.ecapp.EcConfig modify <id> 'Ec App Name' 'Short Name' <id> is the identifier of the electronic commerce application that was generated while adding the electronic commerce application. You can also retrieve the identifiers of applications using the list command.

Example: java oracle.apps.iby.ecapp.EcConfig modify 1234 “ec app name” “ecapp” � To list all the registered electronic commerce applications use the following

command:

java oracle.apps.iby.ecapp.EcConfig list


Overview of Electronic Commerce APIs

Overview of Electronic Commerce APIsiPayment integrates with the following APIs:

� Java APIs for Electronic Commerce Applications

� PL/SQL APIs for Electronic Commerce Applications

The following diagram shows the integration of APIs with iPayment.

iPayment integrating with APIs

Java APIs for Electronic Commerce ApplicationsElectronic commerce applications can embed the iPayment functionality within their application. This eliminates the need of accessing iPayment as a stand-alone application and hence improves performance and simplifies setup.

This section describes the various APIs that are provided to electronic commerce applications for using the features of iPayment. The APIs have been categorized in two categories: Administration APIs and Payment Processing APIs.

Administration APIsAdministration APIs provide the functionality to register, define, and query the various modules within iPayment. Various modules that can be queried are: the electronic commerce application, the payment instrument, etc. These APIs are


Java APIs for Electronic Commerce Applications

used by an electronic commerce application to set up iPayment for processing payments.

Electronic Commerce Application Registration APIsThere are individual APIs to register, modify, and query an electronic commerce application.

� OraECAppReg

This API allows an electronic commerce application to register with iPayment. iPayment can generate a unique identifier (ECAppId) for this request. This identifier is returned to the electronic commerce application. This identifier is used in payment and administration interfaces.

� OraECAppMod

This API allows modification of the information about the electronic commerce application stored in the database. Electronic commerce application is identified by the ECAppId.

� OraECAppInq

This API is provided by iPayment and is used to inquire the information about a registered electronic commerce application. This API returns the information corresponding to the ECAppId.

Payment Instrument APIs A set of APIs are provided to register a payor’s bank or credit card. A user can be a Payee (i.e. a merchant) or a payor (the customer).

� OraInstrAdd

This API is provided to register a user’s bank or credit card account information with iPayment. iPayment generates a PmtInstId if this registration is successful. This identifier is used for payment transactions or for deleting, modifying, or inquiring about this account. Instrument number (credit card number or bank account number) and payor identifier together have to be unique.

� OraInstrMod

This API is provided to modify registered payment instrument account information with iPayment.

� OraInstrDel



This API is provided to delete registered payment instrument account information.

� OraInstrInq

There are two inquiry APIs. One queries instrument information for a single given instrument. The other queries all registered payment instruments for a given payor. The result may contain a mix of credit cards or bank accounts.

Payment Processing APIsThese APIs are the transactional APIs which support various payment operations. The electronic commerce applications use these APIs to process various transaction types. For example, authorization of credit cards, transfer of funds from one bank account to another, capture, cancel, return, etc. A list of such APIs are provided below.

� OraPmtReq

When an electronic commerce application is ready to invoke a payment request (possibly due to a user action) it calls this API. If the operation is successful, a transaction Identifier is generated by iPayment and is returned as part of the result. This transaction identifier can be used later by the electronic commerce application to initiate any other operation on the payment. For example, to modify a payment or capture the payment, the electronic commerce application sends this identifier with other information that is needed to perform the operation requested.

If a payee is risk enabled, electronic commerce application should check transaction identifier and the RiskResponse object that is returned as part of the payment response object to the payment request API. This object contains information about the risk involved in the payment request. Electronic commerce applications can also invoke overloaded payment request API to evaluate a specific risk formula by passing PaymentRiskInfo object.

� OraPmtCanc

A scheduled payment can be canceled by an electronic commerce application using this API.

� OraPmtQryTrxn

Note: This API supports authorization and authorization with capture for credit card payments.



This API provides interface for inquiring the status or history of a payment to electronic commerce application. If a payment has been scheduled and the payment system supports an inquiry operation, the latest status is obtained from the payment system. Otherwise it sends the latest status of the payment as it is in iPayment. History of a payment can also be obtained.

� OraPmtCapture

When a credit card is used as part of a payment request and only an authorization is requested, the electronic commerce application has to capture the payment at a later time. The following APIs allow the electronic commerce application to capture all such payments.

� OraPmtReturn

This API is used for credit card specific operations. It allows processing returns from the payor.

� OraPmtInq

This API retrieves the payment related information that was sent at the time of a payment request (OraPmtReq API). This information includes payment instrument, payee, tangible (bill or order), and payor. If the electronic commerce application does not store the payment information, then this is a useful API to support modification of payment requests. It can retrieve the payment information and display it to the end user for modification.

� OraPmtVoid

This API allows electronic commerce application to void operations submitted earlier. OraPmtVoid API is supported only to void certain credit card operations. iPayment supports both Online and Offline OraPmtVoid API calls.

� OraPmtCredit

This API provides a credit operation. Electronic commerce applications can use this API to give stand-alone credit to the customer. If the operation is successful, a transaction identifier is generated by iPayment. This Identifier is used later to initiate any other operation on the payment. For example, to cancel the credit, electronic commerce application sends this identifier with other information that is needed to perform the cancellation.

� OraPmtCloseBatch

The Close Batch API allows a payee or an electronic commerce application to close a batch of previously performed credit card transactions. The transaction types that are included in a batch are: capture, return, and credit. This operation


Implementing Java APIs for Electronic Commerce Application

is mandatory for a terminal-based merchant. A host-based merchant may not have to explicitly close the batch because the batch is generally closed at predetermined intervals automatically by the processor. An electronic commerce application has to get this information from its merchant’s acquirer.

� OraPmtQueryBatch

This API provides an interface to the electronic commerce application to query the status of an existing batch and a closed batch.

Implementing Java APIs for Electronic Commerce ApplicationAll administration and payment processing functionality described in Java APIs for Electronic Commerce Applications are provided via the Java PaymentService interface. The following information describes how to access and use Java APIs. Refer to Java Developer’s Guide for more details.

Obtaining /Releasing the Payment Service Handle The OraPmt class offers convenient ways to obtain Payment Service handle(PaymentService) for the user. The application can call various APIs using this handle.

� To obtain the payment service handle, use the following method:

static public PaymentService init() throws PSExceptionThis API provides Payment Service handle to the user and takes care of all the necessary session initialization steps.

� To release a Payment Service handle with the session, use the following method:

static public void end() throws PSException

Sample codeThe following code gives an example of how these APIs are used.

public static void main(String[] args) { try { PaymentService paymentService = OraPmt.init(); // now you can call all kinds of APIs //PSResult result = paymentService.OraPmtReq(...); } catch (PSException pe) { // exception handling



System.out.println("Error code is: " + pe.getCode()); System.out.println("Error message is: " + pe.getMessage()); }

finally { try { OraPmt.end(); } catch (PSException pe) { // exception handling System.out.println("Error code is: " + pe.getCode()); System.out.println("Error message is: " + pe.getMessage()); } } }

Checking Returned Result from Payment Service APIPSResult is the returned object of all PaymentService APIs. To obtain the status of the operation, use the following API:

Public String getStatus();This API returns one of the following constants:

PSResult.IBY_SUCCESS// action succeededPSResult.IBY_WARNING// action succeeded with warningPSResult.IBY_INFO// not yet in usePSResult.IBY_FAILURE// action failed

If SUCCESS or WARNING is invoked, a result object can be obtained by using the following API:

Public Object getResult();The actual object returned varies with each API. It could be an integer or one of the payment response objects. You need to clearly cast it. For a list of castings, refer to the iPayment Java Documentation for the PaymentService interface.

If WARNING or FAILURE is invoked, a warning or error message will be returned. Use the following two APIs to retrieve error codes and error messages.

PublicString getCode();// get the error code ’IBY_XXXXXX’PublicString getMessage(); // get the error message text The following sample code illustrates the behavior of PSResult object.

public Object checkResult(PSResult pr) {



String status = pr.getStatus(); if (status.equals(PSResult.IBY_FAILURE)) { // in case of failure, only error message is expected System.out.println("error code is : " + pr.getCode()); System.out.println("error message is : " + pr.getMessage()); return null; }

if (status.equals(PSResult.IBY_SUCCESS)) { // in case of success, only result object is expected Object res = pr.getResult(); return res; // you need cast this to specific object // based on the APIs you called }

if (status.equals(PSResult.IBY_WARNING)) { // in case of warning, both result object and message are // expected // warning is returned only for Payment APIs in case of // offline scheduling System.out.println("warning code is : " + pr.getCode()); System.out.println("warning message is : " + pr.getMessage()); Object res = pr.getResult(); return res; // you need cast it here too }

// currently IBY_INFO is not yet returned by any PaymentService API System.out.println("Illegal status VALUE in PSResult! " + pr.getStatus()); return null;}

Using Payment Service APIAfter a payment service handle is obtained via the OraPmt class, you can call any of the following APIs in Payment Service interface. For details, refer to Java Developer’s Guide.

Here are some sample codes for Electronic Commerce Application Registration API, Instrument API, and Payment APIs. These codes use the checkResult call.

Registering an Electronic Commerce Applicationpublic void ecAppAPISample(PaymentService paymentService) { if (paymentService == null) return;



ECAppReg er; PSResult pr; Object obj; int ecappId;

// add a new ECApplication er = new ECAppReg(); er.setName("My ECApp"); er.setAppShortName("XYZ"); // this should be unique pr = paymentService.oraECAppReg(er); obj = checkResult(pr); if (obj == null) return; // failed at registration

// registration successful ecappId = ((Integer)obj).intValue(); System.out.println("ECApp XYZ registered successfully " + "with id: " + ecappId); }

Registering a Credit Cardpublic void instrAPISample(PaymentService paymentService, int ecappId) { PSResult pr; Object obj; CreditCard cc; Address addr; int instrid_cc; String payerid = "payer1";

addr = new Address("Line1", "Line2", "Line3", "Redwood Shores", "San Mateo", "CA", "US", "94065");

// credit card cc = new CreditCard(); cc.setName("My Credit Card"); cc.setFIName("CitiBank"); cc.setInstrBuf("This is my credit card description."); cc.setInstrNum("4111111111111111"); // the credit card number cc.setCardType(Constants.CCTYPE_VISA); // the credit card type, should // match the credit card number, if set cc.setExpDate(new java.sql.Date(101, 0, 10)); // Jan 10, 2001 cc.setHolderName("Mary Smith"); cc.setHolderAddress(addr);



// add the credit card pr = paymentService.oraInstrAdd(ecappId, payerid, cc); obj = checkResult(pr); if (obj == null) return; // registration failure instrid_cc = ((Integer) obj).intValue();

System.out.println("Credit card registered successfully " + "with instrument id " + instrid_cc);}

Sending a Credit Card Authorization Request// perform an ONLINE credit card authorization with payment servicepublic void paymentAPISample(PaymentService paymentService, int ecAppId) { Bill t; CoreCreditCardReq reqTrxn; CreditCard cc; PSResult pr; CoreCreditCardAuthResp resp;

// set up the tangible object t = new Bill(); t.setId("orderId1"); t.setAmount(new Double(21.00)); t.setCurrency("USD"); t.setRefInfo("refInfo"); t.setMemo("memo"); t.setUserAccount("userAcct");

// set up the transaction object reqTrxn = new CoreCreditCardReq(); reqTrxn.setNLSLang("American_America.US7ASCII"); reqTrxn.setMode(Transaction.ONLINE); reqTrxn.setSchedDate(new java.sql.Date(100, 5, 10)); //June 10, 2000 reqTrxn.setAuthType(Constants.AUTHTYPE_AUTHONLY);

// set up the payment instrument cc = new CreditCard(); cc.setId(100); // assuming we have previously registered credit // card with instrument id 100

pr = // assuming payee1 has already been configured with the payment // service


PL/SQL APIs For Electronic Commerce Applications

paymentService.oraPmtReq(ecAppId, "payee1", "", cc, t, reqTrxn);

resp = (CoreCreditCardAuthResp) checkResult(pr); if (resp == null) return; System.out.println("Request succeeded with transaction id: " + resp.getTID());

}

PL/SQL APIs For Electronic Commerce ApplicationsiPayment provides PL/SQL APIs to those electronic commerce applications that require or prefer PL/SQL interfaces for processing payment operations. There is an additional HTTP call overhead when PL/SQL APIs are called. When electronic commerce applications invoke these PL/SQL APIs, the APIs in return calls the electronic commerce servelet through HTTP, as shown in the iPayment Integrating with APIs diagram.

iPayment PL/SQL APIs provide all payment related APIs only and the functionality of those APIs is the same as the Java APIs. iPayment does not provide administration APIs in PL/SQL.

PL/SQL APIs are created as part of IBY_PAYMENT_ADAPTER_PUB package and these packages are installed in the APPS schema.

Requirements1. PL/SQL Package IBY_PAYMENT_ADAPTER_PUB must be installed in the

APPS schema.

2. An Administrator must set up iPayment URL property to iPayment electronic commerce servlet’s URL using the iPayment administration user interface before invoking the APIs.

The following PL/SQL Code helps you in understanding how iPayment PL/SQL APIs can be invoked. This example code invokes the Payment Request API using a credit card. It also passes risk related information for risk evaluation.

DECLARE p_api_version NUMBER := 1.0;

--To initialize message list. p_init_msg_list VARCHAR2(2000) := FND_API.G_TRUE; p_commit VARCHAR2(2000) := FND_API.G_FALSE;


PL/SQL APIs For Electronic Commerce Applications

p_validation_level NUMBER := FND_API.G_VALID_LEVEL_FULL; p_ecapp_id NUMBER := 0; p_payee_rec IBY_PAYMENT_ADAPTER_PUB.Payee_rec_type; p_payer_rec IBY_PAYMENT_ADAPTER_PUB.Payer_rec_type; p_pmtinstr_rec IBY_PAYMENT_ADAPTER_PUB.PmtInstr_rec_type; p_tangible_rec IBY_PAYMENT_ADAPTER_PUB.Tangible_rec_type; p_pmtreqtrxn_rec IBY_PAYMENT_ADAPTER_PUB.PmtReqTrxn_rec_type; p_riskinfo_rec IBY_PAYMENT_ADAPTER_PUB.RiskInfo_rec_type; x_return_status VARCHAR2(2000); -- output/return status x_msg_count NUMBER; -- output message count x_msg_data VARCHAR2(2000); -- reference string for getting output message text x_reqresp_rec IBY_PAYMENT_ADAPTER_PUB.ReqResp_rec_type; -- request specific output response object l_msg_count NUMBER; l_msg_data VARCHAR2(2000);

BEGIN p_ecapp_id := 66; -- iPayment generated ECAppID p_payee_rec.Payee_ID := 'ipay-payee1'; -- payee’s ID p_payer_rec.Payer_ID := 'ipay-cust1'; -- payer’s ID p_payer_rec.Payer_Name := 'Cust1'; -- Payer’s (Customer’s name) p_pmtreqtrxn_rec.PmtMode := 'ONLINE'; -- Payment mode (Can be ONLINE/OFFLINE) p_tangible_rec.Tangible_ID := 'tangible_id1'; -- Tangible ID / order ID p_tangible_rec.Tangible_Amount := 25.50; -- Amount for the transaction p_tangible_rec.Currency_code := 'USD'; -- Currency for the transaction p_tangible_rec.RefInfo := 'test_refinfo3'; p_pmtreqtrxn_rec.Auth_Type := upper('authonly'); -- request type p_pmtinstr_rec.CreditCardInstr.CC_Type := 'Visa'; -- payment instrument type p_pmtinstr_rec.CreditCardInstr.CC_Num := '4111111111111111'; -- payment instrument number p_pmtinstr_rec.CreditCardInstr.CC_ExpDate := to_char(sysdate+300); -- payment instr. Expiration date --5. RISK INPUTS


Status Update API for Offline Requests

p_riskinfo_rec.Formula_Name := ’test3’; -- Risk formula name p_riskinfo_rec.ShipToBillTo_Flag := ’TRUE’; -- Flag showing if ship to address same as Bill to address p_riskinfo_rec.Time_Of_Purchase := ’08:45’; -- Time of purchase IBY_PAYMENT_ADAPTER_PUB.OraPmtReq( p_api_version, p_init_msg_list,p_commit,p_validation_level, p_ecapp_id , p_payee_rec, p_payer_rec, p_pmtinstr_rec, p_tangible_rec, p_pmtreqtrxn_rec, p_riskinfo_rec , x_return_status, x_msg_count , x_msg_data , x_reqresp_rec); END;

Status Update API for Offline RequestsiPayment provides a PL/SQL API that must be implemented by electronic commerce applications through which Offline payment processing statuses will be updated to electronic commerce application. This API must be defined in a package. Naming convention of the package and signature of the API are defined below. Electronic commerce applications must implement the package according to the syntax defined and create the package in the APPS schema.

Package name has to be of the following format <application_short_name>_ecapp_pkg. The application_short_name is a three-letter short name that is given in Electronic Commerce Application Registration API. The package should have defined update_status procedure with the following signature:

PROCEDURE UPDATE_STATUS( totalRows IN NUMBER,txn_id_Tab IN APPS.JTF_VARCHAR2_TABLE_100,req_type_Tab IN APPS.JTF_VARCHAR2_TABLE_100,



Status_Tab IN APPS.JTF_NUMBER_TABLE,updatedt_Tab IN APPS.JTF_DATE_TABLE,refcode_Tab IN APPS.JTF_VARCHAR2_TABLE_100,o_status OUT VARCHAR2,o_errcode OUT VARCHAR2,o_errmsg OUT VARCHAR2,o_statusindiv_Tab IN OUT APPS.JTF_VARCHAR2_TABLE_100);The following list describes the field names in the above signature:

1. totalRows: Total number of rows being passed for the update.

2. txn_id_Tab: Table of transaction identifiers for which the update is sent.

3. req_type_Tab: Table of request types corresponding to the Transaction Identifier. For each transaction, there might be a req_type associated with it and the electronic commerce application has to update the correct transaction, based on txn_id and req_type.

The various kinds of req_type are listed in the following table.

4. Status_Tab: Table of status corresponding to each transaction.

The various values and their status are listed in the following table.

Request Types and their Descriptions

req_type Description

ORAPMTCANC Cancel Transaction

ORAPMTCAPTURE Capture Transaction

ORAPMTCREDIT Credit Transaction

ORAPMTREQ Authorize Transaction

ORAPMTRETURN Return Transaction

ORAPMTVOID Void Transaction

ORAPMTCLOSEBATCH Closebatch Transaction

Values and their Status

Value Status

0 Paid

5 Pay Failed



5. updatedt_Tab: Table for the last update date for each transaction.

6. refcode_Tab: Table for the reference code for each transaction.

7. o_status: The overall status of the procedure. If there are errors in trying to execute the procedure, electronic commerce application should set up appropriate value in this field.

8. o_errcode: The error code for any errors which might have occurred in processing.

9. o_errmsg: The error message for the error.

10. o_statusindiv_Tab: Table of status values which have been updated. If the status value has been updated by the electronic commerce application for a particular transaction, it should set up the value to ’TRUE’ for that transaction, otherwise, it should set up the value to FALSE.

When does the Scheduler invoke the API?The Scheduler picks up all the Offline payment transactions to be scheduled every time it is run. After all the Offline payment transactions are processed either successfully or unsuccessfully, the Scheduler has to update the status changes, if any, of each transaction, to the appropriate electronic commerce application. To update the electronic commerce application, the Scheduler calls the PL/SQL API, which is implemented by that electronic commerce application.

Pseudo Code for Implementing the PL/SQL API by Electronic Commerce ApplicationFor each row update, the status is based on the request type and transaction identifier. If the update is successful, then set up the status value appropriately.

for i in 1..totalRows;update the tables with status, updatedate, and refinfo informationupdate tables using status_Tab[i], updatedt_Tab[i], refCode_Tab[i] for

13 Scheduled

15 Failed

17 Unpaid

18 Submitted

Values and their Status

Value Status


Integrating Risk Management

the transaction with id txn_id_Tab[i] and req_type_tab[i]if update is successful o_statusindiv_Tab[i] := ’TRUE’else o_statusindiv_Tab[i] := ’FALSE’end for;return

Integrating Risk ManagementiPayment supports risk management. Electronic commerce applications can incorporate this feature and detect fraudulent payments. The following information describes how electronic commerce applications can integrate the risk management functionality with iPayment.

Risk Factors and Risk FormulasiPayment is bundled with a set of risk factors. Payees can configure these factors depending on their business model. The payees can create multiple formulas using different factors and weights depending on their specific requirements. The ability to create multiple formulas provides flexibility to payees to accommodate different business scenarios. Each formula must be setup so that the sum of the weights is equal to 100.

iPayment also defines an implicit formula for each payee with default factors and weights. Administrators have the flexibility to modify the implicit formula. The following information describes how and where the implicit formula is used.

Process Flow of Risk Evaluation1. To enable the risk management functionality for a payee, administrators should

click the Enabled radio button in Risk Management Status screen of that payee.For more information See Updating Risk Management Status.

2. When electronic commerce application makes a Payment Request API call, iPayment checks if the payee involved in the payment request is risk enabled or not. If a payee is risk enabled, iPayment evaluates either the risk formula passed in the Payment Request API or the implicit formula associated with that payee.

3. Electronic commerce application can pass a specific risk formula name by calling the Overloaded Payment Request API. This API takes PmtRiskInfo object in which electronic commerce application can set up the formula name and


Error Handling During Payment Processing

additional information. If PmtRiskInfo object is not passed and the payee is risk enabled, iPayment evaluates the implicit formula of that payee.

4. iPayment returns the Risk Response (RiskResp) object as part of the payment response. If risk evaluation is done successfully, Risk Response object contains the risk score obtained after evaluation and the threshold value that is set up with the payee. Electronic commerce application can decide whether payment can be accepted or not, based on the risk score and the threshold value.

5. If the risk score is more than the threshold value, the payment request is risky.

Error Handling During Payment ProcessingiPayment returns a Response Object to each API that electronic commerce application calls. If the operation fails, then the Response Object contains status value (IBY_FAILURE), indicating that there was a failure while processing the request. In these cases, electronic commerce application can get more information about the failure by checking the error code and the error message. Errors can happen in iPayment for various reasons. For example, wrong or duplicate data passed by the electronic commerce application, time-out while communicating with Payment Systems, etc. All the error cases that can occur in iPayment can be categorized in groups. These groups are:

� Errors due to invalid data or if duplicate information is passed

� Communication errors

� Configuration errors

Common ErrorsThe following table contains the most commonly encountered errors.

Error Codes and Description

Error Code Description

IBY_0001 Communications error. The payment system, the processor, or iPayment electronic commerce servlet is not available. You should resubmit the request at a later time.

IBY_0002 Duplicate order identifier.

IBY_0003 Duplicate batch identified.

IBY_0004 Mandatory fields are required.


Error Handling During Payment Processing

Errors due to invalid or duplicate data In each payment request, a payment instrument from which the money is transferred to the payee’s account is involved. Generally this information will be given by the end user of the electronic commerce application. Sometimes the end user might enter wrong instrument number or an instrument number that does not have enough funds. To detect these errors, iPayment provides two error codes that help electronic commerce applications to prompt the end user for correct information.

The Error Codes due to invalid or duplicate data and their descriptions are given in the following table.

Communication ErrorsBecause payment processing requests involve a number of different components that are not tightly integrated, time-out errors or communication errors are possible. For example, a processor successfully processes a payment request, but the network connection between the payment system and iPayment, or the network connection between iPayment’s PL/SQL API package and iPayment electronic commerce servlet break down, causing the electronic commerce application not to receive the

IBY_0005 Payment system specific error. Check BEPErrCode and BEPErrMsg in response objects for more information.

IBY_0006 Batch partially succeeded. Some transactions in the batch failed and some were processed correctly.

IBY_0007 The batch failed. You should correct the problem and resubmit the batch.

IBY_0008 Requested action is not supported by the payment system.

IBY_0017 Insufficient funds.

IBY_0019 Invalid credit card or bank account number.

Error codes and their description due to invalid data or duplicate data


IBY_0017 Insufficient Funds

IBY_0019 Invalid credit card/bank account number

Error Codes and Description



Risk Management Test Scenarios

result. In some cases, electronic commerce application might crash before receiving a response. Before the crash, payment processing may have completed. Therefore, when electronic commerce application calls the API with the same information, iPayment considers this as a duplicate request and raises an error. To recover from such errors, iPayment provides two approaches.

In the first approach, which is applicable to OraPmtReq and OraPmtCredit, electronic commerce application can try the request with the retry flag set up to TRUE. This makes iPayment retry the request if it has not processed the request. Otherwise iPayment sends the same response that was sent when this request was first made.

In the second approach, which is applicable to all other operations except OraPmtReq and OraPmtCredit, the electronic commerce application needs to find out if the transactions went through successfully to reexecute any lost transactions. To enable the merchant or business to query the status of a transaction, you need to integrate the Query Transaction Status API into the electronic commerce application. This API returns all existing records for a particular transaction identifier on a payment system.

The following table shows a Communication error code and its description.

Configuration ErrorsThese errors occur if payees or payment systems are not configured properly. Make sure that the URLs are entered correctly and the payee’s payment system identifiers are configured properly.

Risk Management Test ScenariosThe following information includes three business scenarios to describe how a merchant can use the Risk Management functionality.

Communication error code and its description


IBY_0001 The payment system, the processor, or iPayment’s electronic commerce servlet is not available. You should resubmit the request at a later time.



Merchant Selling Books and Low Priced GoodsIn a small business, risky instruments is a critical factor. If a customer is using a stolen credit card, the merchant should consider this transaction risky and assign this risk factor a higher weight than the other risk factors. Ship To/Bill To address matching and Payment History are also important risk factors. To include AVS Code risk factor, a merchant can set up a formula with weights as shown in Weight B column in Risk Formula Setup-First Case table. The total of all the weights should be 100. For a formula that a merchant would set up in this case, see Risk Formula Setup for the First Case.

Risk Formula Setup for the First CaseThe following table shows the risk formula setup for a merchant selling books and low priced goods.

Risk Factor Setup� Payment Amount Limit

The following table shows the risk levels and the associated payment amounts.

Risk Formula Setup-First Case

Factors Weight A Weight B

Bad Instruments 30 30

Payment Amount Limit

15 15

Transaction Amount 15 15

Ship to/Bill to 20 10

Payment History 20 10

AVS Code 0 20

Risk Levels and Associated Payment Amount

Risk LevelsGreater than or Equal To

Low 0

Low Medium 100



� Transaction Amount

A transaction is high risk if the transaction amount exceeds 500 in one week. Otherwise there is no risk.

� Payment History

The following table shows the risk levels and the number of payments made in the last six months by a particular customer.

� AVS Codes

The following table shows the risk levels and the associated AVS Codes. AVS Codes risk factor evaluation is useful only for customers in the United States.

Medium 200

Medium High 300

High 400

Risk Levels and the Number of Payments


Low 6

Low Medium 4

Medium 3

Medium High 2

High 0

Risk Levels and Associated AVS Codes

Risk Level AVS Code

No Risk S,Y,U,X,R,E

Low A,Z,W

Risk Levels and Associated Payment Amount




� Ship To/Bill To and Risky Instruments

These risk factors do not require any setup. The evaluation will be done with the data already existing in the database.

� Risk Score

A typical threshold value would be between medium and medium high risk score.

Risk Management module evaluates the payment request and returns an overall risk score. If an overall risk score exceeds the threshold value set up by the merchant, then the merchant has to decide whether to process the request or block the request.

Merchant Selling Electronic GoodsRisky Instruments is a critical factor in this case. If a customer is using a stolen credit card, the merchant should consider this transaction risky and assign it a higher weight.

Frequency of Purchase is the next important risk factor. Usually a customer does not buy electronic goods frequently, and if he does, it could be a fraudulent purchase.

In this scenario, Time of Purchase is also to be considered as an important risk factor. If someone buys many goods after 2:00 AM, it might be a fraudulent purchase.

To include an AVS Codes risk factor, a merchant sets up a formula with weights as shown in column Weight B in Risk Formula Setup-Second Case table. The total of all the weights are 100. AVS Codes risk factor evaluation will be useful only for customers in the United States.

Low Medium

Medium

Medium High

High N

No Risk S,Y,U,X,R,E


Risk Level AVS Code



Risk Formula Setup for the Second CaseThe following table shows the risk formula set up for a merchant selling electronic goods.

Risk Factor Setup� Payment Amount Limit

The following table shows the risk levels and the associated payment amounts.

� Transaction Amount

This risk factor is considered high risk if the amount exceeds 5,000 in one week. Otherwise there is no risk.

� Frequency of Purchase

Risk Formula Setup-Second Case

Factor Weight A Weight B

Bad Instruments 30 30

Ship to/Bill to 15 12

Time of Purchase 15 12

Frequency of Purchase 20 10

Payment Amount 10 8

Transaction Amount Limit 10 8

AVS Code 0 20

Risk Levels And Associated Payment Amounts

Risk LevelsGreater Than or Equal To

Low 500

Low Medium 1000

Medium 1500

Medium High 2000

High 2500



This risk factor is considered high risk if the frequency of purchase exceeds ten times in the previous one week.

� AVS Codes

The following table shows the risk levels and the associated AVS Codes. AVS codes risk factor evaluation is only useful for customers in the United States.

� Ship To/Bill To and Risky Instruments

These risk factors do not require any setup. The evaluation will be done through the data already existing in the database.

� Risk Score

A typical threshold value is to be between medium and medium high risk score.

The Risk Management module evaluates the payment request and returns an overall risk score. If an overall risk score exceeds the threshold value set up by the merchant, the merchant has to decide whether to process the request or to block the request.

Business to Business CustomerIn a business to business scenario, a merchant has an established relationship with his customer. In this scenario, the Oracle Receivables risk factors take higher precedence. The merchant is interested in the customer’s payment history, his credit rating, etc. All Oracle Receivables risk factors are set up through Oracle Receivables interface.


Risk LevelAVS Code (Comma Separated)

No Risk S,Y,U,X,R,E

Low A,Z,W

Low Medium

Medium

Medium High

High N

No Risk S,Y,U,X,R,E



Risk Formula Setup in the Third CaseThe following table shows a Risk Formula setup for a business to business customer.

Risk Factor Setup� Overall Credit Limit: 100,000

� Transaction Credit Limit: 50,000

� Risk Codes are set up through Oracle Receivables codes.

The following table shows the risk codes and the associated risk scores set up through iPayment administration user interface.

� Credit Rating Codes are set up through Oracle Receivables interface

The following table shows the set up of Credit Rating Codes and the associated Risk Scores.

Risk Formula Setup-Third Case

Factors Weight

Overall Credit Limit 30

Transaction Credit limit 30

Risk Codes 15

Credit Rating Codes 15

Payment History 10

Risk Factor Setup

Risk Codes Risk Score

Low Low

Average Medium

Excellent No Risk


Transaction Types

� Risk Score

A typical threshold value is between medium and medium high.

Risk Management module evaluates the payment request and returns an overall risk score. If an overall risk score exceeds the threshold value set up by the merchant, then the merchant decides whether to process the request or block it.

Transaction TypesiPayment returns transaction types (Trxn Type) in individual PmtResponse objects for the electronic commerce application API. The following table contains the transaction types and their description.

Credit Rating Codes and Associated Risk Scores

Credit Rating Codes Risk Score

Low Low

Average Medium

Poor High

Excellent No Risk

Transaction types and their description

Value Type Description

2 AuthOnly An authorization only requested for an order.

3 AuthCapture An online authorization and capture for an order.

4 VoidAuthOnly Void an order that was successfully authorized but not captured.

5 Return Perform a return or credit on an order that was successfully authorized and captured online.

7 VoidAuthCapture Void a previous authorization and capture online.


BatchState

BatchStateThe BatchState parameter indicates the state of the batch based on the processor. If the state is set up to sent, the merchant needs to query the batch again to find out if the batch is accepted and also to retrieve transaction details.

The following table contains the values and definition of the BatchState parameter.

8 Capture Capture performed by a host-based or a terminal-based (closed batch) processing system.

9 MarkCapture Transaction that was marked for capture by a terminal-based processing system.

10 MarkReturn Transaction that was marked for return by a terminal-based processing system.

13 VoidCapture Void a transaction captured by a host-based or terminal-based (close batch) processing system.

14 VoidMarkCapture Void a transaction marked for capture by a terminal-based processing system.

17 VoidReturn Void a transaction that was returned by a host-based or terminal-based (close batch) processor system.

18 VoidMarkReturn Void a transaction that was marked for return by a terminal-based system.

BatchState Values

Value Definition

0 Batch accepted.

1 Batch sent.

2 Batch queued.

3 Batch rejected.

4 Batch processed.

Transaction types and their description

Value Type Description


BatchState

5 Batch error.

6 Batch not found.

7 Batch unknown.

BatchState Values

Value Definition


iPayment Administration User Interface

Administering iPayment

This topic group provides process-oriented, task-based procedures for using the application to perform essential business tasks.

Administration OverviewAll setup and administrative functions of iPayment are done through the iPayment user interface. You can login and create, modify, and inactivate payment systems, payees, risk management properties, and routing rules.

iPayment is administered through a browser based administration user interface that is implemented using Java and Java Server Pages (JSP). Administering iPayment includes using the iPayment user interface to configure and test iPayment, to add and configure the payment systems, payees, routing rules, and risk management.

iPayment Administration User InterfaceThe following table lists the tab names and the functionality available from the iPayment administration user interface.

Navigating the iPayment Administration User InterfaceThe iPayment administration user interface includes the administration tabs and the administration workspace.

The administration tabs on the top of the screen, remain visible as you navigate through iPayment. The tabs list the administrative tasks that you can perform.

Tabs and Functionality

Tab name Functionality

Payment System Create and modify payment system properties in iPayment.

Payee Create and modify payee properties and risk management properties in iPayment.

Routing Rule Create, modify, and delete routing rules in iPayment.

Administering iPayment 51

Payment System

When you click a tab, details for the selected task appear in the administration workspace in the lower portion of the screen.

Payment SystemYou can perform the following tasks from the Payment Systems screen. This screen lists all the registered payment systems and links to each administration site.

Creating a New Payment System

Modifying a Payment System

Updating a Default Payment System

Creating a New Payment SystemUse this procedure to create and register a new payment system from the Create Payment System screen. The payment system is permanently registered.

PrerequisitesNone

Steps1. Click the Payment System tab. Payment Systems screen appears.

2. Click the Create button. Create Payment System screen appears.

3. Enter payment system details. Fields marked with red asteriks are mandatory fields. See Guidelines on Payment System Fields for a description of all fields.

4. Click Create.

Guidelines on Payment System FieldsThe following table lists the payment system fields. Fields with asteriks are mandatory fields.


Modifying a Payment System

Modifying a Payment System Use this procedure to modify the values associated with a payment system from the Payment System Details screen.

Payment System Fields

Field/Checkbox Name Description

* Name Name of the payment system being added. This name is used in iPayment generated screens and reports, and should be a popularly known name of the payment system. This name should not contain any spaces.

* Suffix Three-character suffix for this payment system to use in iPayment API names (for example, psa for Payment System A). This has to be unique and is stored in lower-case.

* User Name Username that is to be used for authentication by the payment system when basic authentication is set up on the payment system servlet. The payment system username must contain at least six characters and not more than 30 characters.

* User Password The password for the payment system username. This should contain at least six characters and no more than 30 characters.

* Base URL Servlet Universal Resource Locator (URL) to invoke the payment system. The base URL should include a port number, if there is one. This generally starts with http://. However, if this URL is SSL enabled, then start with https://.

Administration URL The URL that provides access to the payment system’s administration tools. It is set up to start with either http or https. (This URL is also available in the Go To Vendor Site column on the Payment System Profiles screen.)

* Supported Payment Instruments

iPayment supports both credit card transactions and bank account transfers. Check the appropriate checkbox. If the payment system is SET compliant, check only credit card as the supported payment instrument and then select the Yes button, otherwise select the No button.

For bank account transfers, enter the number of days, if there is a lead time to process a request.

NLS Language Preferred and optional languages and character sets supported by the payment system. These should be in Oracle NLS_LANG parameter format.


Updating a Default Payment System

PrerequisitesNone

Steps1. Determine the payment system for which the properties are to be modified.

2. Click the payment system name from the Payment Systems screen. Payment System Details screen appears.

3. Modify the fields associated with a payment system. See Guidelines on Payment System Fields for field details.

4. Click Update.

Updating a Default Payment SystemUse this procedure to update the default payment system per instrument type from the Default Payment System screen. Any transaction not routed by the routing rules is routed to the default payment system based on its instrument type.

PrerequisitesNone

Steps1. Click the Payment System tab.

2. Click the Default Payment System subtab. Default Payment System screen appears.

3. For each payment instrument, select a default payment system from the drop down list available in the Select Payment System column.

4. Click Update.

PayeePayees and Risk Management screen displays a list of all the registered payees, their status, and their associated risk management links. You can perform the following tasks from the Payees and Risk Management screen.

Creating a New Payee

Modifying a Payee


Creating a New Payee

Inactivating a Payee

Updating Risk Management Status

Creating a New PayeeUse this procedure to add a new payee from the New Payee screen.

PrerequisitesNone

Steps1. Click the Payee tab. Payees and Risk Management screen appears.

2. Click the Create button. New Payee screen appears.

3. Add payee details. Fields marked with red asteriks are mandatory fields. See Guidelines on Payee Fields for a description of all the fields.

4. Click Create. A new payee is created.

Guidelines on Payee FieldsThe following table lists the payee fields.

Payee Fields

Name Description

* Payee Name Payee name that appears on the pages and reports generated by iPayment. It is unique and case sensitive.

* Payee Identifier iPayment uses this payee identifier to identify a particular payee. You cannot modify this identifier after saving it. It is unique and case sensitive.

* Status Payee status is either active or inactive. Select active if you want iPayment to process requests for this merchant. Select inactive to suspend payment processing for a merchant while maintaining access to the payee’s configuration file.

Payment System Identifier Identifier by which this payee is uniquely known to a payment system. Two payees cannot have the same identifier for one particular payment system. This is case sensitive.

Accepted Payment Instrument

Select the appropriate payment instrument that the payee accepts.


Modifying a Payee

Modifying a PayeeUse this procedure to change a payee’s properties from the Payee Details screen.

PrerequisitesNone


2. Click the payee name which appears in the Select Payee column. Payee Details screen appears.

3. Modify the fields associated with a payee. See Guidelines on Payee Fields for details.

4. Click Update.

Inactivating a PayeeUse this procedure to inactivate a payee from the Payee Details screen.

PrerequisitesNone


2. Click the payee name which appears in the Select Payee column. Payee Details screen appears.

3. Click Inactive in the Status radio button.

4. Click Update.

Updating Risk Management StatusUse this procedure to update the risk management status of each payee from the Risk Management Status screen.

PrerequisitesNone


Modifying the Risk Score


2. Click either Enabled or Disabled link in the Risk Management Status column. Risk Management Status screen for that payee appears.

3. Click either Enabled or Disabled radio button.

4. Enter an integer value between 0 to 100 in the Cumulative Risk Threshold field.

5. Click Update.

ReferencesFor more information, See Understanding Risk Management.

Risk FactorsYou can modify the following risk factors and the risk score from the Risk Factors screen. All risk factors and the risk score use default values until the values are modified. After being modified, that particular factor or score only affects that particular payee. The other unchanged factors will continue to use the default values.

Modifying Risk Score

Modifying Payment Amount Limit

Modifying Payment History

Modifying Transaction Amount

Modifying Time of Purchase

Modifying AVS Code

Modifying Frequency of Purchase

Modifying Oracle Receivables Risk Codes

Modifying Oracle Receivables Credit Rating Codes

For more information, See Understanding Risk Management.

Modifying the Risk ScoreUse this procedure to modify the risk score from the Risk Factors screen.


Modifying the Payment Amount Limit Risk Factor

PrerequisitesNone


2. Click the Modify button in the Risk Factors column associated with the payee whose risk factor is to be configured. Risk Factors screen appears.

3. Select Risk Score from the Risk Factors list. Risk Score details appear.

4. Enter an integer value from 0 to 100 in the Risk Value column.

5. Click Update.

Modifying the Payment Amount Limit Risk FactorUse this procedure to modify the Payment Amount Limit risk factor from the Risk Factors screen. Payment Amount is the amount involved in the payment request. Its scale varies from business to business. Based on the business model, each risk level varies with different amount ranges.

PrerequisitesNone



3. Select Payment Amount Limit from the Risk Factor drop down list. Payment Amount Limit details appear.

4. For each risk level, enter a positive integer representing the lower bound of the amount range in Greater than or equal to column.

5. Click Update.

Modifying the Payment History Risk FactorUse this procedure to modify the Payment History risk factor by configuring the frequency values from the Risk Factors screen.


Modifying theTransaction Amount Risk Factor

Payment History is the frequency with which the customer had made payments during the most recent time period. The risk level depends on the frequency. If a customer has made payments frequently, then he is more reliable and less risky.

PrerequisitesNone



3. Select Payment History from the list available in the Risk Factor list. Payment History details appear.

4. Enter a positive integer for the duration value and select a duration time.

5. For each risk level, enter a positive integer representing the lower bound of the frequency range in Greater than or equal to column.

6. Click Update.

Modifying theTransaction Amount Risk FactorUse this procedure to modify the Transaction Amount risk factor from the Risk Factors screen. Transaction Amount is the total amount of payments made using the same instrument in a specified period of time. If the total payment amount exceeds the Transaction Amount, the payment is considered highly risky.

PrerequisitesNone



3. Select Transaction Amount from the Risk Factor drop-down list. Transaction Amount details appear.


Modifying the Time of Purchase Risk Factor

4. Enter a positive number in the amount field, a positive integer in the duration field and select a duration time unit.

5. Click Update.

Modifying the Time of Purchase Risk FactorUse this procedure to modify Time of Purchase risk factor from the Risk Factors screen.

Time of Purchase is the time at which a payment request is made by the payee’s customer. A risk level can be associated to every hour of the day. No hour can be associated with more than one risk level.

PrerequisitesNone



3. Select Time of Purchase from the Risk Factors drop-down list. Time of Purchase details appear.

4. For each time range, select the starting and ending hour and its risk level.

5. Click Update.

GuidelinesYou can add more time ranges and the risk levels associated with them by entering time ranges and risk levels in the last row of the table. You can also delete time ranges by selecting the corresponding checkbox in the Remove column. No time ranges should overlap.

Modifying the AVS Codes Risk FactorUse this procedure to modify the AVS codes risk factor from the Risk Factors screen.

AVS codes is returned by the payment systems such as Cybercash, Verifone, and others. Address Verification Service codes are provided by Mastercard and Visa credit card networks to match the billing address with the address that is


Modifying the Frequency of Purchase Risk Factor

maintained for the cardholder by the issuing bank. These codes can be associated with various risk levels.

PrerequisitesNone



3. Select AVS codes from the Risk Factor list. AVS Codes details appear.

4. Enter the AVS Codes (separated by commas), in the Address Verification Service Codes field, corresponding to each risk level.

5. Click Update.

GuidelinesIf you remove all existing AVS codes, iPayment restores the default values.

Modifying the Frequency of Purchase Risk FactorUse this procedure to modify the Frequency of Purchase risk factor from the Risk Factors screen. Frequency of Purchase is the frequency of payments for a time period. A payment request is considered high risk if the total number of payment transactions exceed the maximum frequency limit for the given time period.

PrerequisitesNone



3. Select Frequency of Purchase from Risk factors list. Frequency of Purchase details appear.


Modifying the Oracle Receivables Risk Codes Risk Factor

4. Enter a positive integer for the maximum frequency of payment and in the duration field. Also enter the duration time period.

5. Click Update.

Modifying the Oracle Receivables Risk Codes Risk FactorUse this procedure to modify Oracle Receivables Risk Codes risk factor from the Risk Factors screen. Risk Code is a user defined risk assessment field in Oracle Receivables. It is useful for online financing or for evaluating purchases of a large amount for a new customer. A payee associates risk levels with each risk code.

Prerequisites1. Install and register Oracle Receivables.



3. Select Oracle Receivables Risk Codes from the Risk Factors list. Oracle Receivables Risk Codes details appear.

4. Select risk levels corresponding to Oracle Receivables Risk Codes in each row.

5. Click Update.

Modifying the Oracle Receivables Credit Rating Codes Risk FactorUse this procedure to modify Oracle Receivables Credit Rating Codes risk factor from the Risk Factors screen. Credit Rating is the information enabling payees to effectively manage financial terms with their customers. It is useful for online financing or for evaluating purchases of large values for a new customer. A payee associates risk levels to each credit rating.

Prerequisites1. Install and register Oracle Receivables.



Modifying the Oracle Receivables Transactional Credit Limit Risk Factor


3. Select Oracle Receivables Credit Rating Codes from the Risk Factors list. Details appear.

4. Select Risk Levels corresponding to Oracle Receivables Credit Rating Codes in each row.

5. Click Update.

Modifying the Risky Instruments Risk FactorThis risk factor cannot be configured.

Risky instruments are a list of instruments that are considered risky by each payee. These include the instruments that were used by customers earlier and had resulted in fraud or chargebacks. If the instrument being used for payment is found in the repository, the payment is considered a high risk payment.

ReferencesSee Risky Instrument Upload Utility for more information about how to upload and remove the risky instruments.

Modifying the Ship to/Bill to Address Risk FactorThis risk factor cannot be configured.

Ship to/Bill to Address is used to match Ship to and Bill to Addresses in the payment request. If the Ship to and Bill to Addresses do not match, the payment request is considered high risk.

Modifying the Oracle Receivables Transactional Credit Limit Risk FactorThis risk factor cannot be configured.

Transaction Credit Limit is the credit limit per transaction assigned by Oracle Receivables. When a payment request exceeds the transaction credit limit, it becomes a risky payment. It varies from business to business and can be set up at customer or site level through Oracle Receivables.


Modifying the Oracle Receivables Overall Credit Limit Risk Factor

Modifying the Oracle Receivables Overall Credit Limit Risk FactorThis risk factor cannot be configured.

Credit Limit is an overall credit limit assigned at site level. If a customer has an outstanding balance and the total amount of payment made by the customer exceeds the overall credit limit, the payment becomes a high risk payment. It varies from business to business and can be set up at customer or site level through Oracle Receivables.

Risk FormulaYou can perform the following procedures from the Risk Formula screen. This screen lists all the risk formulas available for the selected payee.

Creating Risk Formula

Updating Risk Formula

Deleting Risk Formula


Creating a Risk FormulaUse this procedure to create a risk formula from the Risk Formula screen.

PrerequisitesNone


2. Click Create/Modify available below the Risk Formulas column associated with the payee.

3. Risk Formulas screen appears. The screen lists the implicit formula for each payee and other risk formulas of this payee. Click Create. New Risk Formula screen appears.

4. Enter a unique name for the new risk formula in the Formula Name field.


Deleting a Risk Formula

5. Enter a positive integer weight in percent for each risk factor. The total weight of all risk factors should be equal to 100. If Oracle Receivables is installed on your site, Oracle Receivables risk factors also appear on this screen.

6. Click Create.


Updating a Risk FormulaUse this procedure to update risk formula from the Risk Formula screen.

PrerequisitesNone


2. Click Create/Modify available below the Risk Formulas column associated with the payee.

3. Select the risk formula to be modified. Click the name of the formula. Risk Formula Details screen appears listing the risk factors and the weights assigned to each of the risk factors.

4. Enter a positive integer weight in percent for each risk factor. The total weight of all risk factors should be equal to 100. If Oracle Receivables is installed on your site, Oracle Receivables risk factors also appear on this screen.

5. Click Update.


Deleting a Risk FormulaUse this procedure to delete risk formula, except the implicit risk formula, from the Risk Formula screen.


Routing Rule

PrerequisitesNone


2. Click Create/Modify available below the Risk Formulas column associated with the payee. Risk Formulas screen appears. The screen lists the implicit risk formula for each payee and other risk formulas for this payee.

3. Check the check box available in the Remove column corresponding to the risk formula which is to be deleted.

4. Click Update.

Routing RuleYou can perform the following tasks from the Routing Rules screen.

Changing the Routing Rule Priority

Creating Routing Rules

Modifying Routing Rules

Deleting Routing Rules

ReferencesFor more information, See iPayment Routing and Operation.

Changing the Routing Rule PriorityUse this procedure to change the routing rule priority from the Routing Rules screen.

PrerequisitesNone

Steps1. Click the Routing Rule tab. Routing Rules screen appears.

2. Select the new priority for changing the routing rule from the drop down list in the Rule Priority column.


Creating Routing Rules

3. Click Update. All routing rules are automatically reordered in the database.

Creating Routing RulesUse this procedure to create Routing Rules from the Create Routing Rule screen.

PrerequisitesNone

Steps1. Click Routing Rule tab. Routing Rules screen appears.

2. Click the Create button. Create Routing Rule screen appears.

3. Enter values in the fields on this screen. Fields marked with red asteriks are mandatory. See Guidelines on Routing Rule Fields for a description of all the fields.

4. Click Create.

Guidelines on Routing Rule FieldsThe following table lists the routing rule fields.

Routing Rule Fields

Name Description

* Rule Name Name of the Routing rule. This name must be one word without spaces and must be unique.

* Rule Priority Select the new priority from the drop down list.

Status Select the status of the Routing Rule as either Active or Inactive.

* Amount This is a rule condition. Select the desired operation to enter an amount value.

* Instrument type This is a rule condition. Select an operation and an instrument type.

* Route to Payment System Select the payment system to which transactions that satisfy the conditions are routed.


Modifying Routing Rules

Modifying Routing RulesUse this procedure to modify routing rules from the Routing Rule screen.

PrerequisitesNone

Steps1. Click the Routing Rule tab. Routing Rule screen appears.

2. Click the routing rule name which appears below the Select Rule column. Routing Rule Details screen appears with all the routing rule fields. See Guidelines on Routing Rule fields.

3. Modify the fields.

4. Click Update.

GuidelinesFor more information, See iPayment Routing and Operation.

Deleting Routing RulesUse this procedure to delete routing rules from the Routing Rule screen.

PrerequisitesNone

Steps1. Click the Routing Rule tab. Routing Rules screen appears.

2. Select the routing rule to be deleted by checking the corresponding checkbox in the Remove column.

3. Click Update.

iPayment PropertiesYou can use the Property Manager provided by the Admin Console to set up or modify iPayment properties.


iPayment Properties

All the properties listed below are mandatory and should not be removed, however their values can be modified.

iPaymentURLThis property contains the following URL:

http://machine:port/iby/ecapp.

Replace the machine and port with the names of the actual machine and the actual port where the iPayment ECServlet is installed.

This information is needed if electronic commerce applications use iPayment PL/SQL API.

Errorfile This property specifies the name of the error file generated by iPayment. The default value is iby_err.log. This file contains exceptions and error messages. This file is always generated regardless of the debug file.

DebugfileThis property specifies the name of the debug file generated by iPayment when the debug flag is turned on. This file consists of debug messages and error messages.

Debug This property is either true or false. If it is set up to true, iPayment writes debug messages to the Debugfile.

Http_ProxyThis property specifies the proxy-URL. For example, http://www-proxy.us.oracle.com.

Note: There are two more properties on the Admin Console. The properties are service.factories and service.oracle.apps.iby.ecapp.PaymentServiceFactory.desc. Do not modify the values of these properties as these are code specific and are needed by iPayment.


Installing and Configuring iPayment Servlets

No_ProxyThis property specifies the domain name for which no proxy is needed. For example, us.oracle.com.

Installing and Configuring iPayment Servlets

Creating the Servlet ZoneUse this procedure to create a servlet zone.

Prerequisites1. A working installation of Apache 1.3.x with JServ 1.x.

2. iPayment class files. These files are assumed to reside in $AU_TOP/java/apps.zip and contain the BEP servlets. Third party libraries, are assumed to reside in $AU_TOP/java/thirdparty.zip. Oracle JDBC drivers are assumed to reside in $JDBC_HOME/lib/classes11i.zip.

Steps 1. Create a servlet zone, called iby.

2. In the jserv.conf file, add the following statement: ApJServMount /iby /iby_zone

3. In the jserv.properties file, add the following lines:

wrapper.classpath=$AU_TOP/java/apps.zip

wrapper.classpath=$JDBC_HOME/lib/classes111.zip

wrapper.classpath=$AU_TOP/11i/config

wrapper.classpath=$AU_TOP/java/thirdparty.zip

zone=iby_zone

iby_zone.properties=$JSERV_TOP/etc/iby.properties


Installing and Configuring iPayment Cybercash Servlet

4. Create the file $JSERV_TOP/etc/iby.properties by making a copy of an example JServ properties file, such as $JSERV_TOP/etc/zone.properties.

Installing the Scheduler Servlet1. Add the following line to iby.properties:

servlet.scheduler.code=oracle.apps.iby.scheduler.PSReqHandler.

2. The servlet is invoked as: http://<hostname>:<port>/iby/scheduler.

Installing the Electronic Commerce Application Servlet1. Add the following line to iby.properties:

servlet.ecapp.code=oracle.apps.iby.ecservlet.ECServlet.

2. The servlet is invoked as: http://<hostname>:<port>/iby/ecapp.

Installing and Configuring iPayment Cybercash ServletCyberCash is a Secure Socket Layer (SSL) payment system supporting both credit card transactions using Merchant Connection Kit (MCK) and bank account transfers using Cybercash’s PayNow services. It supports all iPayment core operations.

For downloading MCK, go to Amps.cybercash.com, register, and download (Merchant Connection Kit). Follow the instructions on how to configure MCK.

Note: The directory $AU_TOP/11i/config is required by the CRM Foundation to initialize the payment service and is used both by the Scheduler and electronic commerce application servlets. If the servlets are installed on an established CRM Foundation environment, this directory has been appended to JServ’s classpath by a wrapper.classpath statement. Otherwise this directory is to be added.



iPayment integrates with MCK version 3 which connects to CyberCash. Create a separate listener for CyberCash servlet. Do not use iPayment administration user interface or iPayment listener.

Use the following parameters in the iPayment administration user interface while setting up CyberCash as the payment system.

Installing the CyberCash ServletUse the following procedure to install the Cybercash Servlet.

Prerequisites1. The iPayment CyberCash Connection Library (libcybnv.so). It is located in

$IBY_TOP/lib.

2. The Merchant Connection Kit (MCK) version 3 from CyberCash with at least one configured merchant. All merchants must be installed in one directory ($MCK_HOME). To install MCK and merchants, see the MCK documentation.

Note: If your MCK is located inside the firewall and your firewall requires a proxy for outbound communication, then add the following parameters to the MCK payee_conf file:

HTTP_PROXY_HOST=<hostname>

HTTP_PROXY_PORT=<port>

Property Value

Name CyberCash

Suffix cyb (do not use CYB or Cyb)

Base URL http://<machine_name>.com:<port>

The machine where CyberCash servlet is to be installed, and any active port, for example:

http://www.merchant.com:9997

Admin URL http://amps.cybercash.com



Steps1. Set up a wrapper.env variable in the following file

jserv.conf. If a line "wrapper.env=LD_LIBRARY_PATH=..." is already present, append the location of the iPayment CyberCash Connection Library (it is assumed to be $IBY_TOP/lib) in the same way as you would append the LD_LIBRARY_PATH environment variable. Or if there is no such line, enter the following line: wrapper.env=LD_LIBRARY_PATH=$IBY_TOP/lib

2. Enter the following line in the iby.properties file: servlet.oramipp_cyb.code=oracle.apps.iby.bep.cybercash.CybServlet.This allows the servlet to be invoked as: http://<hostname>:<port>/<servlet_zone>/oramipp_cyb

3. Enter the following line in the iby.properties file:servlet.oramipp_cyb.initArgs=mckhome=$MCK_HOME,debug=false,logfile=$IBY_TOP/log/ibycybserv.log

Initialization parameters recognized by the CyberCash Servlet � mckhome: The directory in which the CyberCash merchants have been

installed. For example, if a merchant with the name, test-mck has been installed so that its associated files can be found in the following directory /usr/oracle/mck/test-mck. Then mckhome should be set up to /usr/oracle/mck. This is a required parameter. Transaction requests to CyberCash fail, if mckhome is not set up correctly.

� debug: If it is set up to true, the servlet prints debugging information with the responses. This information includes the inputs sent to the servlet during the request and the outputs the servlet sends for its response. If an exception occurs during the processing of the request, a stack trace is printed. Debug is an optional initialization parameter. If it is not set up, debugging is turned off.

� logfile: A string which specifies the fully qualified path name of the log file. The input and output values of each transaction and the stack traces, if an exception occurs, are written to this file. Logfile is an optional parameter. If it is not set up, logging is turned off.

Setting Up Basic Authentication on the CyberCash ApplicationUse the following procedure to set up basic authentication on the CyberCash application.


Installing and Configuring Verifone PayWorks Servlet

Steps1. Enter a username and password for the basic user. This username and

password must be the same as the payment system username and password that were set up during the creation of the CyberCash payment servlet in iPayment administration user interface.

2. Put this user into a group and a realm.

3. Click Apply.

Testing Basic AuthenticationUse the following procedure to test basic authentication.

Steps1. Enter the following URL:

http://<machine_name:port_number>oramipp_cyb?OapfAction=OraAuth

Enter Network Password screen appears. If this screen does not appear, basic authentication has not been successfully set up.

2. Enter the username and password for the basic user.

3. Click Enter. A blank screen and a CyberCash error message appears. Basic authentication has been successfully set up. If you receive an invalid username/password message, basic authentication has not been successfully set up.

Installing and Configuring Verifone PayWorks Servlet Verifone is a major terminal payment vendor. Verifone PayWorks is Verifone’s latest product. It is a distributed, modular credit card based internet payment transaction system with open programmable APIs for internet payees to acquire and process payment and related alternate currency transactions. PayWorks is designed to provide a flexible and scalable framework and to lower software development, deployment, and support costs.

The Payworks servlet integrates iPayment with Verifone PayWorks ISP and can be run from any servlet engine which supports Java servlets 2.0.

Installing the Payworks ServletUse the following procedure to install the Payworks Servlet.



Prerequisites1. A working installation of Verifone PayWorks ISP. Refer to the PayWorks

documentation on how to install and configure Verifone PayWorks.

2. The following information is required:

� Admin Service URL: This is: http://<host name>:<pay service port number>. The <host name> is the name of the machine that the primary server node is installed on.

� Pay Service URL: This is: http://<host name>:<admin service port number>. The <host name> is the name of the machine that the primary server node is installed on.

� DTD URL: Copy the exact value given during installation of Verifone Payworks. This information is mandatory and without it the PayWorks servlet does not communicate with the PayWorks Server.

Steps1. Enter the following line in the iby.properties file:

servlet.oramipp_vfi.code=oracle.apps.iby.bep.payworks.PayworksServlet.This allows the servlet to be invoked as: http://<hostname>/iby/oramipp_vfi

2. Enter the following line in the iby.properties file:servlet.oramipp_vfi.initArgs=configdir=$IBY_TOP/config/payworks,debug=false,logfile=$IBY_TOP/log/vfiserv.log

Initialization Parameters Recognized by the Payworks Servlet� debug: If it is set up to true, the servlet prints debugging information with the

responses. This information includes the inputs sent to the servlet during the request and the outputs the servlet sends for its response. If an exception occurs during the processing of the request, a stack trace is also printed. Debug is an optional initialization parameter. If it is not set up, debugging is turned off.

� logfile: A string which specifies the fully qualified path name of the logging file. The input and output values of each transaction and stack traces if an exception occurs are written to this file. Logfile is an optional parameter. If it is not set up logging is turned off.

� configdir: A string which specifies the fully qualified path name of the servlet configuration directory. Sample files to be added in this directory are located in $IBY_TOP/config/payworks/. Configdir is a mandatory initialization



parameter. If it is not set up to a valid value, or if the configuration files in it do not conform to the proper configuration file syntax, an exception occurs when the Payworks Servlet is invoked.

The Payworks Servlet Configuration Directory This directory contains configuration files for the site as a whole and for individual stores. At the top of the directory is a file called site.cfg. This file contains attributes for the site as a whole. Each store that you want to use with the Payworks Servlet must have its own configuration file, called store.cfg, located in a subdirectory with the same name as that of the store. For example, if you want to use store xyz with the Payworks servlet, the configuration directory must contain a subdirectory called xyz, and in that subdirectory must be a store.cfg file that has been correctly written for store xyz. The syntax of the site.cfg and store.cfg files are similar and consist of either comments, blank lines, or attribute settings.

� Comments are any lines that begin with #.

� Blank lines are lines that consist entirely of whitespace characters.

� Attribute settings are of the form: name = value and must be applicable to the file they are defined in. For example, certain attribute names are valid only for the site.cfg and not the store.cfg files. If an attribute setting is not valid, it is ignored.

Attribute values begin with the first non-whitespace character after the equals sign and extend to the last non-whitespace character before the end of the line. For certain attributes, a valid set of values are enumerated below. If a value specified for such an attribute does not match any of the enumerated ones, the attribute will not be set up.

site.cfg Attributes� store: This attribute specifies the pseudo store name which Payworks uses to

refer to the entire site. It should have a default value in the example configuration file, probably site. Do not change this from the value in the example file.

� user and password: The user name and password of an administrative account with full privileges for the Payworks site. These attributes are optional. Without setting these up, the Payworks Servlet loses certain functionality, such as the ability to dynamically retrieve the default acquirer name, default terminal identifier, default capture type, or currency type of a store.



� dtdurl: The DTD URL (see Prerequisites for Installing the Payworks Servlet). Its value is determined during the installation of the Payworks Server.

� payurl: The Pay Service URL (see Prerequisites for Installing the Payworks Servlet). Its value is determined during the installation of the Payworks server.

� adminurl: The Admin Service URL (see Prerequisites for Installing the Payworks Servlet). Its value is determined during the installation of the Payworks Server.

� logdir: This is an optional attribute. If it is set up, it causes XML log files to be generated by the Payworks Servlet for every transaction in the specified directory. XML logging is very useful for debugging the behavior of both the Payworks Server and the Payworks Servlet and can be used with the servlet logfile.

� cache: Must be set up to either yes or no. If yes, values retrieved dynamically by the Payworks Servlet (a merchant’s default acquirer name, default terminal id, default capture type, or currency type) are cached by the Servlet. This improves performance by reducing the number of communication requests needed to finish a transaction. It also implies that if any values change on the server, the Payworks Servlet must be restarted.

� security: Must be set up to either HTTP or HTTPS. It specifies the communications protocol used to communicate between servlet and server. Because HTTPS is encrypted for security, it is slower than HTTP and may not be useful in certain configurations. For example, when the servlet and server are on the same machine and so do not communicate over an insecure link.

� charset: The character set used by the client application for data fields. This attribute defaults to ISO-8859-1, if it is not specified.

store.cfg Attributes All values to be used for the following merchant attributes are determined during the setup and configuration of a store on the Payworks Server. See the Verifone Payworks Documentation for how to do this.

� user and password: The user name and password for an existing user account with full permissions for the store.

� currency: The currency used by the store. It is in a three letter ISO format (for example, USD for US dollars). This attribute is optional and can be retrieved dynamically by the servlet during execution. Valid values have to be present for user, password, and adminurl attributes in the site section. If these attributes are


Installing and Configuring CheckFree

not set up, dynamic retrieval and certain transaction it depends on, for example, void, and possibly batch close fail.

� acquirer: The store’s default acquirer. This attribute is optional and can be retrieved dynamically by the servlet during execution. Valid values have to be present for the user, password, and adminurl attributes in the site.cfg file and the store has to have a single acquirer. If these attributes are not set up or if the store has multiple acquirers, dynamic retrieval fails and transactions like batch close and possibly batch query fail or produce erroneous results.

� terminal: The store’s default terminal for its default acquirer. This attribute is optional and can be retrieved dynamically by the servlet during execution, but only if there are valid values for the user, password, and adminurl attributes in the site.cfg file, and if the store has a single acquirer and a single terminal on that acquirer. If these attributes are not set up or if the store does not have a single acquirer with a single terminal, dynamic retrieval fails and transactions like batch close and possibly batch query fail or produce erroneous results.

� capturetype: The capture type of the store’s default acquirer. It is either host or terminal. This attribute is optional and can be retrieved dynamically by the servlet during execution. Valid values have to be present for the user, password, and adminurl attributes in the site.cfg file and the store must have a single acquirer. If these attributes are not set up or if the store has multiple acquirers, dynamic retrieval fails and aborts most transactions.

It is strongly encouraged to specify as many attributes as possible, including optional ones. If any of the attributes in a configuration file are changed, or if any store is added, the Payworks Servlet must be restarted before these changes are implemented. The sample files in $IBY_TOP/config/payworks/ are written to work with Verifone’s test payment server. The only attribute you may change to reflect your set up is logdir in the site.cfg file.

Installing and Configuring CheckFreeiPayment is integrated with Checkfree to provide account transfer functionality. Checkfree’s Direct Collect model is provided by Checkfree for account transfer. iPayment is integrated with this model.

How the Direct Payment Model Works� Checkfree has defined a set of file formats for the Direct Payment Model.

� iPayment and Checkfree generate files complying to these formats.



� The generated files are transmitted between iPayment and Checkfree via a secured mechanism suggested by Checkfree. From all the available file formats, only three file formats are used in iPayment integration. The file formats are:

� Debit Order file

� Transaction Journal file

� Return Exception file

For more information about these files, see Checkfree’s Direct Payment Model File Specifications documentation.

Processing Payments for a Payee using Checkfree 1. A payee must have an external setup with Checkfree to use the Direct Collect

model.

2. A payee must be configured in iPayment with the information that Checkfree provides during the setup. For a detailed description about the configuration process, see Configuring a Payee for Checkfree.

3. After configuration, iPayment can start accepting bank account transfer payments for that payee. These payments can be routed to Checkfree.

Payment Process Flow1. The Scheduler works at regular intervals and picks up all pending payments for

Checkfree.

2. The Scheduler writes all those requests to a Debit Order file conforming to the specifications of the Direct Collect model. The name and directory location of this file are configured through the configfile.

3. The Scheduler creates one file for each payee and each file is in a different directory. Location of the file depends on the payee configuration in Checkfree.

4. All Debit Order files generated by the Scheduler get transmitted to Checkfree gateway using a process suggested by Checkfree. Refer to Checkfree Direct Collect File Specifications documentation for more information.

5. Checkfree sends a Confirmation Output file and a Transaction Journal file in response to the Debit Order file. iPayment only processes Transaction Journal file.

6. Confirmation Output file shows if the Debit Order file has a proper syntax or not and Transaction Journal file contains responses for all the accepted payment requests that were submitted in the Debit Order file. iPayment does not process



the Confirmation Output file to verify if there were any errors or not. You should monitor the Confirmation Output file to detect any syntax errors in the Debit Order file.

7. Checkfree also returns Return Exception file if there are any exceptions during processing of the payment requests. iPayment processes Return Exception file.

8. iPayment notifies electronic commerce applications of all status changes of the payment requests throughout the cycle.

The following diagram depicts how the payment status changes after iPayment processes different files.



Changes on the Payment states

Installation of Checkfree1. Integrated components are installed automatically during installation of

iPayment. When iPayment is installed, the files related to iPayment and CheckFree integration are installed in the following directory:oracle/apps/iby/bep_impl/ckf.



2. The other component to be installed is the component that transfers files from iPayment to Checkfree. There are different models that Checkfree suggests to transfer files in a secure mode. A model can be selected depending on the need and should be installed before making iPayment Checkfree enabled.

Configuring a Payee for CheckfreeUse the following procedure to configure a payee for Checkfree.

Prerequisites1. Install the File Transfer module as suggested by Checkfree.

Steps1. Set up CheckFree as a payment system via the administration user interface.

2. Each payee that wants CheckFree as one of their back end payment processing systems must set up a configuration file in the following directory: $IBY_TOP/config/checkfree/payment system identifier>. Payment System Identifier is the key value that is entered for Checkfree in the Payee administration screens for this payee. A template config file (config.cfg) is provided for reference and is available in $IBY_TOP/config directory.

3. Create a directory in $IBY_TOP/config with name as the Payment System Identifier.

4. Copy the template config file to this new directory and rename the file as <BEP-Key>.cfg. For example, if BEP key is abc_key, then the template file config.cfg is copied to $IBY_TOP/config/abc_key/abc_key.cfg. This file should be edited with valid values as specified in the Guidelines on the Valid Values for the Configuration File.

Guidelines on the Valid Values for the Configuration FileThe following table lists the valid values for the configuration file.

Note: Ensure that $IBY_TOP is present in the CLASSPATH environment variable of the Scheduler servlet.

valid Values for the Configuration File

Name Description



Administrative Tips1. Monitor the Confirmation Output files generated by Checkfree to determine if

any exceptions or errors were generated. If any errors or exceptions were generated, file a bug with Oracle Support.

2. Archive the files that are generated by CheckFree and iPayment.

CLIENT_ID CheckFree implementation is custom built for merchants needs. Merchants who need CheckFree’s account transfer support, have to contact CheckFree to obtain this identifier. This identifier is provided specifically for each merchant by CheckFree.

PAYEE_ID The identifier provided specifically for each merchant by CheckFree.

PAYEE_SHORT_NAME Short name of the merchant.

DIR_TO_SEND_TO_CHECKFREE

Name of the directory in which iPayment generates all files (relating to this merchant) to be transferred to CheckFree.

TO_FILE_BASE_NAME iPayment prepends this name while generating files (relating to this merchant) to be transferred to CheckFree.

DIR_TO_GET_FROM_CHECKFREE

Name of the directory in which CheckFree generates all files (relating to this merchant) to be transferred to iPayment.

JOURNAL_FILE_BASE_NAME

CheckFree prepends this name while generating journal files (relating to this merchant) to be transferred to iPayment.

RETURNS_FILE_BASE_NAME

CheckFree prepends this name while generating returns files (relating to this merchant) to be transferred to iPayment.

MERCHANT_ADDRESS_LINE_1

Street address for this merchant. This is only to be in the format accepted by CheckFree.

MERCHANT_CITY City name for this merchant. This should only be in the format accepted by CheckFree.

MERCHANT_STATE State name for this merchant. This should only be in the format accepted by CheckFree.

MERCHANT_ZIP Zip code for this merchant. This should only be in the format accepted by CheckFree.

MERCHANT_COUNTRY

Country name for this merchant. This should only be in the format accepted by CheckFree.

valid Values for the Configuration File




Documents

Oracle iPayment · iPayment consists of the following servlets: ... 4 Oracle iPayment Concepts and Procedures ... Understanding Credit Card Transactions iPayment handles both credit