Inbound Web Services
This section lists the web services provided to allow a third-party payment processing system to invoke functions within Oracle Utilities Customer Cloud Service that relate to account verification, one-time payment processing, and recurring automatic payments.
Third-Party Account Verification (C1-ThirdPartyVerifyAccount)
This web service is used to verify an account either before capturing a one-time payment or before processing an auto pay setup/enrollment. It checks that an input Account ID exists in Oracle Utilities Customer Cloud Service, and if so, returns the account’s balance, past due amount (if any), bill due and any existing account auto pay options. The existing account auto pay option information is useful when verifying the account prior to auto pay setup/enrollment. The third-party payment processors can use this to determine how to handle the auto pay enrollment request.
Example: If the account is already enrolled in auto pay, the third-party payment processor will know if the new enrollment overlaps or duplicates the existing enrollment and if the existing enrollment is just being updated.
The web service creates a service task that performs this processing. Refer to the C1-ThirdPartyAcctVerifTask business object in the application for more details about this service task.
The schema for this web service is as follows:
Field
Element Name
Required/Optional
Comments
Header Information (group)
head
 
 
Action
action
Required
Value: C1VE (Verify)
Account ID
accountId
Required
 
Account Verification (group)
accountVerification
 
 
Input (group)
input
 
 
Auto Pay Reference Start Date
autoPayReferenceStartDate
Optional
Used to check if the account has existing auto pay enrollments/options. If not supplied, service will look for auto pay enrollments) as of the current date.
Auto Pay Reference End Date
autoPayReferenceEndDate
Optional
Used to check if the account has existing auto pay enrollments/options.
Custom Inputs (group)
customInput
Optional
Not used in CCB base logic. For implementation use only.
Field 1
field1
 
 
Name
name
 
 
Value
value
 
 
Field 2
field2
 
 
Name
name
 
 
Value
value
 
 
Field 3
field3
 
 
Name
name
 
 
Value
value
 
 
Field 4
field4
 
 
Name
name
 
 
Value
value
 
 
Field 5
field5
 
 
Name
name
 
 
Value
value
 
 
Output
output
 
 
Is Verified
isVerified
 
Boolean
Account Balance
accountBalance
 
 
Past Due Amount
pastDueAmount
 
 
Due Date
dueDate
 
 
Auto Pay Exists
autoPayExists
 
Boolean
Existing Account Auto Pay
 
 
 
InformationList (group)
existingAccountAutoPayInformation
 
 
Auto Pay Start Date
autoPayStartDate
 
 
Auto Pay End Date
autoPayEndDate
 
 
Auto Pay Source
autoPaySource
 
 
Custom Outputs (group)
customOutput
 
Not used in CCB base logic. For implementation use only.
Field 1
field1
 
 
Name
name
 
 
Value
value
 
 
Field 2
field2
 
 
Name
name
 
 
Value
value
 
 
Field 3
field3
 
 
Name
name
 
 
Value
value
 
 
Field 4
field4
 
 
Name
name
 
 
Value
value
 
 
Field 5
field5
 
 
Name
name
 
 
Value
value
 
 
Error Information (group)
errorInformation
 
 
Is In Error
isInError
 
Boolean
Error Reference (group)
errorReference
 
 
Message Category
category
 
 
Message Number
number
 
 
Error Message Text
errorMessage
 
 
Third-Party One-Time Payment Notification (C1-ThirdPartyOneTimePayNotification)
This web service is used to notify Oracle Utilities Customer Cloud Service about one-time payments that are processed at a third-party payment processing system.
The actions supported are as follows:
• Adding an immediate or scheduled one-time payment
• Updating the details of a scheduled payment
• Processing a scheduled payment
• Canceling a scheduled or processed payment
The web service creates a service task that performs this processing. Refer to the C1-ThirdPartyOneTimePayTask business object in the application for more details.
The schema for this web service is as follows:
Field
Element Name
Required / Optional
Comments
Header Information (group)
head
 
 
Action
action
Required
Values:
• C1AD (Add)
• C1CA (Cancel)
• C1PR (Process)
• C1UP (Update)
• C1RE (Read)
Account ID
accountId
Required
 
