Handling a user purchase of a third-party product

Overview

When a user purchases a third-party product through your CRM system, the system 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:

• If your deployment uses SSP, the CRM system should send a POST request to:

  BASH

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

• If your deployment does not use SSP, the system should send a POST request to:

  BASH

  https://<host>:<port>/tpes/v1/operator/entitlements

The payload is the same for both requests. The only difference is that in the response, the entitlement ID field is named differently (see below).

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

• validFrom – the entitlement validity start date/time in ISO 8601 format

• expiryDate – the entitlement validity end date/time in ISO 8601 format

Optional arguments

None

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",
  "validFrom": "2025-09-01T13:47:59.228Z",
  "expiryDate": "2025-12-01T13:47:59.228Z"
}

Response

A successful request returns either an HTTP 200 or an HTTP 202 status:

• 200 – the request was successful and the merchant entitlement was created.

• 202 – the request was successful, but the user needs to activate the entitlement.
  In this case, the response includes an activation URL that the CRM system must pass to the user so they can activate the entitlement.
  Once the user has activated the entitlement, OPF will call the CRM system’s notification endpoint to notify it of the entitlement status change. See Implementing endpoints to handle notification and authorisation calls from OPF.

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 v2 or the Third Party Entitlement Service (TPES) API documentation for the specific error codes and their meanings.

Example

If the request was successful (202) and the user is required to activate the entitlement before it becomes active, the response looks like this:

{
  "_id": "ef57e369-3fa6-4720-802d-82eac4f100b5",
  "merchantId": "netflix",
  "merchantCustomerId": "94245dab-0681-4ab6-99e8-0a7929b659c3",
  "status": "Pending",
  "activationUrl": "bango.com/activate/ef57e369-3fa6-4720-802d-82eac4f100b5"
}

The name of the ID field for the newly-created entitlement is different between TPES and CRM Gateway:

• In CRM Gateway (shown above), it is _id.

• In TPES, it is entitlementId.

See also

• CRM Gateway API documentation v2

• Third Party Entitlement Service (TPES) API documentation