Integrating with Oracle Payments Using Public Funds Capture APIs
Overview of Oracle Payments APIs
This chapter explains the public APIs used in Oracle Payments.
Oracle Payments provides APIs which can be implemented:
-
Implementing Electronic Commerce Applications APIs. These APIs are mainly used for payment processing.
Implementing Electronic Commerce Applications APIs
Oracle Payments provides various types of APIs to integrate electronic commerce applications with Oracle Payments.
If you are using an electronic commerce application other than the preintegrated Oracle applications, you must implement the electronic commerce application's APIs to link your application to Oracle Payments.
Electronic commerce applications can embed the Oracle Payments functionality within their application, which eliminates the need to access Oracle Payments as a standalone application, and hence improves performance, and simplifies the setup.
This section describes the various APIs that are provided to the electronic commerce applications for using the features of Oracle Payments. The APIs were categorized into these categories:
Oracle Payments provides APIs in these programming languages:
This diagram shows the integration of APIs with Oracle Payments.
Oracle Payments Integrating with APIs
Payment Instrument Registration APIs
Payment Instrument APIs provide the functionality to register a payor's bank, credit card, PINless debit card, or purchase card.
OraInstrAdd
This API is provided to register a user's bank, credit card, PINless debit card, or purchase card account information with Oracle Payments. Oracle Payments 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, PINless debit card, purchase 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 Oracle Payments.
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, PINless debit cards, purchase cards, or bank accounts.
Payment Processing APIs
These APIs are the transactional APIs that support various payment operations. The electronic commerce applications use these APIs to process various transaction types. For example, authorization of credit cards, PINless debit cards, and purchase cards, transfer of funds from one bank account to another, capture, cancel, return, and others. A list of such APIs are provided below.
OraPmtReq
This API supports authorization and authorization with capture for credit card, PINless debit card, and purchase card payments. This API also supports inbound account transfers and electronic funds transfer online validation.
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 Oracle Payments 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 a payment.
For example, to modify a payment or capture a payment, the electronic commerce application sends this identifier with other information that is needed to perform the operation requested.
If a payment is either a credit card, PINless debit card, or a purchase card payment, and the request is online, Oracle Payments can perform risk analysis with the payment request (Authorization).
To enable risk analysis with authorization, either setup the payment request with risk flag set to true in one of its input objects (Refer to Java Documentation for details) or check the Enabled radio button in the Risk Management Status screen for that payee. If either of the conditions are satisfied, the electronic commerce application will check the Riskresp object that is returned as part of the payment response object to the Payment Request API. Electronic commerce applications can also invoke the Payment Request API to evaluate a specific formula by passing the PaymentRiskInfo object.
This API is also used after a voice authorization is done to enable Oracle Payments to handle follow-on operations. To use it for a voice authorization, set up the payment request's input objects with the Voice Authorization flag set to true and the Authorization Code variable set to the authorization code issued by the financial institution. See Oracle Payments Java Documentation for details.
OraPmtCanc
A scheduled payment can be canceled by an electronic commerce application using this API.
OraPmtQryTrxn
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 Oracle Payments. History of a payment can also be obtained.
OraPmtCapture
When a credit card or purchase 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, PINless debit card, and purchase card specific operations. It allows processing returns from the payor.
Gateway model payment systems process capture operations online. If the capture is still in the Gateway's open batch (that is, the batch has not been closed) you should call OraPmtVoid. If the batch has been closed, you need to call OraPmtReturn. The batch needs to be closed again before the return is processed. This can be confusing since Gateways can be set up to close batches automatically, for example, once per day.
Processor model payment systems process captures offline. If the capture is still in Payment's open batch, call OraPmtVoid. If the batch has been closed, call OraPmtReturn. The batch needs to be closed again after the return operation for the return to be processed.
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 id (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, and purchase card operations. Oracle Payments supports both online and offline OraPmtVoid API calls.
Voiding auths electronically is not supported by some processors or gateways. Only a few card-issuing banks supported it while the vast majority did not. Cancelling an authorization could only be done by telephone or by letting the auth expire.
Thus, within Payments, calling OraPmtVoid for an Online Auth results in the current payment system servlets returning status 8 - Operation not Supported. For an Offline Auth, you can void the Authorization if it is still in the Payments open batch and has not yet been sent to the payment system.
OraPmtCredit
This API provides credit and Electronic Fund Transfer (EFT) operations. 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 Oracle Payments. 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, or purchase card transactions and if necessary PINless debit card. The transaction types that are included in a batch are: capture, return, and credit. This operation 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.
Risk Management APIs
These APIs allow electronic commerce applications to do risk analysis independently for credit card, PINless debit card, and purchase card transactions. These APIs together can evaluate any risk formula that is configured for a payee.
A risk formula can contain any number of risk factors with different weights associated with them. When Risk API 1 is called, it evaluates all the factors configured in the formula except the AVS Code risk factor. If a risk formula has an AVS Code risk factor, then, Risk API 1, in the response object, indicates that the formula has an AVS Code risk factor. This allows electronic commerce applications to completely or partially check the risk formula and decide whether to perform an authorization or not.
If the response of the first Risk API 1 indicates that the payment is not risky, then electronic commerce application can perform the authorization and complete the rest of the evaluation by calling Risk API 2.
Electronic commerce applications can call Risk API 2 by passing the same payee id, the formula name, and the AVS code that was returned during the authorization response and the risk score that was returned as part of the response in Risk API 1. The response object of Risk API 2 contains the finally evaluated risk score.
Risk API 1
This API evaluates the risk formula associated with the payee id passed as part of the input object, PmtRiskInfo. This API can evaluate a specific formula or the implicit formula depending on the input object. After evaluation, this API constructs the response object indicating if the AVS Code risk factor is a part of the formula or not by setting the flag, AVSCodeFlag. If this flag is set to true, then electronic commerce applications need to call the Risk API 2 to complete the risk evaluation of the formula.
Risk API 2
This API needs to be called when the AVSCodeFlag in RiskAPI 1 response object indicates that the formula contains AVS Code factor. When this API is called, it only evaluates the AVS code factor. The input object of this API contains the same payee id and the formula name that was passed in Risk API 1 and the AVS Code that was returned by the payment system for the payment request. The response object that this API returns, contains the final risk score of the formula.
Credit Card Validation APIs
The Credit Card Validation APIs provide methods for determining the credit card type of a credit card number and for doing basic authentication. Since most credit card types specify the number of digits and a prefix for all valid credit card accounts in their company name, it is possible to determine the credit card types of most credit card numbers. Also, since the digits of most credit card types must (using a special algorithm) be evenly divisible by 10, it is possible to determine if a credit card number is valid or not. These APIs do not perform some of the more advanced credit card verification techniques available to back end payment systems, such as billing address verification. These APIs allow many common errors to be caught, such as wrongly typed or truncated credit card digits. By allowing common errors to be caught by the electronic commerce application, performance is improved, since the cost of calling these APIs is much less than sending a request to the back end payment system.
The Credit Card Validation APIs are created as part of the IBY_CC_VALIDATE package and this package is installed in the APPS schema.
Main Methods of Credit Card Validation APIs
The Credit Card Validation APIs consist of three main methods.
-
Method StripCC is used to format a raw credit card number input by the customer. StripCC removes common filler characters such as hyphens and spaces until it produces a credit card number consisting only of digits. StripCC must be called before the credit card number is passed to the other methods.
-
Method GetCCType returns the credit card type of a credit card number, where each credit card type, including values for invalid and unknown types is a constant in the package.
-
Method ValidateCC, which takes both a credit card number and date. It returns a boolean value indicating whether the credit card can still be used or not.
Note: The IN parameters p_api_version and p_init_msg_list and the OUT parameters x_msg_count and x_msg_data are ignored. If an unexpected error occurs, x_return_status will be set to FND_API.G_RET_STS_UNEXP_ERROR. This will happen if the credit card number has invalid characters in it.
DECLARE
-- each character specifies a possible filler characters in the credit
-- card number; i.e. a character that can safely be stripped away
p_fill_chars VARCHAR(3) := '* -#';
p_cc_number VARCHAR(20) := '4111*1111 1111-1111#';
p_api_version NUMBER := 1.0;
p_init_msg_list VARCHAR2(2000) := ' ';
x_return_status VARCHAR2(2000);
x_msg_count NUMBER;
x_msg_data VARCHAR2(2000);
-- will hold the credit card number stripped of all characters except
-- digits; credit card numbers must be of this form for the GetCCType
-- and ValidateCC methods
v_clean_cc VARCHAR(20);
-- variable to be set by GetCCType method
v_cc_type IBY_CC_VALIDATE.CCType;
-- variable set by ValidateCC method; indicates if the credit card is
-- still usable
v_cc_valid BOOLEAN;
-- credit card expr date; rolled to the end of the month
-- by the ValidateCC method
v_expr_date DATE := SYSDATE();
BEGIN
-- the credit card number must first be stripped of all non-digits!!
IBY_CC_VALIDATE.StripCC( p_api_version, p_init_msg_list, p_cc_number,
p_fill_chars, x_return_status, x_msg_count, x_msg_data,
v_clean_cc );
-- check that illegal characters were not found
IF x_return_status != FND_API.G_RET_STS_UNEXP_ERROR THEN
IBY_CC_VALIDATE.GetCCType( p_api_version, p_init_msg_list, v_clean_cc,
x_return_status, x_msg_count, x_msg_data, v_cc_type);
IF x_return_status != FND_API.G_RET_STS_UNEXP_ERROR THEN
IF v_cc_type=IBY_CC_VALIDATE.c_InvalidCC THEN
DBMS_OUTPUT.PUT_LINE('Credit card number not a valid one.');ELSE
DBMS_OUTPUT.PUT_LINE('Credit card number OK.');END IF;
IBY_CC_VALIDATE.ValidateCC( p_api_version, p_init_msg_list, v_clean_cc,
v_expr_date, x_return_status, x_msg_count, x_msg_data, v_cc_valid);
IF v_cc_valid THEN
DBMS_OUTPUT.PUT_LINE('Credit card is valid.');ELSE
DBMS_OUTPUT.PUT_LINE('Credit card number invalid or has expired.');END IF;
END IF;
END;
Note: An overloaded version of the StripCC method exists. It takes all the same arguments as the version used above except p_fill_chars. It gets its filler characters from the package constant c_FillerChars, which allows spaces and hyphens to be interspersed within the credit card number.
Status Update API
Oracle Payments has defined a PL/SQL API that must be implemented by electronic commerce applications when offline payment processing is performed. This API allows the electronic commerce application to receive a status update. This API must be defined in a package. The 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 if they have offline payments.
The package name has to be of the format <application_short_name>_ecapp_pkg. The application_short_name is a three-letter short name that was given in electronic commerce application registration. 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:
-
totalRows: total number of rows being passed for the update.
-
txn_id_Tab: table of transaction identifiers for which the update is sent.
-
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 reason for having a req-type is to uniquely identify the transaction. For the same transaction identifiers, there can be multiple transactions. e.g. Authorization and Capture. Electronic commerce applications can uniquely identify the transaction based on the values in trxnid and req_type.
The table below lists the various kinds of request types and their descriptions.
req_type Description ORAPMTCAPTURE Capture transaction ORAPMTCREDIT Credit transaction ORAPMTREQ Authorize transaction ORAPMTRETURN Return transaction ORAPMTVOID Void transaction -
Status_Tab: table of statuses corresponding to each transaction.
The table below lists the various values and their statuses.
Value Status 0 Paid 5 Payment failed 13 Scheduled 15 Failed 17 Unpaid 18 Submitted Note: Please refer to Table D-15 for a complete list of values and their statuses.
-
updatedt_Tab: table for the last update date for each transaction.
-
refcode_Tab: table for the reference code for each transaction.
-
o_status: the overall status of the procedure. If there are errors in trying to execute the procedure, electronic commerce application should set up an appropriate value in this field.
-
o_errcode: the error code for any errors which might have occurred during processing.
-
o_errmsg: the error message for the error.
-
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 the value to TRUE for that transaction, otherwise, it should set the value to FALSE.
Note: In the above procedure, for each transaction there will be an entry in the table parameters. If there were ten transactions of this electronic commerce application, whose status has changed, there will be ten entries in each table parameters.
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 Application
For each row update, the status is based on the request type and the 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 information
update tables using status_Tab[i], updatedt_Tab[i], refCode_Tab[i] for
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
Java APIs for Electronic Commerce Application
All administration and inbound payment processing functionalities are provided via the Java PaymentService interface. The following information describes how to access and use Java APIs. Refer to Oracle Payments JavaDoc for more details.
Note: Guest user properties need to be setup in the database before any operation can be performed. Please refer to the Setup Document provided by CRM Foundation 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 PSException
This 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 Code
The 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 API
PSResult 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 succeeded
PSResult.IBY_WARNING// action succeeded with warning
PSResult.IBY_INFO// not yet in use
PSResult.IBY_FAILURE// action failed
If SUCCESS or WARNING is invoked, a result object can always be obtained by using the following API:
public Object getResult();
If FAILURE is invoked, a result object may be returned for payment operation APIs, if this failure occurred with back- end payment system.
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 Oracle Payments Java Documentation for the PaymentService interface.
If WARNING or FAILURE is invoked, a warning or error message is returned. Use the following two APIs to retrieve error codes and error messages.
public String getCode();// get the error code 'IBY_XXXXXX'
public String 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());
Object res=pr.getResult();
if (res!=null) System.out.printIn ("failure occured with backend Payment system");
return res;
}
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 API
After 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 JavaDoc.
Here is some sample codes for the Payment Instrument API, and Payment Processing APIs. These codes use the checkResult call.
Registering a Credit Card
public 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("Paymentech");
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 service
public 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
paymentService.oraPmtReq(ecAppId, "payee1", "", cc, t,
reqTrxn);
resp = (CoreCreditCardAuthResp) checkResult(pr);
if (resp == null) return;
System.out.println("Request finished with transaction id: " +
resp.getTID());
}
Registering a Purchase Card
public void instrAPISample(PaymentService paymentService,
int ecappId) {
PSResult pr;
Object obj;
PurchaseCard pc;
Address addr;
int instrid_pc;
String payerid = "payer1";
addr = new Address("Line1", "Line2", "Line3",
"Redwood Shores", "San Mateo", "CA",
"US", "94065");
// purchase card
pc = new PurchaseCard();
pc.setName("My Purchase Card");
pc.setFIName("Paymentech");
pc.setInstrBuf("This is my purchase card description.");
pc.setInstrNum("4111111111111111"); // the purchase card
// number
pc.setCardType("Constants.CCTYPE_VISA"); // the purchase
// card type, should match the purchase card number, if
// set
pc.setCardSubtype("P");
pc.setExpDate(new java.sql.Date(101, 0, 10));
// Jan 10, 2001
pc.setHolderName("Mary Smith");
pc.setHolderAddress(addr);
// add the purchase card
pr = paymentService.oraInstrAdd(ecappId, payerid, pc);
obj = checkResult(pr);
if (obj == null) return; // registration failure
instrid_pc = ((Integer) obj).intValue();
System.out.println("Purchase Card registered " +
"successfully with instrument id " +
instrid_pc);
}
Sending a Purchase Card Authorization Request
// perform an ONLINE purchase card authorization with
// payment service
public void paymentAPISample(PaymentService paymentService,
int ecAppId) {
Bill t;
PurchaseCardReq reqTrxn;
PurchaseCard pc;
PSResult pr;
CoreCreditCardAuthResp resp; // since purchase card
// authorization responses are identical to credit card
// responses. See javadoc for details.
// 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 PurchaseCardReq();
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);
reqTrxn.setPONum("PONum");
reqTrxn.setTaxAmount("1.50");
reqTrxn.setShipToZip("94065");
reqTrxn.setShipFromZip("94404");
// set up the payment instrument
pc = new PurchaseCard();
pc.setId(100); // assuming we have previously registered
// purchase card with instrument id 100
pr = // assuming payee1 has already been configured with
// the payment service
paymentService.oraPmtReq(ecAppId, "payee1", "", pc,
t, reqTrxn);
resp = (CoreCreditCardAuthResp) checkResult(pr);
if (resp == null) return;
System.out.println("Request finished with " +
"transaction id: " + resp.getTID());
}
PL/SQL APIs for Electronic Commerce Applications
Oracle Payments 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 when PL/SQL APIs are called. When electronic commerce applications invoke these PL/SQL APIs, the APIs in return, call the electronic commerce servlet through HTTP.
Oracle Payments PL/SQL APIs provide all payment related processing and two Risk APIs. The functionality of these APIs is the same as the Java APIs.
PL/SQL APIs are created as part of IBY_PAYMENT_ADAPTER_PUB package and these packages are installed in the APPS schema.
New parameters are included to pass voice authorization flag and authorization date to support passing correct parameters for Payments need:
-
pmtreqtrxn_rec.voiceauthflag
-
pmtreqtrxn_rec.authcode
-
pmtreqtrxn_rec.DateOfVoiceAuthorization
Requirements
Requirements include the following:
-
PL/SQL Package IBY_PAYMENT_ADAPTER_PUB must be installed in the APPS schema.
-
An administrator must set up Oracle Payments URL property to Oracle Payments electronic commerce servlet's URL using the Oracle Payments administration user interface before invoking the APIs.
The following PL/SQL code helps you to understand how Oracle Payments 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;
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
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;
Payment Request Related Response. Printing Only If Status Is Success
If(Char(X_Reqresp_Rec.Response.Status = 'S') Then
-- Offline Mode Related Response
If P_Pmtreqtrxn_Rec.Pmtmode = 'OFFLINE' Then
Dbms_Output.Put_Line('Transaction ID = ' || To_Char(X_Reqresp_Rec.Trxn_ID));
Dbms_Output.Put_Line (' X_Reqresp_Rec.Offlineresp.Earliestsettlement_Date = ' ||
To_Char(X_Reqresp_Rec.Offlineresp.Earliestsettlement_Date));
Dbms_Output.Put_Line('X_Reqresp_Rec.Offlineresp.Scheduled_Date = ' ||
To_Char(X_Reqresp_Rec.Offlineresp.Scheduled_Date));
Else
Dbms_Output.Put_Line('Transaction ID = ' || To_Char(X_Reqresp_Rec.Trxn_ID));
Dbms_Output.Put_Line('X_Reqresp_Rec.Authcode = ' || X_Reqresp_Rec.Authcode);
Dbms_Output.Put_Line('X_Reqresp_Rec.Avscode = ' || X_Reqresp_Rec.Avscode);
Dbms_Output.Put_Line('-------------------------------------------');
-- Risk Related Response
If(X_Reqresp_Rec.Riskrespincluded = 'YES') Then
Dbms_Output.Put_Line('-------------------------------------------');
Dbms_Output.Put_Line(' X_Reqresp_Rec.Riskresponse.Risk_Score= '|| X_Reqresp_Rec.Riskresponse.Risk_Score );
Dbms_Output.Put_Line('X_Reqresp_Rec.Riskresponse.Risk_Threshold_Val= '||
X_Reqresp_Rec.Riskresponse.Risk_Threshold_Val);
Endif;
Endif;
End If;
Security Considerations
Oracle Payments is architected to send credit card details in the URL. This architecture requires the logging levels on Apache to be lowered from the default to prevent the credit card information from appearing in the log files.
In the httpds.conf file, change:
LogFormat "%h %l %u %t \"%r\" %>s %b" common
to:
LogFormat "%h %l %u %t \"%U\" %>s %b" common