Once a user has decided to purchase a product, the client application must send a purchase request to the OpenTV Platform. Assuming that the purchase is authorised, the subscription then authorises any internal or external requests to enable playback to commence. For example, for an Open Device this could be the authorisation of a DRM license to be delivered to the device.
The SDP handles all purchase requests and maintains the subscription information.
See Subscription data for details on retrieving and using the subscription data.
Data models
Context
The context model is used to provide the SDP with details on the device, user and account making the purchase request. See Account, User and Device data for details on how to retrieve it. It can be altered by the UI application if required, for example, to purchase the content for a different device than the one currently used.
Context data model
Name
Type
Description
Localised
Always available
accessPointUid
Integer
The unique Access Point identifier within the SDP. Can be used to request the full Access Point details from the SDP using the Access Point service. An Access Point provides details on the location the device resides in and how it should connect to the platform.
No
Yes
accountNumber
String
The account number. Usually provided by the service provider.
No
Yes
accountOriginId
Integer
In cases where the account number needs to be defined within the SDP for some reason, this field can be used to identify the system providing the account origin key information, if present.
No
No
accountOriginKey
String
In cases where the account number needs to be defined within the SDP for some reason, this field can be used to define the original account number as provided by the service provider. Rarely used.
No
No
accountUid
Integer
The unique account identifier within the SDP. This identifier is not known externally to the SDP, so it should only be used for SDP API calls. Account number should be used for account identification wherever possible.
No
Yes
casn
String
The Conditional Access Serial Number of the device CA chipset. Only applicable to set top boxes. It can be changed by a firmware change, but this is not common, so it can be used as a device identifier for signon.
No
No
challengeId
String
The solution to a recent challenge obtained from the challengeAggregateService, where required.
This field is used in NAGRA Media PRM deployments that use challenges to provide additional security around purchasing and licensing. It only needs to be set when providing a Contextobject to an API that requires this additional security, such as those on bocPurchaseService. The same challenge ID may be used multiple times until it expires, normally in the order of 30 seconds after issue. Once a challenge ID expires, you must to obtain a new challenge using challengeAggregateService.acquireSecureChallengeand refresh this field with the decrypted challenge ID.
No
No
deviceOriginId
Integer
The identifier of the external system that provisioned the device. Only used if deviceOriginKey is present.
No
No
deviceOriginKey
String
The external identifier of the device. Not typically used, as external systems usually also identify devices by hardware identifiers such as CASN.
No
No
deviceProfileUid
Integer
Unique device profile identifier. Can be used to retrieve device profile information from the Profile service.
No
No
deviceType
String
The device type. Must be one of:
STB – set top box
MP – media player
No
Yes
deviceUid
Integer
Can be used to retrieve the full device information from the Device service.
No
Yes
drmInstanceId
String
The ID of the DRM system the client wishes to use. Typically not needed, as the DRM system is usually determined by the content itself.
No
No
featureNameList
List of strings
A list of the name of each Featurein the DeviceProfile associated with the request. If the client does not supply a value for this field, it is derived from the featureUidList where possible.
No
No
featureUidList
List of longs
A list of the uid of each Featurein the DeviceProfile associated with the request. If the client does not supply a value for this field, it is derived from the deviceProfileUid where possible.
No
No
mediaPlayerId
String
The identifer of the open device. Only applicable to open devices. Usually created by the DRM system during device initialisation.
No
No
smartcardId
String
The smartcardId of the device's smartcard, if there is one.
No
No
userUid
Integer
The user's unique identifier within the SDP.
No
Yes
8 reads
Offer specification
An OfferSpecification model allows the client application to specify any identifiers that it knows about a product to complete the purchase.
Offer specification data model
Name
Type
Description
Localized
Always available
polgrpOriginId
Integer
TheoriginIdof the Entity (that is, the identifier used by SDP for the system that owns the object).
No
*
polgrpOriginKey
String
TheoriginKeyof the Entity (that is, the identifier used for the object by the system that owns it).
No
*
polgrpCasId
String
Id of the policy group provided by CAS.
No
*
polgrpCasInstanceId
String
Id of the CAS instance for the policy group.
No
*
polgrpUid
Long
Unique Id of the policy group.
No
*
offerId
String
Offer id of the policy group.
No
Yes
* One of the following must be available:
polygrpUid
polgrpOriginId and polgrpOriginKey
polgrpCasId and polgrpCasInstanceId
Use cases
The use cases involve the bocPurchaseService and challengeAggregateService. This service provides APIs for purchase transactions, retrieval of payment methods, retrieval of purchase tokens, and challenge acquisition. The various use cases for this service are described below.
Get pay options for account
Fetch the payment options that are available to the specified Account.
All payment options supported by the Account's Service Provider are returned. The return objects include details of any credentials SDP holds for the Account.
If a payment option requires credentials but these are missing, the payment method cannot currently be used. The Account holder must contact the operator or payment provider to set up their credentials before they can use this payment option.
This API returns a list of PaymentProviderDetails, which contains the payment options available.
GET parameters
Name
Type
Description
Mandatory
pContext
Context
Contextdata model.
Y
pAccountUid
Long
Theuidof the Account that is making the purchase.
Y
Purchase impulse or subscription product post-paid for account or smartcard
Subscribe to a Policy Group for postpaid scenario.
Different types of products, such as impulse or subscription, can be purchased using this API. The purchase can be linked either to the account or to the smartcard only by setting values in the parameter PurchaseFor.
Whether to provide access across the whole Account or just to a single smart card. Value must be one ofACCOUNTor SMARTCARD.
Y
Purchase impulse or subscription product at no cost account or smartcard
Subscribe to a Policy Group that is available at no cost. This method bypasses the normal payment processing, but verifies that the specified Policy Group has zero price. If the Policy Group must be paid for, an error is returned.
Different types of products, such as impulse or subscription, can be purchased using this API. The purchase can be linked either to the account or to the smartcard only by setting values in the parameter PurchaseFor.
Whether to provide access across the whole Account or just to a single smart card. One ofACCOUNTor SMARTCARD.
Y
Purchase product post paid for account with challenge
This use case involves retrieving the challenge using the challenge aggregateService and using this challenge to purchase a product.
Get challenge using challengeAggregateService
The challenge received can only be decrypted by the device's encryption hardware. The license server identifies Set Top Boxes and Media Players using their caSN, derived from the information provided during signon.
A client that does not provide device information when it signed on cannot use this API. This also applies to clients that sign on anonymously.
Media Players that initially signed on without providing device information can update their status using signonService.updateTokenWithMediaPlayer, supplying their mediaPlayerId. SDP responds with a new token that should be used in subsequent requests.
This API returns an encrypted or signed challenge, suitably encoded, of type String.
Purchase product with Challenge
Using the challenge received in Purchase impulse or subscription product post paid for account or smartcard, this challenge can be used until its expiry.
Purchase impulse product for account and pay with card or e-wallet
Subscribe to a Policy Group and process payment using the details supplied. The payment can be made through various means such as a card or e-wallet.
A PaymentDetails object specifying how this purchase will be paid for. The required fields of this object depend on the payment type (for example, card or e-wallet) that has been chosen.
