C H A P T E R 2

Billing Integration

You do not need to change your billing implementation to use the Content Delivery Server. You can configure the Content Delivery Server to work with your current billing system through the use of billing adapters.

A billing adapter for postpaid or asynchronous billing converts the information provided by the Content Delivery Server to the format needed by your billing system. The Content Delivery Server posts billing events to a Java Message Service (JMS) queue. You can receive these billing events using a JMS client. The JMS client uses the billing adapter to format the information for your billing system.

A billing adapter for prepaid or synchronous billing is called by the Content Delivery Server as the purchase is being processed. The adapter can dynamically change the price of content, if desired, validate the purchase in real time, or manage billing through an external system such as premium SMS.

You can create your own postpaid billing adapter using the Event Service API if the adapter provided does not meet your needs. You can create your own prepaid billing adapter using the Billing API. See the Sun Java System Content Delivery Server Customization Guide for information on these APIs.

2.1 Billing Adapter Provided

For postpaid billing, the Content Delivery Server provides the Postpaid Service. This service includes a JMS client that processes the billing events in the event queue and generates a file that contains the information that your billing system can use to charge subscribers. The file format can be XML, comma-separated values (CSV), or name-value pairs. See Section 2.2, Working with the Postpaid Service.

No prepaid billing adapters are provided.

2.2 Working with the Postpaid Service

The Postpaid Service supports billing systems that charge subscribers after content has been purchased. You can use the Postpaid Service instead of a customized billing adapter if your billing system supports postpaid billing and processes records in one of the following formats:

Name-value pairs

To use the Postpaid Service, set the following properties in the PostpaidService.properties file. This file is in the $CDS_HOME/deployment/deployment-name/conf directory.

postpaid.handler.class. Set this property to the fully qualified name of the class that you want to use. Use one of the following values:

com.sun.content.server.postpaid.impl.PostpaidDefaultHandler. Use this class to generate billing records in either XML or name-value format.

com.sun.content.server.postpaid.impl.PostpaidCSVHandler. Use this class to generate billing records in CSV format.

postpaid.record.class. Set this property to com.sun.content.server.postpaid.PostpaidBillingRecord.

postpaid.template.filename. Set this property to the fully qualified name of the file that defines the records that you want generated. Use one of the following values:

deployment/deployment-name/conf/resources/default_record.xsl. Use this file with PostpaidDefaultHandler to generate name-value records.

deployment/deployment-name/conf/resources/xml_record.xsl. Use this file with PostpaidDefaultHandler to generate XML records.

deployment/deployment-name/conf/resources/csv_record.xsl. Use this file with PostpaidCSVHandler to generate CSV records.

The following table shows the information provided for each billing event:

TABLE 2-1 Billing Event Parameters
Parameters	Description
`billing-ticket`	Billing ticket for this transaction.
`campaign_coupon`	Coupon code for a campaign.
`campaign_id`	String that identifies the campaign.
`catalog-res-id`	String that identifies the content edition.
`content_binary_mimetype`	MIME type of the content.
`content_class_id`	String that identifies the content item.
`content_description`	Long description of the content.
`content_drm_type_id`	String that identifies the DRM method used to protect the content.
`content_short_description`	Short description of the content.
`content-id`	String that identifies the content that was purchased. This value is the same as `catalog-res-id`.
`content_name`	Name of the content.
`current-status`	Current status of this transaction.
`date`	Date on which the transaction occurred.
`destination-address`	Address to which content is sent, for example, the MSISDN of the subscriber who requested content.
`developer-content-id`	Unique identifier used by the developer to identify the content.
`developer-id`	String that identifies the developer of the content.
`developer_name`	Name of the developer who submitted the content.
`download-confirm`	Flag that indicates whether a confirmation is required after a successful download.
`download-count`	Number of times the content can be downloaded for the price paid.
`download-current-count`	Number of times the subscriber has downloaded this content, including this time.
`download-expiration`	Flag that indicates whether the download period has expired.
`download-period`	Time period during which the content can be downloaded without additional charge to the subscriber.
`download-price`	Price of the content purchased.
`download-purchase`	Flag that indicates this is a purchase request.
`download-recurring`	Flag that indicates whether the subscriber is charged for each download.
`event-log`	Name of the event log.
`event-msg`	Message issued with the event.
`event-source-type-id`	Number that identifies the source of the event.
`event-type`	Numeric representation of the event that occurred.
`event-type-id`	String that identifies the type of event that occurred.
`external_content_id`	String that identifies the content to the billing system.
`external_group_id`	String that identifies the group to which the content belongs.
`external-request-text`	Text of the request from the subscriber, for example, the MO push request content.
`gift_message`	Message included with the gift.
`gifted_current_downloads`	Number of times the recipient downloaded this gift, including this time.
`gifted_current_subscriptions`	Number of subscription periods used by the recipient, including this period.
`gift_download_date`	Date that the gift was first downloaded by the recipient.
`gift_expiration_date`	Date by which the gift must be claimed by the recipient.
`gift_purchase_date`	Date the gift was purchased by the giver.
`gifted_downloads`	Number of downloads included in the gift.
`gifted_subscriptions`	Number of subscription periods included in the gift.
`is_on_device`	Flag that indicates whether the content is already on the device.
`is-prepay`	Flag that indicates whether the subscriber has prepaid for the content.
`locale`	Subscriber's locale.
`msisdn`	MSISDN for the subscriber device.
`push-msgtext`	Message sent to the subscriber's device or email.
`recipient_locale_code`	Locale of the intended recipient of the content.
`recipient_login_id`	Login ID of the intended recipient of the content.
`recipient_mobile_id`	Mobile ID of the intended recipient of the content.
`recipient_unique_device_id`	Unique device ID of the intended recipient.
`server-id`	String that identifies the Vending Manager.
`session-id`	String that identifies the subscriber's session.
`source-address`	Address of the external entity from which the message was received, for example the MSISDN of the SMSC.
`subscription-expiration`	Date that the subscription period ends.
s`ubscription-frequency`	How often the subscription price is charged.
`subscription-recurring`	Fag that indicates whether the subscriber should be automatically charged for the next period when the current subscription period ends.
`subscription-price`	Price of the subscription period.
`timestamp`	Time at which the transaction occurred.
`unique-device-id`	String that uniquely identifies the device used.
`usage-count`	Number of uses allowed for the price specified for `usage-price`.
`usage-price`	Price charged for the number of uses specified for `usage-count`.
`user-id`	String that identifies the user who initiated the transaction.
`username`	Login name for the subscriber.
`vending-res-id`	String by which the Vending Manager identifies the content.