Return to Navigation

Payment Integration Web Service Operations

This section discusses the SSF_INITIATE_EPAYMENT and SSF_COMPLETE_EPAYMENT service operations for the SSF_EPAYMENT_TRANSACTION service.

Note: The payment integration service operations are delivered for only supporting online applications. These service operations are not intended to be used for any other purpose.

Note: The schema diagrams in this section may get updated with future bundle releases.

This service operation enables the user to record a newly initiated electronic payment in Student Financials and provides access to Campus Solutions’ hosted payment framework. The hosted payment framework provides information necessary to transition the user to a designated third party payment provider’s hosted site to make a payment. The insert into the GL_TXN table, for the general ledger process, will not be done until the Complete ePayment service operation (SSF_COMPLETE_EPAYMENT) is invoked successfully.

This web service operation is adapter-based. AAWS has been delivered with its own custom Payment Application adapter and will perform its own validation according to the admissions application functional requirements.

Note that the Initiate ePayment service operation operates only within the Self Service mode (and cannot be used within the Administrator mode).

Details:

   

Description:

The Initiate ePayment service operation call will create a new SF Payment in Student Financials in Initiated status, assigning a new SF Payment Reference Number (SF_PMT_REF_NBR) for tracking. This service uses the payment application’s own tracking number as the merchant reference number passed to the third party payment processor. For AAWS, that tracking number is the application number (ADM_APPL_NBR). The application number will be stored in the SF Payment as ADM_APPL_NBR and SSF_EXT_TRANS_REF and the SF Payment Reference number will be stored in the Admissions Tender Staging table. In addition, the Temp ID will be stored in the SF Payment and Log. The service, through the AAWS adapter, will create new Admissions Tender Staging records (if they do not exist) for all tenders associated with the application center used in the creation of the application.

The Initiate ePayment service will perform initial validation. For instance, the payment method must be either credit card or electronic check (CC or EC), the amount has to be greater than zero, and the Payment Application must be defined in the system table SSF_ELEC_PMTS.

When the AAWS adapter is invoked, it will perform further validation on the transaction.

  • The payment amount and currency must match the previously calculated application fee stored in the Admissions Application Staging record (SAD_APL_DAT_STG). This amount should have been previously calculated in and returned from the submit web service operation.

  • The transaction must have been originated by the owner of the application.

  • The application must be in Saved (SV) status.

  • If the payment is for a credit card tender type, the SF Merchant must be defined in the application center associated with the application. For electronic check transactions, the Electronic Check Merchant ID must be defined in the Application Center. These SF Merchants must be associated with Payment Merchants that are defined as hosted.

  • The tender used must be defined as a valid tender on the Application Fee code associated with the application center.

Users:

An applicant using an online application.

Processing:

This service operation performs the following steps:

  1. Validate the parameters passed in to the web service.

  2. Create a SF Payment to record the transaction. The SF Payment will be in Initiated status. For AAWS, SF Payment Detail records, which will later be used to record the transaction in the General Ledger, will be based on the Application Fee Item Type setup.

  3. Call the AAWS adapter to:

    • Validate the application.

    • Validate the payment parameters.

    • Create Application Tender Staging records.

    • Save the application.

  4. Call the hosted payment framework. The hosted payment framework will:

    • Based on the hosted payment adapter associated with the Payment Merchant, perform an initial web service callout to the third party to pass demographic information about the applicant, such as name, address, email and phone. Note that this information may or may not be used, depending on the third party payment processor. In addition, a shared secret may be passed to the third party to authenticate electronic check transactions. For AAWS, this shared secret is the Constituent birth date. The third party will return a temporary token that identifies the transaction to both the third party and Campus Solutions.

    • Using the HTML object definition on the Payment Merchant, create a string that will be used to either http post or redirect to the third party.

Output:

