PeopleSoft 9.1 PeopleBook: Integration Interfaces

Setting Up the Credit Card Interface

This chapter provides an overview of credit card integration using Integration Broker and discusses how to:

Set up credit card integration for Integration Broker.
Set up credit card interface elements.

Understanding XML-Based Integration Using Integration Broker

You can use PeopleSoft Integration Broker to process your PeopleSoft credit card transactions with the third-party credit card processing vendor of your choice. Oracle delivers messages and a synchronous service for you to use to set up a synchronous connection with your third-party vendor. Because each third-party vendor requires a different format for communication, PeopleSoft applications do not deliver transformations to your third-party vendor. This is because each third-party vendor has different requirements for inputs and outputs to their services. Therefore, part of setting up an integration involves writing your own transformation programs for the request and response message. The transformation programs are a mapping between the fields in the PeopleSoft system and the fields in your third-party vendor’s service. You also need to set up a node in the PeopleSoft application to process the response from your third-party vendor.

Oracle delivers XML messages for use with XML-based credit card processing vendors. You must build your own XML message transformation into the format that the vendor is expecting.

You can use PeopleSoft Application Engine to perform your transformations. You use the delivered EOEC_CCI_SYNC message for the request transaction and the delivered EOEC_CCI_RESPONSE message for the response transaction. The messages are detailed later in this section.

Note. If you have upgraded from a PeopleTools 8.47 or earlier release, the upgrade program creates service operations for these messages. The service operation names and message names are the same.

The diagram shows the process flow for integration with a third-party credit processing vendor.

EOEC_CCI_SYNC and EOEC_CCI_RESPONSE is used to integrate with a third-party credit processing vendor

EOEC_CCI_Sync Message

The EOEC_CCI_SYNC message is a synchronous request that the credit card interface sends to the third-party vendor. The request can be for an authorize, bill, authorize and bill, credit transaction, or authorization reversal. The PeopleCode that supports this message is located in App Package EOEC_CCI. The following tables describe the request fields and how they are populated by the PeopleSoft system.

Level 0 Record: EOEC_CCI_XMLPAY:

Message field	Alias	Populated with
EOEC_CCI_UNIQUE_ID	UNIQUEID	Unique ID generated for each transaction.

Level 1 Record: EOEC_CCI_RQST:

Message field	Alias	Populated with
EOEC_CCI_MERCHANT	VENDOR	Populated from the merchant ID set up on the Credit Card Interface Installation page.
EOEC_CCI_PARTNER	PARTNER	Hardcoded to “PeopleSoft”.

Level 2 Record: EOEC_CCI_TRANS:

Message field	Alias	Populated with
EOEC_CCI_TRANSID	TRANSACTION_ID	Either blank or contains the request ID of a previous transaction (such as a prior authorization transaction).
EOEC_CCI_MERCH_REF	TRANSACTION_CUSTREF	Contains a reference to the transaction such as an order or invoice number.
EOEC_CCI_RQSTTOKEN	N/A	Either blank or contains the request token of a previous transaction (such as a prior authorization transaction).

Level 3 Record: EOEC_CCI_TRNTYP:

Message field	Alias	Populated with
EOEC_CCI_TRANSACT	TRANSTYPE	The service to be performed: 1=Authorize Only 2=Authorize & Bill 3=Bill Only 4=Credit 5=Authorize Reversal

Message field

Alias

Populated with

EOEC_CCI_TRANSACT

TRANSTYPE

The service to be performed:

1=Authorize Only
2=Authorize & Bill
3=Bill Only
4=Credit
5=Authorize Reversal

Level 4 Record: EOEC_CCI_PAYDAT:

Message field	Alias	Populated with
EOEC_CCI_TRANSACT	N/A	N/A

Level 5 Record: EOEC_CCI_INV:

Message field	Alias	Populated with
EOEC_CCI_INV_NUM	INVNUM	Either blank or contains the request ID of a pervious transaction (such as a prior authorization transaction). Oracle recommends that you use TRANSACTION_ID instead of INVNUM in transformation programs because the field is only 20.
EOEC_DATE		N/A
DESCR254	DESCRIPTION	Hardcoded to “Description”.
EOEC_CCI_DISC_AMT	DISCOUNTAMT	N/A
EOEC_CCI_SHIP_AMT	SHIPAMT	N/A
EOEC_CCI_DUTY_AMT	DUTYAMT	N/A
EOEC_CCI_TAX_AMT	TAXAMT	N/A
EOEC_CCI_TAX_INCL	NATIONALTAXINCL	N/A
EOEC_CCI_TOTAL_AMT	TOTALAMT	The total amount of the transaction.
EOEC_CCI_COMMENT	COMMENT	N/A
CURRENCY_CD	N/A	N/A

