Intelligent Guides

Introduction and Journey

Minna provides an ability to cancel a particular subscription using Cancellation Intelligent Guides API, where a customer receives a structured localised guide with defined required steps for a particular service provider.

To identify which service provider supports cancellation method using intelligent guides, there is Service Providers API (https://docs.minna.tech/docs/service-providers-1, and the “cancel option” for the particular service will be defined as CancellableWithGuide.

When a service and subscription identified, to work with Cancel Intelligent Guides, there are two endpoints available in Cancel API v2:

To receive localised guide and required steps for a specified service, identified earlier used Service Providers API
To submit a user cancellation confirmation and feedback

The simplest possible solution would be the following journey:

However, it is also possible to use multiple cancellation methods simultaneously, for example using Cancellation API for intelligent guides and Block Payments API to place blocks for the same subscription:

API overview

Receiving cancellation intelligent guides

To receive localised guide and required steps for a specified service there is an endpoint:

GET /v2/service-providers/{serviceProviderId}/service/{serviceId}/intelligent-guide[?locale={locale}]

URL parameters
- serviceProviderId - The id of the service provider that provides the service for the subscription
- serviceId - The id of the service that the subscription is for
Query parameters:
- locale (optional) - Used to request a specific locale for the guide, if not present the guide will be returned in the default locale for the market

Request example:

GET /v2/service-providers/cf927968-7f30-4e6c-ae47-775061265552/service/df127968-7f30-4e6c-ae47-775061265441/intelligent-guide?locale=en-GB

Response example:

{
    "guide": {
        "settings": {
            "guideId": "generic",
            "linkToCancel": "http://example.net/provider-1"
        },
        "steps": [
            {
                "id": "loginDetails",
                "description": "Make sure you have your login details at hand."
            },
            {
                "id": "goToCancel",
                "description": "Go to <a href =\"http://example.net/provider-1\">this page</a> and sign in."
            },
            {
                "id": "selectCancel",
                "description": "Select <b>Cancel</b> and follow the instructions"
            },
            {
                "id": "updateSubscription",
                "description": "Come back here to let us know how it went, so we can update your subscriptions"
            }
        ]
    },
    "locale": "en-GB"
}

Posting a user cancellation confirmation and feedback

To submit a user cancellation confirmation and feedback there an endpoint:

POST /v2/users/{userId}/cancellations/intelligent-guide/{cancellationGuideId}/confirmation

URL parameters
- cancellationGuideId - The id of the cancellation guide for which the user is providing feedback
- userId - The id of the user providing the feedback
Body
- serviceId (required) - The id of the service that the subscription is for
- cancelled (required) - The cancellation result if the user subscription was cancelled or not
- rating (optional) - rating from 0 (lowest) to 5 (highest) from a user
- userComment (optional) - some unstructured comment/feedback from a user

Request example:

POST /v2/users/cf927968-7f30-4e6c-ae47-775061265552/cancellations/intelligent-guide/generic/confirmation

{
    "serviceId": "df127968-7f30-4e6c-ae47-775061265441",
    "cancelled": true,
    "rating": 5,
    "userComment": "Everything went perfectly"
}

Response example:

{
    "cancellationId": "acf8d22e-af5e-4674-b4d5-58abe62f3338"
}

Response provides a cancellation created using intelligent guides as correlation id for diagnostic/analytics purposes.