After completing the processing steps, the service operation:

  1. Records the transaction in the SF Payment table and Detail records.

  2. Creates new Admissions Application Tender Staging records.

  3. Optionally, performs a web service callout to the third party payment processor to pass demographic information and receive a token identifying the transaction.

Error Conditions:

The following conditions result in a service error:

  • The payment method is invalid.

  • The payment amount is zero.

  • The Payment Application is invalid.

  • Required input parameters have not been supplied by the user.

  • The transaction does not pass the AAWS adapter validation.

Input Message: SSF_INITIATE_EPAYMENT_REQ

Image: SSF_INITIATE_EPAYMENT_REQ Message Parameters

This image shows the input parameters that the SSF_INITIATE_EPAYMENT service operation receives from an online application.

SSF_INITIATE_EPAYMENT_REQ Message Parameters

Required data that the online application must supply to the service operation:

  • Payment Application

  • Payment Application Key (Application Number)

  • Payment Amount

  • Currency Code

  • Payment Method (Credit card or electronic check)

The following is an example of the SSF_INITIATE_EPAYMENT_REQ message that the SSF_INITIATE_EPAYMENT service operation receives from an online application:

<?xml version="1.0"?>
<SSF_INITIATE_EPAYMENT_REQ xmlns="http://xmlns.oracle.com/Enterprise/HCM/services">
  <SCC_PMT_APPL>SADAAWS</SCC_PMT_APPL>
  <SCC_PMT_APPL_KEY>00024828</SCC_PMT_APPL_KEY>
  <SCC_EPAY_TOTAL_AMT>20</SCC_EPAY_TOTAL_AMT>
  <CURRENCY_CD>USD</CURRENCY_CD>
  <SCC_EPAY_PAYMETHOD>CC</SCC_EPAY_PAYMETHOD>
</SSF_INITIATE_EPAYMENT_REQ>

Output Message: SSF_INITIATE_EPAYMENT_RESP

When the Integration Broker receives the SSF_INITIATE_EPAYMENT_REQ message, it responds with the SSF_INITIATE_EPAYMENT_RESP message.

Image: SSF_INITIATE_EPAYMENT_RESP Message Parameters

This image shows the output parameters that the SSF_INITIATE_EPAYMENT service operation passes to the online application.

SSF_INITIATE_EPAYMENT_RESP Message Parameters

The following is an example of the SSF_INITIATE_EPAYMENT_RESP message that the SSF_INITIATE_EPAYMENT service operation transmits to the online application:

<?xml version="1.0"?>
<SSF_INITIATE_EPAYMENT_RESP xmlns="http://xmlns.oracle.com/Enterprise/HCM/services">
  <SCC_REDIRECT>N</SCC_REDIRECT>
  <SCC_HTML_STRING>
    <![CDATA*<SCRIPT LANGUAGE='JavaScript'>
writeConsole('https://someserver/C30002test_upay/web/index.jsp', '<input type="HIDDEN" name="TICKET_NAME" value="SADAAWS"><input type="HIDDEN" name="UPAY_SITE_ID" value="12"><input type="HIDDEN" name="TICKET" value="ce224625-e55c-4346-b87c-96f784f5ae90">');
function writeConsole(bind1, bind2)
{
var stuff = '<form name="payform" action="'+bind1+
'" method="POST">'+bind2+'<SCRIPT LANGUAGE="JavaScript" onload="submitForm()">'+
'function submitForm(){document.payform.submit()}'+
'</'+'SCRIPT>'+'</'+'form'+'>';
document.body.innerHTML = stuff;
document.payform.submit();
}
</SCRIPT>*]>
  </SCC_HTML_STRING>
  <SCC_HPAY_INTG_ID>QA_CS_AAWS_MODEL1A</SCC_HPAY_INTG_ID>
</SSF_INITIATE_EPAYMENT_RESP>

Fault Message: SSF_TRANS_FAULT_RESP

If the service operation encounters an error condition, it responds with the SSF_TRANS_FAULT_RESP message.

