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

Example

{
  "_id": "ef57e369-3fa6-4720-802d-82eac4f100b5",
  "merchantId": "netflix",
  "merchantCustomerId": "94245dab-0681-4ab6-99e8-0a7929b659c3",
  "status": "Active"
}

Here (using CRM Gateway), _id is the ID of the newly-created entitlement.

In the TPES response, the field is called entitlementId.

See also

• CRM Gateway API documentation v1

• Third Party Entitlement Service (TPES) API documentation