Payment Information (group)
paymentInfo
 
 
Input (group)
input
 
 
Payment DateTime
paymentDateTime
Required
As a standard, inbound and outbound communication with an external system use the standard xsd datetime format - yyyy-MM-dd'T'hh:mm:ss[+|-]hh:mm
 
Example: 2017-02-28T09:15:00-08:00
Payment Amount
paymentAmount
Required
 
Currency
currency
Optional
If not supplied, CCB will use the currency that is designated on the account.
 
Note: This is for payment processing systems that support multi-currency.
Payment Type
paymentType
Required
The base product provides the following values:
• CREDITCARD
• CHECKING
• SAVINGS
This is a customizable lookup field. Implementations can add their specific values.
Bank Account Information
bankAccountInfo
 
Required IF Payment Type is CHECKING or SAVINGS.
Account Number
accountNumber
 
This should contain only the partial number. For example: The last four digits of the account number
Routing Number
routingNumber
 
This routing number should be one that is configured on one of the Auto Pay Sources in CCB.
(Reason: Auto Pay Source is a required field on the Account Auto Pay which is used to store the enrollment details)
Account Name
accountName
 
 
Credit Card Information
creditCardInfo
 
This group is required if Payment Type is CREDITCARD.
Card Type
cardType
 
The base product provides the following values:
• C1AM (American Express)
• C1DV (Discover)
• C1MC (MasterCard)
• C1VS (Visa)
This is a customizable lookup field. Implementations can add their specific values.
Card Number
cardNumber
 
This should contain only the partial number. For example: The last four digits of the card number
Account Name
accountName
 
 
Expiry Month
expMonth
 
Format: MM
Expiry Year
expYear
 
Format: YYYY
Billing Zip Code
zipCode
 
 
Email Address
email
Optional
 
Phone Number
phone
Optional
 
External Reference Number
extReferenceNumber
Optional
From the third party processor. Can be used to send the payment confirmation number that was sent to the customer. CCB can store this for informational purposes.
External Parent Reference Number
extParentRefNumber
Optional
From the third party processor. Can be used to send the confirmation number of the original payment that is being canceled. CCB can store this for informational purposes.
External Status
extStatus
Optional
This is the status from the third party processor. CCB can store this for informational purposes.
Custom Inputs (group)
customInput
Optional
Not used in CCB base logic. For implementation use only.
Field 1
field1
 
 
Name
name
 
 
Value
value
 
 
Field 2
field2
 
 
Name
name
 
 
Value
value
 
 
Field 3
field3
 
 
Name
name
 
 
Value
value
 
 
Field 4
field4
 
 
Name
name
 
 
Value
value
 
 
Field 5
field5
 
 
Name
name
 
 
Value
value
 
 
Input / Output (group)
input
 
 
Service Task ID
serviceTaskId
 
Output on add (C1AD) action. This is a required input on cancel (C1CA) of a processed payment. This is a required input on cancel (C1CA), update (C1UP) or process (C1PR) of a scheduled (future-dated) payment.
Payment Event ID
paymentEventId
 
Output on add (C1AD) and process (C1PR) actions. This is a required input on cancel (C1CA) of a processed payment.
Payment Cancel Reason
cancelReason
 
Required input on cancel (C1CA) of a processed payment. This must be a valid Pay Cancel Reason defined in the Third Party Payment Processing Integration master configuration.
Output (group)
output
 
 
Cancellation Service Task ID
cancellationServiceTaskId
 
Output on cancel (C1CA) action
Payment Cancel Reasons List
payCancelReasonsList
 
Output on read (C1RE) action
Cancel Reason
cancelReason
 
 
Cancel Reason Description
description
 
 
Informational Message
infoMessage
 