The following is an example of the SSF_TRANS_FAULT_RESP message that the SSF_INITIATE_EPAYMENT service operation transmits to the online application:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>Client</faultcode>
      <faultstring>An Error occurred processing this request (14098,286)</faultstring>
      <detail>
        <MSGS>
          <MSG>
            <ID>14871-11</ID>
            <DESCR>The Payment Amount must be greater than zero. (14871,11)</DESCR>
          </MSG>
        </MSGS>
      </detail>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This web service operation completes a previously initiated (SSF_INITIATE_EPAYMENT) SF Payment, by authorizing the transaction and submitting the application. If authorization is successful, the SF Payment Transaction Manager will create the Direct GL Transaction.

After having successfully invoked the SSF_INITIATE_EPAYMENT service operation, the Online Application should transition the applicant to the third party payment provider using the SCC_HTML_STRING returned from the SSF_INITIATE_EPAYMENT response. This next web service should be invoked after the transaction is submitted by the applicant from the third party payment processor user interface.

Details:

   

Description:

The Complete ePayment web service operation interprets the response from the third party payment processor by invoking the hosted payment framework. The data received from the third party is transformed into Campus Solutions data elements to allow the update of both Student Financials tables and the calling Payment Application (AAWS).

If the user submitted the transaction successfully from the third party processor, this web service operation will complete any processing required in Student Financials to record the payment. The session ID, which is a unique token generated and returned by the third party to identify the payment, as well as the last 4 digits of the credit card or account number, will be stored in the SF Payment table from within the hosted payment framework.

The ePayment API will be invoked to authorize the transaction. If successful, the payment will be processed in Student Financials by setting the SF Payment status to Complete (SF_PAYMENT_STATUS = B), creating the SF Payment Log with the results of the authorization, and eventually deleting the SF Payment.

The transaction will be recorded directly in the General Ledger using the Direct to GL API (as opposed to posting to a Student Financials account).

Finally, the adapter for AAWS will be invoked to submit the application. The application fee status will be set to Received, the Application Fee Paid amount and GL Sent Amount will be set to the Payment Amount. The Admissions Application Tender Staging record’s tender amount will also be set to the Payment Amount.

If the user cancelled the transaction from the third party payment processor’s hosted site, the SF Payment status will be set to Cancelled. No update will occur on the AAWS adapter and the applicant can submit another payment against the application.

Users:

An applicant using an online application.

Processing:

This service operation performs the following steps:

  1. Validate the parameters passed in to the web service.

  2. Call the Hosted Payment framework using the Hosted Payment adapter passed into the web service. The hosted payment framework will interpret the name/value pairs and transform them into Campus Solutions data elements using the hosted payment adapter settings. It will extract the Payment Application ID and Key (application number) to correctly identify the transaction. It will update the session id and last 4 digits of the account or credit card number in the SF Payment.

  3. Complete the SF Payment associated with the application. For successfully submitted transactions, the transaction will be authorized and sent to the General Ledger.

  4. Call the AAWS adapter to update the proper fields in the application and submit it.

Output:

After completing the processing steps, the service operation:

  1. Sets the SF Payment status to Complete or Cancelled according to the user action on the third party processor. It will set the status to Declined if authorization fails. The SF Payment will be deleted and the SF Payment Log will be created to record the transaction results.

  2. Creates the General Ledger Transaction records for later processing to the General Ledger.

  3. Submits the application if the payment was successfully authorized.

Error Conditions:

The following conditions result in a service error:

  • The Hosted Payment Adapter ID is invalid.

  • The Return URL type is invalid (Valid values are S, C or E)

  • The Payment Application is invalid.

  • Required input parameters have not been supplied by user.

  • The transaction does not pass the AAWS adapter validation.

Input Message: SSF_COMPLETE_EPAYMENT_REQ

Image: SSF_COMPLETE_EPAYMENT_REQ Message Parameters

This image shows the input parameters that the SSF_COMPLETE_EPAYMENT service operation receives from an online application.

