16 Oracle Monetization Cloud web services

This document provides an overview of Oracle Monetization Cloud web services.

Topics in this document

About Oracle Monetization Cloud web services

Oracle Monetization Cloud web services expose numerous subscriber and account management operations to external applications through SOAP APIs. The operations are grouped into web services by functional area. For example, the Billing web service contains the billing operations. For operation details, including sample requests and responses, see the following:

Each operation supports XML element data type payloads (see About web service data types).

The operation request input is specified in a WSDL file included with Oracle Monetization Cloud (see About web service WSDL files).

You can use any standards-compliant SOAP UI development tool to generate a stub that the client can use to communicate with the web services.

Oracle Monetization Cloud uses the OAuth 2.0 web authorization protocol to secure its web services. For information about securely accessing the web services with your client applications, see Configuring secure client access to web services.

About web service data types

Oracle Monetization Cloud supports the following data types in web service operation requests and responses:

For detailed information about each operation's required and optional data types, see Oracle Monetization Cloud SOAP API Reference.

Supported simple data types

Simple data type Description
decimal Decimal data type. Oracle Monetization Cloud supports 15 decimal places.
enum Enumerated value. Contains a list of well-known values.
int Signed 32-bit integer.

Contains four bytes of data represented by a number.

Oracle Monetization Cloud considers an integer value that begins with 0 as octal and an integer value that begins with 0x as hexadecimal and converts this value into a decimal.

string ASCII character string terminated with a \0 (NULL). len = max length in bytes, not including \0.

Uses UTF-8 encoding.

timestamp UNIX time stamp with one-second accuracy. Contains integer data.

This value is interpreted as the number of seconds past January 1, 1970.


Supported complex data types

Complex data type Description
array Array element. See array.
buf Buffer with an arbitrary size for any large data, such as text or image. See buf.
errbuf Structure for holding error information. See errbuf.
POID Oracle Monetization Cloud object identifier. See POID.
substruct Embedded substructure. See substruct.

array

The array data type stores a defined structure of information.

For example, the /account storable class contains a NAMEINFO array. Each element in the array has fields for first name, last name, street address, and other address information. The array can contain any number of elements to describe the different types of account addresses.

buf

The buf data type is used for large text files or binary data such as an array of bytes.

xbuf stands for external buffer. The buffer data isn't in memory but is written directly from a file to the internet or from the internet to a file. The most common use for xbufs are for systems with limited or slow virtual memory. xbufs can be used only from an application.

errbuf

The errbuf data type is used by Oracle Monetization Cloud to record errors.

An errbuf data type has the following structure:

typedef struct {
             int32            location;
             int32            errclass;
             int32            err;
             num_t    field;
             int32            rec_id;
             int32            reserved;
             int32            line_no;
             char             *filename;
             int              facility;
             int              msg_id;
             int              err_time_sec;
             int              err_time_usec;
             int              version;
             flist_t      *argsp;
             errbuf_t     *nextp;
             int              reserved2
} errbuf_t;
 

The following table describes the fields in the errbuf data type:

errbuf field Possible values
location Specifies the component that encountered the error. The following are possible values:
  • ERRLOC_APP: The error occurred in an external application. Use this value to specify that the problem originated in your application, not in Oracle Monetization Cloud.

  • ERRLOC_FLIST: The error occurred in an flist manipulation routine local to the external application. Common causes include illegal parameters and low system memory.

  • ERRLOC_POID: The error occurred in a POID manipulation routine local to the external application. Common causes include illegal parameters and low system memory.

  • ERRLOC_PCM: The error occurred in a web service operation local to the external application. Common causes include illegal parameters.

  • ERRLOC_PCP: The error occurred in the internal communications protocol library. This library provides communication support between the modules of Oracle Monetization Cloud. Common causes include network connection failures. This value indicates a system problem that requires immediate attention.

  • ERRLOC_CM: The error occurred in an internal connection management process. Common causes include an unknown operation or input missing the required POID field.

  • ERRLOC_FM: The error occurred in a web service operation. Common causes include input that doesn't conform to the required specification.

  • ERRLOC_DM: The error occurred in an internal data translation process. Common causes include input that doesn't meet the required specifications or a problem communicating with the Oracle Monetization Cloud database.

