Externally-Managed Passes [Beta]

🚧

Beta

Please note that it is a Beta phase.

The lifecycle of externally-managed passes [EMP] is outside of Cleeng’s control. It’s controlled by external parties, such as telcos and direct carriers, external payment gateways, mobile and TV apps.

Synchronize Externally-Managed Passes

Cleeng harmonizes different platforms with API framework for synchronizing externally-managed passes.

An external system may be directly integrated with Cleeng API, but a more common case is when a connector acts as a proxy between an external system and Cleeng API and synchronizes externally-managed purchases.

Once the accounts, and payments are in sync, the endpoints below allow you to keep pass up to date with the events taking place in the external system (e.g. inform about status changes such as new payment, refund, or termination).

Create Externally-Managed Pass

You can create externally-managed passes with Create a pass endpoint (POST /3.1/passes).

While creating it, please bear in mind the following:

  • if expiration date is provided - the date will be set as pass expiration date
  • if expiration date is not provided - expiration date will be calculated based on the offer
  • if expiration date = null- pass will not expire until another request is sent to terminate. This sort of pass is called an evergreen pass.

Get Externally-Managed Pass

You can fetch details of an externally-managed pass with Get a pass endpoint (GET /3.1/passes/{passId}).

List Externally-Managed Passes

You can retrieve externally-managed passes that match the specified criteria with the List passes endpoint (GET /3.1/passes). You can determine if a pass is externally-managed by the field isExternallyManaged in the pass resource.

Update Externally-Managed Pass

You can update externally-managed passes with the Update a pass endpoint (PATCH 3.1/passes/{passId}).

Terminate Externally-Managed Pass

You can terminate externally-managed passes with the Terminate a pass endpoint (POST 3.1/passes/{passId}/terminate).

You do not need to call this endpoint to terminate a pass if you have enabled auto-termination.

Webhooks - Externally-Managed Passes

For information, see Webhooks - Pass Topics.

Auto-termination

An external system is responsible for all status updates of passes, but it can be changed while configuring a payment method (see the Prerequisites section in the in the Integrating Multi-Channel Billing article). You can enable auto-termination during configuration of a payment method.

If auto-termination is not enabled for the payment method, Cleeng platform will not terminate the pass when expiration date is reached, and the broadcaster will need to send the termination request to revoke access.

Evergreen Passes

Broadcasters can create non-expiring (evergreen) passess so that customers can have permanent access to the offer unless/until it is terminated with a separate request.

To create non-expiring passes, set expiry date to null in Create a pass endpoint.

You can convert from evergreen to terminating passes by providing an expiration date.