Output on cancel (C1CA) action when the input Cancel Reason is invalid or not supplied. The message will indicate that the system default cancel reason was used.
Custom Outputs (group)
customOutput
Optional
Not used in CCB base logic. For implementation use only.
Field 1
field1
 
 
Name
name
 
 
Value
value
 
 
Field 2
field2
 
 
Name
name
 
 
Value
value
 
 
Field 3
field3
 
 
Name
name
 
 
Value
value
 
 
Field 4
field4
 
 
Name
name
 
 
Value
value
 
 
Field 5
field5
 
 
Name
name
 
 
Value
value
 
 
Error Information (group)
errorInformation
 
 
Is In Error
isInError
 
Boolean
Error Reference (group)
errorReference
 
 
Message Category
category
 
 
Message Number
number
 
 
Error Message Text
errorMessage
 
 
Third-Party Automatic Payment Setup (C1-ThirdPartyAutoPaySetup)
This web service is used to set up an account for recurring automatic payments, such as automatic bill pay. Oracle Utilities Customer Cloud Service creates an Account Auto Pay record using the supplied information.
The web service creates a service task that performs this processing. Refer to the C1-ThirdPartyAutoPayTask business object in the application for more details.
Field
Element Name
Required / Optional
Comments
Header Information (group)
head
 
 
Action
action
Required
Values:
• C1AD (Add)
• C1CN (Cancel)
• C1UP (Update)
Account ID
accountId
Required
 
Auto Pay Information (group)
autoPayInformation
 
 
Input (group)
input
 
 
Start Date
startDate
 
Required if Action is add (C1AD) or update (C1UP)
End Date
endDate
 
Required if Action is C1CN
Payment Type
paymentType
Required
The base product provides the following values:
• CREDITCARD
• CHECKING
• SAVINGS
This is a customizable lookup field. Implementations can add their specific values.
Credit Card Type
cardType
 
Required if Payment Type is CREDITCARD. The base product provides the following values:
• C1AM (American Express)
• C1DV (Discover)
• C1MC (MasterCard)
• C1VS (Visa)
This is a customizable lookup field. Implementations can add their specific values.
Account Number
externalAccountId
Required
Applicable to all Payment Types. This should be a partial number. For example: The last four digits of the account/card number.
Expiry Month
expMonth
 
Required if Payment Type is CREDITCARD
Expiry Year
expYear
 
Required if Payment Type is CREDITCARD
Name on Account
name
Required
 
Routing Number
bankRoutingNumber
 
Routing number should be one that is configured on one of the Auto Pay Sources in CCB.
(Reason: Auto Pay Source is a required field on the Account Auto Pay which is used to store the enrollment details)
Maximum Amount
maxWithdrawAmount
Optional
 
External Reference Number
externalReferenceNumber
Optional
From the third party processor. Can be used to send the confirmation number that was sent to the customer. CCB can store this for informational purposes.
Custom Inputs (group)
customInput
Optional
Not used in CCB base logic. For implementation use only.
Field 1
field1
 
 
Name
name
 
 
Value
value
 
 
Field 2
field2
 
 
Name
name
 
 
Value
value
 
 
Field 3
field3
 
 
Name
name
 
 
Value
value
 
 
Field 4
field4
 
 
Name
name
 
 
Value
value
 
 
Field 5
field5
 
 
Name
name
 
 
Value
value
 
 
Input / Output (group)
inputOutput
 
 
Account Auto Pay ID
autoPayId
 
This is output on add (C1AD) action. It is a required input on an update (C1UP) or a cancel (C1CN) action.
Output (group)
output
 
 
Custom Outputs (group)
customOutput
Optional
Not used in CCB base logic. For implementation use only.
Field 1
field1
 
 
Name
name
 
 
Value
value
 
 
Field 2
field2
 
 
Name
name
 
 
Value
value
 
 
Field 3
field3
 
 
Name
name
 
 
Value
value
 
 
Field 4
field4
 
 
Name
name
 
 
Value
value
 
 
Field 5
field5
 
 
Name
name
 
 
Value
value
 
 
Error Information (group)
errorInformation
 
 
Is In Error
isInError
 
Boolean
Error Reference (group)
errorReference
 
 
Message Category
category
 
 
Message Number
number
 
 
Error Message Text
errorMessage