Level 6 Record: EOEC_CCI_BILLFM:

Message field	Alias	Populated with
EOEC_CCI_FULLNAME	NAME	N/A
EOEC_EMAIL_ADDR	EMAIL	N/A
PHONE	N/A	N/A
FAX	N/A	N/A
URL	N/A	N/A

Level 7 Record: EOEC_CCI_ADDR1:

Message field	Alias	Populated with
ADDRESS1	STREET	N/A
ADDRESS2	N/A	N/A
ADDRESS3	N/A	N/A
ADDRESS4	N/A	N/A
CITY	N/A	N/A
STATE	N/A	N/A
POSTAL	ZIP	N/A
COUNTRY	N/A	N/A

Level 6 Record: EOEC_CCI_BILLTO:

Message field	Alias	Populated with
EOEC_CCI_CUSTID	CUSTOMERID	N/A
EOEC_CCI_FULLNAME	NAME	N/A
EOEC_EMAIL_ADDR	EMAIL	Email address of the consumer.
PHONE	N/A	Telephone number of the consumer.
FAX	N/A	N/A
EOEC_CCI_CUSTCODE	CUSTCODE	N/A
EOEC_CCI_PO_NUM	PONUM	N/A
EOEC_CCI_TAXEXEMPT	TAXEXEMPT	N/A

Level 7 Record: EOEC_CCI_ADDR2:

Message field	Alias	Populated with
ADDRESS1	STREET	Street address of the consumer.
ADDRESS2	N/A	N/A
ADDRESS3	N/A	N/A
ADDRESS4	N/A	N/A
CITY	N/A	City address of the consumer.
STATE	N/A	State address of the consumer.
POSTAL	ZIP	Postal address of the consumer.
COUNTRY	N/A	Country address of the consumer.

Level 6 Record: EOEC_CCI_SHIPFM:

Message field	Alias	Populated with
EOEC_CCI_FULLNAME	NAME	N/A
EOEC_EMAIL_ADDR	EMAIL	N/A
PHONE	N/A	N/A
FAX	N/A	N/A

Level 7 Record: EOEC_CCI_ADDR3:

Message field	Alias	Populated with
ADDRESS1	STREET	N/A
ADDRESS2	N/A	N/A
ADDRESS3	N/A	N/A
ADDRESS4	N/A	N/A
CITY	N/A	N/A
STATE	N/A	N/A
POSTAL	ZIP	N/A
COUNTRY	N/A	N/A

Level 6 Record: EOEC_CCI_SHIPTO:

Message field	Alias	Populated with
EOEC_CCI_FULLNAME	NAME	N/A
EOEC_EMAIL_ADDR	EMAIL	N/A
PHONE	N/A	N/A
FAX	N/A	N/A

Level 7 Record: EOEC_CCI_ADDR4:

Message field	Alias	Populated with
ADDRESS1	STREET	N/A
ADDRESS2	N/A	N/A
ADDRESS3	N/A	N/A
ADDRESS4	N/A	N/A
CITY	N/A	N/A
STATE	N/A	N/A
POSTAL	ZIP	N/A
COUNTRY	N/A	N/A

Level 6 Record: EOEC_CCI_ITEM:

Message field	Alias	Populated with
EOEC_CCI_ITEM NUM	ITEM_NUMBER	N/A
EOEC_CCI_SKU	SKU	N/A
EOEC_CCI_UPC	UPC	N/A
DESCR254	DESCRIPTION	N/A
EOEC_CCI_QTY AMT TOTALAMT	QUANTITY	N/A
EOEC_CCI_UOM	UNITOFMEASURE	N/A
EOEC_CCI_UNITPRICE	UNITPRICE	N/A
EOEC__CCI_EXTAMT	EXTAMT	N/A
EOEC_CCI_DISC_AMT	DISCOUNTAMT	N/A
EOEC_CCI_TAX_AMT	TAXAMT _	N/A
EOEC_CCI_TOTAL	TOTALAMT	N/A