errclass Describes the class of error. Use the error class to determine the appropriate type of error recovery. The following are possible values:
  • ERRCLASS_APPLICATION: The error was caused by the application passing illegal data or by a system failure in the client application. The error was detected before the requested operation was performed, so no data in the database changed. After the error is fixed, retry the operation.

  • ERRCLASS_SYSTEM_RETRYABLE: The error was probably caused by a transient condition. Retry the operation. Common causes include a temporary shortage of system resources or the failure of a network connection that you can route around. The error was detected before any data was committed to the database; no data changed.

  • ERRCLASS_SYSTEM_DETERMINATE: The error was caused by a system failure during the operation. Retrying the operation is unlikely to succeed, and the system failure should be investigated immediately by Oracle support (submit a service request to Oracle support at https://support.oracle.com). The error was detected before any data was committed to the database, so no data changed. After the error is fixed, retry the operation.

  • ERRCLASS_SYSTEM_INDETERMINATE: The error was caused by a system failure during the commit phase of an operation. A small window exists during the commit in which a network failure can leave the system unsure of whether the commit occurred. The application must determine whether system data has changed. This class of error is extremely rare, but you must deal with it carefully to avoid corrupting the data in the database. If you determine that no changes were made, you can resolve the system failure problem and then retry the operation.

err Describes the exact error that was encountered. If an API call was successful, err is set to ERR_NONE, and all other fields in the error buffer are left undefined. If an API call results in an error, one or more of the fields are defined with error information.
field Identifies the field number of the input parameter that caused the error.
rec_id Specifies the element ID of the array element that caused the error.
reserved Designates an internal system state used by Oracle support for debugging. Contains no useful information for the application developer.
line_no Specifies the line number in the application source file where the error was detected. The logging routines print the file name and line number from the error buffer, which you can use to locate the exact call to the Oracle Monetization Cloud API that caused the error.

This information is useful only to Oracle support.

filename Specifies the name of the application source file where the error was detected. This can be used with the line_no field to locate the source of an error quickly.

This information is useful only to Oracle support.

facility Specifies the code of a facility associated with Oracle Monetization Cloud internationalization (I18N) features.

Used with the msg_id value to create a localized error message.

msg_id Specifies a unique ID number for each message in the facility identified by the facility code.

Used with the facility value to create a localized error message.

err_time_sec Specifies the time when the error occurred in seconds.
err_time_usec Specifies the time when the error occurred in microseconds.
version Specifies the version of the arguments.
flist_t | *argsp Points to an optional arguments flist.
errbuf_t *nextp Points to one or more optional chained errbufs.
reserved2 Reserved for internal use.

POID

The POID data type identifies an object in the Oracle Monetization Cloud database. Each object has a unique POID. You use the POID to locate the object in the database.

The POID contains the following information:

database_number   object_type   object_id   object_revision_level
 

The following table describes each entry in the POID:

Entry Description
database_number An arbitrary 64-bit number assigned by Oracle to a particular Oracle Monetization Cloud database. Every database has a unique database number that's stored in each object in that database.
object_type The storable class to which the object belongs, for example, /event and /service. A null POID has only /.
object_id A unique 64-bit number assigned to each object. After it's assigned, the ID is never changed or reused. The ID is 64 bits to accommodate the large number of objects that can exist in a database.

The maximum value allowed for the ID is 264 in a nonpartitioned table and 244 in a partitioned table.

object_revision_level The object's revision number. This value increments automatically each time the object is updated. You can't change this value directly.

Example:

0.0.0.1 /account 1234 0
  

To perform an action on all objects of a particular type, specify a type-only POID by setting the object ID to -1. For example, to search for all /invoice objects, the operation's input for the search operation request must contain the following field:

<POID>0.0.0.1 /invoice -1 0</POID>
  

substruct

Use the substruct data type to group several data types. You use substructs to define a field that contains several fields of different data types. Substructs can contain any of the supported data types, including arrays, and they can be nested to any level.

Because substructs are single elements, they're fully identified by the field name in the object class. Unlike arrays, they don't require element IDs.

About web service request date and time format

Oracle Monetization Cloud SOAP web service requests support date and time values in ISO 8601 format, or Unix epoch timestamps. Any value not in ISO 8601 format is treated as a Unix epoch timestamp.

The expected ISO 8601 format is:

YYYY-MM-DDThh:mm:ssTZD

where:

  • YYYY is the four-digit year

  • MM is the two-digit month

  • DD is the two-digit day of the month

  • T separates the date from the time

  • hh is the two digit hour
    mm is the two digit minute

  • ss is the two digit second

  • TZD is the time zone designation, using Z for UTC or +hh:mm or -hh:mm for specific time zones

The following table shows how Oracle Monetization Cloud interprets time zones for example values of TZD.

Time Time zone
2020-05-21T10:24:00-07:00 PST
2020-05-21T10:24:00Z UTC
2020-05-21T10:24:00 Local server time

For more information about this format, see the ISO 8601 standard.

About web service WSDL files

Oracle Monetization Cloud includes one WSDL file for each web service. The WSDL file describes the operation's request input for the service.

The following table lists the names and locations of the WSDL files, where hostname is the URL of your Oracle Monetization Cloud instance.

Web Service WSDL Location
Accounts Receivable https://hostname/BrmWebServices/BRMARServices_v2?wsdl
Activity https://hostname/BrmWebServices/BRMActServices_v2?wsdl
Balance https://hostname/BrmWebServices/BRMBalServices_v2?wsdl
Billing https://hostname/BrmWebServices/BRMBillServices_v2?wsdl
Contracts https://hostname/BrmWebServices/BRMContractServices_v2?wsd
Customer https://hostname/BrmWebServices/BRMCustServices_v2?wsdl
Customer Care https://hostname/BrmWebServices/BRMCustcareServices_v2?wsdl
Data Export https://hostname/BrmWebServices/BRMDataExportServices_v2?wsdll
Invoicing https://hostname/BrmWebServices/BRMInvServices_v2?wsdl
Payment https://hostname/BrmWebServices/BRMPymtServices_v2?wsdl
Pricing https://hostname/BrmWebServices/BRMPricingServices_v2?wsdl
Read https://hostname/BrmWebServices/BRMReadServices_v2?wsdl
Subscription https://hostname/BrmWebServices/BRMSubscriptionServices_v2?wsdl

Oracle Monetization Cloud uses OAuth 2.0 to secure web services WSDL and related XSD files. To access the WSDL and the associated XSD files, pass the OAuth Access Token in the http header when getting the WSDL and XSD files.

For example:

curl -i -H 'Content-Type: text/xml;charset=UTF-8' http://hostname/BrmWebServices/BRMReadServices_v2?wsdl -H 'Authorization : Bearer access_token' 

where hostname is the URL of your Oracle Monetization Cloud instance and access_token is the OAuth access token.

Oracle Monetization Cloud validates the access token with Oracle Access Manager and grants access to the requested WSDL and XSD. You can then download the WSDL and associated XSD files to a local system.

To import the WSDL into a client tool such as SoapUI, remove references to the Oracle Monetization Cloud server URL. For example, change:

http://hostname/BrmWebServices/BRMReadServices_v2?xsd=1 

To:

BRMReadServices_v2?xsd=1 

Testing and implementing web services

This section provides an overview of how to test and implement Oracle Monetization Cloud web services. You can use available tools such as SoapUI or an integrated development environment (IDE) that supports SOAP.

To test and implement web services, perform the following tasks:

Obtaining web service URLs

The URLs for accessing Oracle Monetization Cloud web services are listed in About web service WSDL files.

For the hostname in these URLs, contact your Oracle representative.

Configuring secure client access to web services

Oracle Monetization Cloud uses the OAuth 2.0 protocol to authorize external applications to access its web services. To call a web service, an application must be registered as an OAuth client in Oracle Monetization Cloud. For more information, see Using OAuth to authorize access.

Setting up a SOAP test environment for web services

You can use a SOAP test environment to do the following:

  • Test your applications that interact with Oracle Monetization Cloud.

  • Test web service requests sent to Oracle Monetization Cloud.

SOAP test environments may have minor differences in project configuration. See your SOAP development environment documentation for configuration information.

In general, to set up a SOAP test environment:

  1. Configure a new project in your SOAP test environment.

  2. Import the web service WSDL files.

    To access the WSDL files from Oracle Monetization Cloud, see About web service WSDL files.

  3. In the properties of the web service operations you want to use, specify valid credentials for the SOAP test environment.

  4. Use the SOAP test environment or a text editor to update the sample operation requests to include data applicable to your environment.

    For a list of web services that includes links to sample requests and responses, see About Oracle Monetization Cloud web services.

    For detailed reference information on the request and response parameters in each operation, see Oracle Monetization Cloud SOAP API Reference.

  5. Send your web service request to Oracle Monetization Cloud by using the SOAP test environment client.

  6. View the web service response in the SOAP test environment.

About masked data in web service responses

SOAP response XML files may contain masked fields in your Oracle Monetization Cloud implementation. Subscriber fields, including payment information and user credentials, may be hidden in responses to secure sensitive subscriber data.

For more information on masked data, contact your Oracle representative.

Example of using a web service to create an account

This section provides an example of how to use web services to create a subscriber account.

For information, see the following:

  • For links to topics with sample requests and responses for all web service operations, see Web services.

  • For information about parameters for each web service operation, see Oracle Monetization Cloud SOAP API Reference.

To create an account in Oracle Monetization Cloud, use a SOAP client to call the pcmOpCustCommitCustomer operation, which is included in the BRMCustServices_v2 web service and contains operations related to subscriber accounts.

Sample SOAP request input XML file

The following sample is a sample pcmOpCustCommitCustomer SOAP request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes">
   <soapenv:Header/>
   <soapenv:Body>
      <bus:pcmOpCustCommitCustomerRequest>
         <bus:PCM_OP_CUST_COMMIT_CUSTOMER_Request>
            <bus:flags>1</bus:flags>
            <bus:PCM_OP_CUST_COMMIT_CUSTOMER_inputFlist>
               <bus:ACCTINFO elem="0">
                  <bus:ACCOUNT_NO>a022020202011992</bus:ACCOUNT_NO>
                  <bus:BAL_INFO />
                  <bus:BUSINESS_TYPE>1</bus:BUSINESS_TYPE>
                  <bus:CURRENCY>840</bus:CURRENCY>
                  <bus:POID>0.0.0.1 /account -1 0</bus:POID>
               </bus:ACCTINFO>
               <bus:BAL_INFO elem="0">
                  <bus:BILLINFO />
                  <bus:LIMIT elem="840">
                     <bus:CREDIT_LIMIT>"0"</bus:CREDIT_LIMIT>
                  </bus:LIMIT>
                  <bus:NAME>Account Level Balance Group</bus:NAME>
                  <bus:POID>0.0.0.1 /balance_group -1 0</bus:POID>
               </bus:BAL_INFO>
               <bus:BILLINFO elem="0">
                  <bus:BAL_INFO />
                  <bus:BILL_WHEN>1</bus:BILL_WHEN>
                  <bus:BILLINFO_ID>88-CYZZ5</bus:BILLINFO_ID>
                  <bus:CURRENCY>840</bus:CURRENCY>
                  <bus:PAY_TYPE>10001</bus:PAY_TYPE>
                  <bus:PAYINFO />
                  <bus:POID>0.0.0.1 /billinfo -1 0</bus:POID>
               </bus:BILLINFO>
               <bus:END_T>2010-02-17T22:37:49</bus:END_T>
               <bus:FLAGS>0</bus:FLAGS>
               <bus:LOCALES elem="1">
                  <bus:LOCALE>en_US</bus:LOCALE>
               </bus:LOCALES>
               <bus:NAMEINFO elem="1">
                  <bus:ADDRESS>123 Hollywood Boulevard</bus:ADDRESS>
                  <bus:CITY>Los Angeles</bus:CITY>
                  <bus:CONTACT_TYPE>Account holder</bus:CONTACT_TYPE>
                  <bus:COUNTRY>USA</bus:COUNTRY>
                  <bus:EMAIL_ADDR>test_001</bus:EMAIL_ADDR>
                  <bus:FIRST_NAME>John</bus:FIRST_NAME>
                  <bus:LAST_NAME>Smith</bus:LAST_NAME>
                  <bus:STATE>NJ</bus:STATE>
                  <bus:ZIP>90001</bus:ZIP>
               </bus:NAMEINFO>
               <bus:PAYINFO elem="0">
                  <bus:INHERITED_INFO>
                     <bus:INV_INFO elem="0">
                        <bus:ADDRESS>123 Hollywood Boulevard</bus:ADDRESS>
                        <bus:CITY>Los Angeles</bus:CITY>
                        <bus:COUNTRY>USA</bus:COUNTRY>
                        <bus:DELIVERY_DESCR>test_001</bus:DELIVERY_DESCR>
                        <bus:DELIVERY_PREFER>0</bus:DELIVERY_PREFER>
                        <bus:EMAIL_ADDR />
                        <bus:INV_TERMS>0</bus:INV_TERMS>
                        <bus:NAME>John Smith</bus:NAME>
                        <bus:STATE>NJ</bus:STATE>
                        <bus:ZIP>90001</bus:ZIP>
                     </bus:INV_INFO>
                  </bus:INHERITED_INFO>
                  <bus:INV_TYPE>0</bus:INV_TYPE>
                  <bus:PAY_TYPE>10001</bus:PAY_TYPE>
                  <bus:POID>0.0.0.1 /payinfo/invoice -1 0</bus:POID>
               </bus:PAYINFO>
               <bus:POID>0.0.0.1 /plan -1 0</bus:POID>
            </bus:PCM_OP_CUST_COMMIT_CUSTOMER_inputFlist>
         </bus:PCM_OP_CUST_COMMIT_CUSTOMER_Request>
      </bus:pcmOpCustCommitCustomerRequest>
   </soapenv:Body>
</soapenv:Envelope>

Sample SOAP response output XML file

The following sample is a SOAP response for pcmOpCustCommitCustomer:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <pcmOpCustCommitCustomerResponse xmlns:brm="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes">
         <ACCOUNT_OBJ>0.0.0.1 /account 225757 0</ACCOUNT_OBJ>
         <ACCTINFO elem="0">
            <ACCOUNT_NO>a022020202011992</ACCOUNT_NO>
            <BAL_INFO elem="0" />
            <BUSINESS_TYPE>1</BUSINESS_TYPE>
            <CURRENCY>840</CURRENCY>
            <POID>0.0.0.1 /account -1 0</POID>
         </ACCTINFO>
         <BAL_INFO elem="0">
            <ACCOUNT_OBJ>0.0.0.1 /account 225757 0</ACCOUNT_OBJ>
            <BILLINFO_OBJ>0.0.0.1 /billinfo 226269 0</BILLINFO_OBJ>
            <LIMIT elem="840">
               <CREDIT_LIMIT />
            </LIMIT>
            <NAME>Account Level Balance Group</NAME>
            <POID>0.0.0.1 /balance_group 225341 0</POID>
            <SERVICE_OBJ>0.0.0.0 0 0</SERVICE_OBJ>
         </BAL_INFO>
         <BILLINFO elem="0">
            <BAL_GRP_OBJ>0.0.0.1 /balance_group 225341 0</BAL_GRP_OBJ>
            <BILLINFO_ID>88-CYZZ5</BILLINFO_ID>
            <BILL_WHEN>1</BILL_WHEN>
            <CURRENCY>840</CURRENCY>
            <CURRENCY_SECONDARY>0</CURRENCY_SECONDARY>
            <EFFECTIVE_T>2010-02-17T22:37:49Z</EFFECTIVE_T>
            <PAYINFO_OBJ>0.0.0.1 /payinfo/invoice 226781 0</PAYINFO_OBJ>
            <PAY_TYPE>10001</PAY_TYPE>
            <POID>0.0.0.1 /billinfo 226269 0</POID>
         </BILLINFO>
         <END_T>2010-02-17T22:37:49Z</END_T>
         <FLAGS>0</FLAGS>
         <GROUP_INFO />
         <HOST elem="1">
            <HOSTNAME>XXX.XXX.XXX.XXX</HOSTNAME>
            <TYPE>1</TYPE>
         </HOST>
         <HOST elem="2">
            <HOSTNAME>XXX.XXX.XXX.XXX</HOSTNAME>
            <TYPE>1</TYPE>
         </HOST>
         <HOST elem="3">
            <HOSTNAME>XXXXXXXXX.XXX</HOSTNAME>
            <PORT>0</PORT>
            <TYPE>2</TYPE>
         </HOST>
         <HOST elem="4">
            <HOSTNAME>XXXX.XXX</HOSTNAME>
            <TYPE>3</TYPE>
         </HOST>
         <HOST elem="5">
            <HOSTNAME>XXXX.XXX</HOSTNAME>
            <TYPE>4</TYPE>
         </HOST>
         <HTTP_URL>XXXXXXXXXXXXXXX</HTTP_URL>
         <LOCALES elem="1">
            <LOCALE>en_US</LOCALE>
         </LOCALES>
         <NAMEINFO elem="1">
            <ADDRESS>123 Hollywood Boulevard</ADDRESS>
            <CANON_COUNTRY>US</CANON_COUNTRY>
            <CITY>Los Angeles</CITY>
            <COMPANY />
            <CONTACT_TYPE>Account holder</CONTACT_TYPE>
            <COUNTRY>USA</COUNTRY>
            <ELEMENT_ID>1</ELEMENT_ID>
            <EMAIL_ADDR>test_001</EMAIL_ADDR>
            <FIRST_NAME>John</FIRST_NAME>
            <LAST_NAME>Smith</LAST_NAME>
            <MIDDLE_NAME />
            <SALUTATION />
            <STATE>NJ</STATE>
            <TITLE />
            <ZIP>90001</ZIP>
         </NAMEINFO>
         <PAYINFO elem="0">
            <INHERITED_INFO>
               <INV_INFO elem="0">
                  <ADDRESS>123 Hollywood Boulevard</ADDRESS>
                  <CITY>Los Angeles</CITY>
                  <COUNTRY>USA</COUNTRY>
                  <DELIVERY_DESCR>test_001</DELIVERY_DESCR>
                  <DELIVERY_PREFER>0</DELIVERY_PREFER>
                  <EMAIL_ADDR />
                  <INV_TERMS>0</INV_TERMS>
                  <NAME>John Smith</NAME>
                  <STATE>NJ</STATE>
                  <ZIP>90001</ZIP>
               </INV_INFO>
            </INHERITED_INFO>
            <INV_TYPE>0</INV_TYPE>
            <PAY_TYPE>10001</PAY_TYPE>
            <POID>0.0.0.1 /payinfo/invoice 226781 0</POID>
         </PAYINFO>
         <POID>0.0.0.1 /plan -1 0</POID>
         <START_T>2010-05-07T06:00:09Z</START_T>
         <SUPPORT_PHONE>XXXXXXXXXXXXXXX</SUPPORT_PHONE>
      </pcmOpCustCommitCustomerResponse>
   </S:Body>
</S:Envelope>