SSF_COMPLETE_EPAYMENT_REQ Message Parameters

Required data that the online application must supply to the service operation:

  • Hosted Payment Adapter ID.

  • Return URL Type (Success, Cancelled, Error).

  • Hosted Payment Response Values (Name/Value pairs returned from third party). These values are expected to correspond to the values under the Third Party Parameter Name of Inbound Parameters grid of Hosted Payment Adapter Setting. For example:

    Image: Hosted Payment Adapter Setting Example

    This example illustrates a Hosted Payment Adapter setting.

    Hosted Payment Adapter Setting Example

The following is an example of the SSF_COMPLETE_EPAYMENT_REQ message that the SSF_COMPLETE_EPAYMENT service operation receives from an online application:

<?xml version="1.0"?>
<SSF_COMPLETE_EPAYMENT_REQ xmlns="http://xmlns.oracle.com/Enterprise/HCM/services">
  <SCC_HPAY_INTG_ID>QA_CS_AAWS_MODEL1A</SCC_HPAY_INTG_ID>
  <SCC_EPAY_URL_TYPE>S</SCC_EPAY_URL_TYPE>
  <SCC_HP_RESPONSE_VALUES>
    <SCC_TP_PARM>
      <name>session_identifier</name>
      <value>5c012fb4-43a4-4ffd-be63-a1415ce2b7e4</value>
    </SCC_TP_PARM>
    <SCC_TP_PARM>
      <name>UPAY_SITE_ID</name>
      <value>12</value>
    </SCC_TP_PARM>
    <SCC_TP_PARM>
      <name>EXT_TRANS_ID</name>
      <value>SADAAWS_00024863</value>
    </SCC_TP_PARM>
    <SCC_TP_PARM>
      <name>acct_number</name>
      <value>XXXXXXXXX2222</value>
    </SCC_TP_PARM>
    <SCC_TP_PARM>
      <name>acct_number</name>
      <value>XXXXXXXXX2222</value>
    </SCC_TP_PARM>
  </SCC_HP_RESPONSE_VALUES>
</SSF_COMPLETE_EPAYMENT_REQ>

Output Message: SSF_COMPLETE_EPAYMENT_RESP

When the Integration Broker receives the SSF_COMPLETE_EPAYMENT_REQ message, it responds with the SSF_COMPLETE_EPAYMENT_RESP message.

Image: SSF_COMPLETE_EPAYMENT_RESP Message Parameters

This image shows the output parameters that the SSF_COMPLETE_EPAYMENT service operation passes to the online application.

SSF_COMPLETE_EPAYMENT_RESP Message Parameters

The following is an example of the SSF_COMPLETE_EPAYMENT_RESP message that the SSF_COMPLETE_EPAYMENT service operation transmits to the online application:

<?xml version="1.0"?>
<SSF_COMPLETE_EPAYMENT_RESP xmlns="http://xmlns.oracle.com/Enterprise/HCM/services">
  <SF_PMT_REF_NBR>000000000043</SF_PMT_REF_NBR>
  <SCC_EPAY_MERCH_REF>00024828</SCC_EPAY_MERCH_REF>
  <CR_CARD_DIGITS>1111</CR_CARD_DIGITS>
  <SF_POST_STATUS>S</SF_POST_STATUS>
  <SF_PAYMENT_STATUS>B</SF_PAYMENT_STATUS>
  <SSF_PMT_SOURCE_STATUS>S</SSF_PMT_SOURCE_STATUS>
  <SSF_PMT_MSG>Your payment was successfully processed.</SSF_PMT_MSG>
  <SSF_APPL_MSG>Your application 00024828 was successfully submitted.</SSF_APPL_MSG>
</SSF_COMPLETE_EPAYMENT_RESP>

Fault Message: SSF_TRANS_FAULT_RESP

Refer to the SSF_TRANS_FAULT_RESP message example in the SSF_INITIATE_EPAYMENT section.