Level 4 Record: EOEC_CCI_TENDER:

Message field	Alias	Populated with
EOEC_CCI_TRANSACT	N/A	N/A

Level 5 Record: EOEC_CCI_CARD:

Message field	Alias	Populated with
EOEC_CCI_TYPE	CARDTYPE	Two-character code for the type of card used in the transaction. 01=Visa 02=MasterCard 03=Diners Club 04=American Express 05=Discover
EOEC_CCI_NUMBER	CARDNUM	Credit card number used in the transaction.
EOEC_CCI_EXPYR	EXPYR	Expiration year of the card.
EOEC_CCI_EXPMO	EXPMO	Expiration month of the card.
EOEC_CCI_CVNUM	CVNUM	Card verification number.
EOEC_CCI_MAGDATA	MAGDATA	N/A
EOEC_CCI_FULLNAME	NAMEONCARD	First and last name of the consumer.
EOEC_CCI_FNAME	FIRSTNAME	First name of the consumer.
EOEC_CCI_LNAME	LASTNAME	Last name of the consumer.

Level 5 Record: EOEC_CCI_STATUS:

Message field	Alias	Populated with
EOEC_CCI_TRANS_REF	PNREF	N/A

Note. When writing your transformation program, use the alias name to reference the fields. When you view the “Request — Original” text of the message, the alias name is displayed.

EOEC_CCI_RESPONSE Message

The EOEC_CCI_RESPONSE message is a response to the request that the credit card interface receives from the third-party vendor. Your transformation should populate the response message fields as shown in the tables.

Level 0 Record: EOEC_CCI_XMLRSP:

Message field	Alias	Populate with
EOEC_CCI_UNIQUE_ID	UNIQUEID	N/A

Level 1 Record: EOEC_CCI_RSPNS:

Message field	Alias	Populate with
EOEC_CCI_MERCHANT	VENDOR	N/A
EOEC_CCI_PARTNER	PARTNER	N/A

Level 2 Record: EOEC_CCI_TRRSLT:

Message field	Alias	Populate with
EOEC_CCI_TRANSID	TRANSACTIONID	The request ID or identifier returned from the third-party vendor.
EOEC_CCI_RESULT	RESULT	Map the appropriate return code for the transmission result in the following way: 0=Approve (no error) 100-199=Decline For self-service application, you can display the vendor return message to self-service users. 200-299=Decline For self-service application, do not display the vendor return message to self-service users. 300-399=Connection Error
EOEC_CCI_AVS	AVS	N/A
EOEC_CCI_CVRESULT	CVRESULT	N/A
EOEC_CCI_RET_MSG	MESSAGE	Populate this with a text response from the vendor or this can be populated with text that explains to the user why a transaction was not successful.
EOEC_CCI_TRANS_REF	PNREF	N/A
EOEC_RET_AUTHCD	AUTHCODE	This should be populated with the authorization code returned from the vendor.
EOEC_CCI_HOSTCODE	HOSTCODE	N/A
EOEC_CCI_HOST_URL	HOSTURL	N/A
EOEC_CCI_ORIGRSLT	ORIGRESULT	N/A
EOEC_RET_STATUS	TRSTATUS	N/A
EOEC_RET_STATUSMSG	N/A	N/A
EOEC_RET_AUTHDTTM	N/A	N/A
EOEC_CCI_RQSTTOKEN	N/A	N/A

Level 3 Record: EOEC_CCI_AVRSLT

Message field	Alias	Populate with
EOEC_MATCH_STREET	STREETMATCH	N/A
EOEC_MATCH_ZIP	ZIPMATCH	N/A

When writing the transformation program, use the alias name to reference the fields.

Note. The alias name is shown in the “Response — Original” message from within the Service Operations Monitor.

Agents can then process credit cards using their application-specific credit card transaction page to submit the transaction to the vendor for authorization, billing, authorization and billing, or credit. You can choose which types of transactions to permit.

Setting Up Credit Card Integration for Integration Broker

This section discusses how to configure integration for Integration Broker.

Configuring Integration for Integration Broker

To set up Integration Broker for credit card processing:

