Handling a user purchase of a third-party product

Overview

When a user purchases a third-party product through your self-care portal, the portal calls OpenTV Platform so that it can create the necessary entitlement and initiate the purchase action through Bango.

The customer must already have an account in OpenTV Platform before making the below request.

Request

To create a third-party product entitlement for an account, the portal should send a POST request to:

https://<host>:<port>/crm-gateway/v2/rmg/v1/entitlements

Headers

• x-correlation-id  – identifier for logging, to correlate messages across a call flow

• Authorization – Keycloak access token (see Accessing operator APIs using Keycloak)

• nv-tenant-id – tenant ID

• Content-Type: application/json

Mandatory arguments

• productType – must be THIRDPARTY

• productId – the OPF product ID (see Creating a third-party product)

• accountId – the ID of OPF account making the purchase

• status – the status of the entitlement. This should be set to PENDING initially.

Optional arguments

• prohibitDuplicateProductPurchase (in query) – whether to allow (true) or prevent (false) duplicate product purchases with overlapping validity dates (default: false).

• reasonCode – a code representing the reason why the entitlement is in its current state. This does not need to be set when creating an entitlement.

• reasonCategory – the reason code category. This does not need to be set when creating an entitlement.

• _id – the unique ID of the entitlement. If you do not provide an ID, one will be generated automatically.

Example

A request with this payload will create a new third-party product entitlement and initiate the purchase action through Bango:

{
  "productId": "product1234",
  "accountId": "account1234",
  "productType": "THIRDPARTY",
  "status": "PENDING"
}

Response

A successful request returns an HTTP 201 status.

A bad request returns an HTTP 400 status.

A forbidden request (invalid token) returns an HTTP 403 status.

If the specified tenant does not exist, the request returns an HTTP 404 status.

See the CRM Gateway API documentation for the specific error codes and their meanings.

Example

{
  "_id":"abc1234"
}

Here, _id is the ID of the newly-created entitlement.

See also

CRM Gateway API documentation