Define the Integration Broker Gateway if it's not already done.
Activate the delivered service (EOEC_CCI_SYNC) that is used for the credit card integration.
Set up an external node to use when using the XML-based interface to which the XML messages should be sent and to indicate where the processor is located.

Also specify the authentication option that you arranged with the credit card processor.
Set up routings.

Use the Routings tab in the Node component to add the EOEC_CCI_SYNC service to the node. To see the XML data before and after transformations, set the log detail to Header & Detail. This is helpful when troubleshooting your new integration.
Test the integration.

You can use the test component described below.

If you receive error messages when using Integration Broker, see the Troubleshooting the Integration Broker Setup section below:

Troubleshooting the Integration Broker Setup

Several sources of information are available when the setup is not successful. These include but are not limited to:

Error messages stored on the message instance (view with the message monitor).
IB gateway error log (http://<GatewayMachine>:<Port>/PSIGW/errorLog.html).
IB gateway message log (http://<GatewayMachine>:<Port>/PSIGW/msgLog.html).
Application server log for the active IB domain server on the database.
Web server logs.

You can also do the following:

Increase the log fence on the gateway properties file. This file is located in the following directory: PS_CFG_HOME\webserv\<web-server>\applications\peoplesfoft\PSIGW

If you set the log fence to five in the integration Gateway properties, you will receive more details in the error and message logs.
Check the Service Operations Monitor to view the XML messages before and after the transformations (PeopleTools, Integration Broker, Monitor, Service Operations, Synchronous Services).

Check the Header and Detail logs on the Synchronous Detail page (PeopleTools, Integration Broker, Service Operations Monitor, Monitor, Synchronous Details).

Problems are usually due to incorrect transformations between the two systems. Use these logs to ensure that your transformations are correct.

Your Response-Transformed message structure should look similar to this:

<?xml version="1.0"?>
<EOEC_CCI_RESPONSE xmlns:c="yourcompany.com">
  <FieldTypes>
    <EOEC_CCI_XMLRSP class="R"/>
    <EOEC_CCI_TRRSLT class="R">
      <RESULT type="NUMBER"/>
    </EOEC_CCI_TRRSLT>
    <EOEC_CCI_AVRSLT class="R"/>
    <EOEC_CCI_RSPNS class="R"/>
    <PSCAMA class="R"/>
  </FieldTypes>
  <MsgData>
    <Transaction>
      <EOEC_CCI_XMLRSP class="R">
        <UNIQUEID/>
        <EOEC_CCI_RSPNS class="R">
          <VENDOR/>
          <PARTNER/>
          <EOEC_CCI_TRRSLT class="R">
            <TRANSACTIONID>177</TRANSACTIONID>
            <RESULT>0</RESULT>
            <AVS/>
            <CVRESULT/>
            <MESSAGE/>
            <AUTHCODE>123456</AUTHCODE>
            <HOSTCODE/>
            <HOSTURL/>
            <ORIGRESULT/>
            <TRSTATUS/>
            <EOEC_RET_STATUSMSG/>
            <EOEC_RET_AUTHDTTM/>
            <EOEC_CCI_AVRSLT class="R">
              <STREETMATCH/>
            </EOEC_CCI_AVRSLT>
          </EOEC_CCI_TRRSLT>
        </EOEC_CCI_RSPNS>
      </EOEC_CCI_XMLRSP>
    </Transaction>
  </MsgData>
</EOEC_CCI_RESPONSE>

Setting Up Credit Card Interface Elements

This section discusses how to:

Define connection parameters.
Define accepted credit card types.
Test the credit card interface.
Test credit card transactions.

Note. The information is this section is used for credit card integration using Integration Broker, or any manual processing that you have set up for credit card processing vendors.

Pages Used to Set Up Credit Card Interface Elements

Page Name	Definition Name	Navigation	Usage
Credit Card Interface Installation	EOEC_CCI_INSTAL	Enterprise Components, Component Configurations, Credit Card Interface, Setup	Define connection parameters for credit card processing calls to a third-party vendor. Before you set up credit card processing options, establish your merchant account with a third-party vendor.
Card Type	EOEC_CCI_CARDTYPE	Enterprise Components, Component Configurations, Credit Card Interface, Credit Card Types	Define the types of credit cards you accept for credit card processing.
Test Credit Card Interface - Card Entry/Display	EOEC_CCI_TEST	Enterprise Components, Component Configurations, Credit Card Interface, Test Credit Card Interface, Card Entry/Display	Enter test credit card information that you can submit to verify that your credit card processing is functioning properly.
Test Credit Card Interface - Transaction	EOEC_CCI_TRANSACT	Enterprise Components, Component Configurations, Credit Card Interface, Test Credit Card Interface, Transaction	Enter test credit card transaction information that you can submit to verify that your credit card processing is functioning properly.

Defining Connection Parameters

Access the Credit Card Interface Installation page (Enterprise Components, Component Configurations, Credit Card Interface, Setup).

Use the Credit Card Interface Installation (EOEC_CCI_INSTAL) page to set up connection parameters for credit card processing calls to a third-party vendor.

Note. Before you set up credit card processing options, establish your merchant account with a third-party vendor.

Note. Check the installation documentation for the product you are installing for specific details on setting up credit card interfaces.

Verify connection requirements with your vendor.

Credit Card Merchant ID	Enter the merchant ID supplied by your vendor.
Credit Card Hist. Backup Days (credit card history backup days)	If you create a process that archives history records, specify the number of days that you retain credit card authorization history records.
Credit Card Tracing	This field is currently not used.
On-line Transmission Retries	Enter a value from 0 through 9 to specify how many times the system should attempt to retransmit transactions in the event of transmission failure.
Address Verification Flag	Credit card transmissions can fail authorization if the address that you send doesn't exactly match the billing address for the credit card. Select from: Add Vf ON (address verification on): Transactions fail when the address that you send does not match the credit card billing address. This is the default value. Add Vf OFF (address verification off): Transactions do not fail when the address that you send does not match the billing address on the credit card.
Type of Interface	Select to use Integration Broker as the interface type.

Allowed Transaction Types

Credit Card Transaction Type

Select the types of transactions that your agents are allowed to submit. Disallowed transaction types are not available on the application-specific credit card transaction page. Select from:

Authorization Reversal: Your vendor can cancel the transaction after authorization and before payment is received. This makes the funds available if the transaction is cancelled.

Authorize Only: Your vendor verifies that the card is valid for the charge. For example, the customer has enough credit to pay for the order, the card is not stolen, and so forth. The vendor does not bill the credit card.

Bill Only: Your vendor bills the card without first verifying that the card is valid for the charge. Select this option if you have preauthorized the transaction and you want to submit the transaction for billing only.

Authorize and Bill: Your vendor performs both authorization and billing during the same transaction. The vendor charges the customer’s credit card on receiving authorization.

Credit Only: Your vendor credits the customer’s credit card.

Process Credits

Select to permit agents to submit credit transactions as well as billing transactions. This option is available only if you selected either Authorize and Bill or Bill Only in the Credit Card Transaction Types field.

Connection Parameters

The third-party vendor that you integrate with will provide you with information to connect with their systems. Enter that information to enable your PeopleSoft system to make the connection when you submit a transaction for processing.

Defining Accepted Credit Card Types

Access the Card Type page (Enterprise Components, Component Configurations, Credit Card Interface, Credit Card Types).

Use this page to define the types of credit cards that you accept for credit card processing.

Oracle delivers data for most popular credit card types. You can modify existing definitions and add new ones.

Credit Card Type	Enter a value for the credit card.
Credit Card Name	Enter a credit card name such as Visa or MasterCard. The name should match the credit card type so that you can identify the card without memorizing the credit card type codes.
Credit Card Number Length	Enter the card's standard credit card number length. Before transmitting a request to your vendor, the system validates the length of the credit card number against this number.
Credit Card Status	Select Active if you accept this type of credit card. Select Inactive if you don’t accept this type of credit card. Inactive credit card types do not appear on the application-specific credit card transaction page or in the Test Credit Card Interface component. The default value for this field is Inactive.
Credit Card Valid Prefixes	Enter all valid prefixes for this type of credit card. Enter multiple prefixes in comma-separated format with no spaces in between. The system removes any characters other than numbers and commas when you move to another field. Before transmitting a request to your vendor, the system validates that the credit card number starts with a valid prefix.
Use Check Digit Algorithm	Select Y (yes) to use the modulus (MOD) 10 check digit algorithm to validate credit card numbers before transmitting requests to your vendor. The MOD 10 check digit algorithm verifies whether card numbers you enter into the system are legitimate. The default value for this field is N.
Credit Card Expiration Days	Enter a four digit numerical expiration value.

Testing the Credit Card Interface

Access the Test Credit Card Interface - Card Entry/Display page (Enterprise Components, Component Configurations, Credit Card Interface, Test Credit Card Interface, Card Entry/Display).

Use this page to enter test credit card information that you can submit to verify that your credit card processing is functioning properly.

The test that you can run on this page:

Verifies that the card number you enter meets the requirements defined in the Credit Card Valid Prefixes field for the associated card type on the Card Type page.
If you have set the Use Check Digit Algorithm field value to Y, verifies that the card number is valid based on the MOD 10 check digit algorithm.
Verifies that you have entered values in the Exp. Month, Expiration Year, First Name and Last Name fields on this page.

You can use the following credit card sample data in your test transactions:

Credit Card Type	Credit Card Number
American Express	378282246310005
Diners Club/Carte Blanche	38000000000006
Discover	6011111111111117
MasterCard	5555555555554444
Visa	4111111111111111

Card Type	Select a card type to test. Available values are defined on the Credit Card Types page.
Credit Card Number	Enter the credit card number to test.
Exp. Month (expiration month), Expiration Year, Card Verification Number, First Name and Last Name	Enter card information to test. Card verification number is optional in running credit card tests.
Toggle Display	Click to switch between display-only and editable modes.
Test	Click to begin the test.
Test Results	The results of the test appear in this text box. If the card number is valid, the message VALID CARD NUMBER appears. If the card number is not valid, an explanatory message appears; the card number is incorrect or the card is expired, for example.

Testing Credit Card Transactions

Access the Credit Card Transaction Test page (Enterprise Components, Component Configurations, Credit Card Interface, Test Credit Card Interface, Transaction).

Use this page to enter test credit card transaction information that you can submit to verify that your credit card processing is functioning properly.

The test that you can run on this page verifies that your environment is set up correctly to process online credit card transactions using XML Compliant integration.

Note. This does not test the environment that is set up for batch credit card transactions.

Sequence and Request ID	Display a combination of numbers that distinguishes the transaction from other transactions. The combination of numbers are similar to a run control or job number.
Amount	Enter a transaction amount and click the Look up button to select a transaction currency.
Token	The token is a response value that is returned from the Credit Card processing service. It is another validation that can be referenced in regards to a specific transaction.
Trans. Type (transaction type)	Choose a transaction type to test: Auth/Bill (Authorization/Bill): Perform both authorization and billing during the same transaction. AuthRev (Authorization Reversal): Cancel the transaction after authorization and before payment is received. Authorize: (default value) Verify that the card is valid for the charge. Bill: Bill the card without first verifying that the card is valid for the charge. Credit: Credit the customer’s credit card.
Class ID	Select TestTransaction (the default) or one of the following interface types that has been specified on the Credit Card Interface Installation page. ProcessBrokerTransaction: Select if you want to test your XML-based interface. InterlinkTransaction: Select if you want to test your Business Interlink interface.
Process	Click to process the test transaction.
Return Code	Enter a return code to test whether proper error messages and results are returned. Available codes and their descriptions are discussed in the Return Codes section subsequently.
Test Results	The results of the transaction test appear in this text box. Test result interpretations are discussed in the following sections.

Return Codes

You can enter any of the following return codes and click Process to view the corresponding description and error message in the Test Results area. These return codes and their corresponding error messages can appear in multiple areas. For example, when you are using the Test Credit Card Interface component, they appear on this test page. In an application, they appear as appropriate for that application's method of interacting with the credit card interface.

Return Code	Description
-3	Error Opening Trace File
-4	Vendor Error − ICS_INIT failed
-5	Unsupported Service
-6	Credit card number is invalid
-7	Phone number is too long
-8	State field length is invalid
-9	Zip Code field is too long
-10	Amount must be greater than zero
-11	Vendor Error − ICS_SEND failed
-12	Decryption Failed
-15	Request ID is required
-16	Currency is required
-17	Phone is required
-18	Email ID is required
-19	Zip Code is required
-20	City is required
-21	Country code is required
-23	Address 1 is required
-99	Trace Run Only