Receive Notifications

Partners can receive notifications of the state changes on subscriptions, and purchase orders during their life cycles. Partners need to subscribe to the corresponding Cloud Pubsub topic provisioned by Payments Reseller Subscription backend.

Subscription and Purchase Order notifications can be useful to detect and process events such as:

  • Google cancels a subscription:
  • user deleting their Google account, or
  • a subscription failing to be extended by the partner during the grace period.
  • Google refunds a purchase order, prorated or in full.

Partner could use appropriate processing in their application for such changes.

Currently, we don't provide notifications on other resources such as products and promotions.

Subscription Lifecycle

state transitions

Subscribing to Cloud Pubsub

During the onboarding process, each partner entity will be assigned with unique Cloud Pubsub Topic IDs for subscriptions and/or purchase orders. The partner will provide the service accounts they wish to be allow-listed to subscribe to the topics. We recommend using the default service accounts provided by Compute Engine, or App Engine.

Notification Specification

The notification is encoded in the pubsub message using the following specification:

  • data: subscription resource, or purchase order resource in json format. It is base64-encoded in Pubsub RESTful API. Pubsub SDK may return decoded value directly, see java example.

  • attributes (subscription only): A map containing additional information related to the subscription in the message. Can be accessed via attributes field in the PubsubMessage, see java example. Currently has the following keys that are returned in the Map

Key Description
state Value corresponds to the String value of the enum

State

cancellationReason This entry will be populated only when CancellationReason is present in the message.
Value corresponds to String value of enum

CancellationReason

Partners can use attributes to create topic subscription with a filter in order to receive only messages that matches the filter. For instance, use filter such as attributes.state = "STATE_CANCELLED" AND attributes.cancellationReason = "CANCELLATION_REASON_ACCOUNT_CLOSED" to receive messages for cancelled subscriptions due to account closure. See docs for more information.

Following fields are not used:

  • orderingKey

Subscription notification examples:

  • User activating the service:
{
  "data": "ewogICJuYW1lIjogInBhcnRuZXJzL2RlbW8vc3Vic2NyaXB0aW9ucy82NWEzMGRmOS04NjY1LTQyYTgtOGM3Yi0wM2RjZTkxMzVlOWEiLAogICJwcm9kdWN0IjogInBhcnRuZXJzL2RlbW8vcHJvZHVjdHMvUFRQRC0xMjM0NTY3OCIsCiAgInBhcnRuZXJVc2VyVG9rZW4iOiAiMjE1NDkzNDI1MTY2IiwKICAicmVkaXJlY3RVcmkiOiAiaHR0cHM6Ly93d3cuZXhhbXBsZS5jb20iLAogICJzZXJ2aWNlTG9jYXRpb24iOiB7CiAgICAicmVnaW9uQ29kZSI6ICJVUyIKICB9LAogICJjeWNsZUVuZFRpbWUiOiAiMjAyMS0wMi0wMlQxNTowMToyM1oiLAogICJmcmVlVHJpYWxFbmRUaW1lIjogIjIwMjEtMDEtMDJUMTU6MDE6MjNaIiwKICAiZW5kVXNlckVudGl0bGVkIjogdHJ1ZSwKICAic3RhdGUiOiAiU1RBVEVfQUNUSVZFIiwKICAicHJvdmlzaW9uVGltZSI6ICIyMDIwLTEwLTAyVDE1OjAxOjIwWiIsCiAgImNyZWF0ZVRpbWUiOiAiMjAyMC0xMC0wMlQxNTowMToyM1oiLAogICJ1cGRhdGVUaW1lIjogIjIwMjAtMTAtMDhUMTU6MDE6MjNaIiwKfQ==",
  "attributes": {
    "state": "STATE_ACTIVE"
  },
  "messageId": "967147fc-6b2e-11eb-b3ac-a1d6ba962d73",
  "publishTime": "2021-02-02T15:01:23Z"
}

The data field encodes the following subscription resource:

{
  "name": "partners/demo/subscriptions/65a30df9-8665-42a8-8c7b-03dce9135e9a",
  "product": "partners/demo/products/PTPD-12345678",
  "partnerUserToken": "215493425166",
  "redirectUri": "https://www.example.com",
  "serviceLocation": {
    "regionCode": "US"
  },
  "cycleEndTime": "2021-02-02T15:01:23Z",
  "freeTrialEndTime": "2021-01-02T15:01:23Z",
  "endUserEntitled": true,
  "state": "STATE_ACTIVE",
  "provisionTime": "2020-10-02T15:01:20Z",
  "createTime": "2020-10-02T15:01:23Z",
  "updateTime": "2020-10-08T15:01:23Z",
}
  • Subscription cancellation. It can be initiated by the partner or Google.
{
  "data": "ewogICJuYW1lIjogInBhcnRuZXJzL2RlbW8vc3Vic2NyaXB0aW9ucy82NWEzMGRmOS04NjY1LTQyYTgtOGM3Yi0wM2RjZTkxMzVlOWEiLAogICJwcm9kdWN0IjogInBhcnRuZXJzL2RlbW8vcHJvZHVjdHMvUFRQRC0xMjM0NTY3OCIsCiAgInBhcnRuZXJVc2VyVG9rZW4iOiAiMjE1NDkzNDI1MTY2IiwKICAicmVkaXJlY3RVcmkiOiAiaHR0cHM6Ly93d3cuZXhhbXBsZS5jb20iLAogICJzZXJ2aWNlTG9jYXRpb24iOiB7CiAgICAicmVnaW9uQ29kZSI6ICJVUyIKICB9LAogICJjeWNsZUVuZFRpbWUiOiAiMjAyMS0wMi0wMlQxNTowMToyM1oiLAogICJmcmVlVHJpYWxFbmRUaW1lIjogIjIwMjEtMDEtMDJUMTU6MDE6MjNaIiwKICAiZW5kVXNlckVudGl0bGVkIjogdHJ1ZSwKICAic3RhdGUiOiAiU1RBVEVfQ0FOQ0VMTEVEIiwKICAiY2FuY2VsbGF0aW9uRGV0YWlscyI6IHsKICAgICJyZWFzb24iOiAiQUNDT1VOVF9DTE9TRUQiCiAgfSwKICAicHJvdmlzaW9uVGltZSI6ICIyMDIwLTEwLTAyVDE1OjAxOjIwWiIsCiAgImNyZWF0ZVRpbWUiOiAiMjAyMC0xMC0wMlQxNTowMToyM1oiLAogICJ1cGRhdGVUaW1lIjogIjIwMjAtMTAtMDhUMTU6MDE6MjNaIiwKfQ==",
  "attributes": {
    "state": "STATE_CANCELLED",
    "cancellationReason": "CANCELLATION_REASON_ACCOUNT_CLOSED"
  },
  "messageId": "967147fc-6b2e-11eb-b3ac-a1d6ba962d73",
  "publishTime": "2021-02-02T15:01:23Z"
}

The data field encodes the following subscription resource with cancellation details:

{
  "name": "partners/demo/subscriptions/65a30df9-8665-42a8-8c7b-03dce9135e9a",
  "product": "partners/demo/products/PTPD-12345678",
  "partnerUserToken": "215493425166",
  "redirectUri": "https://www.example.com",
  "serviceLocation": {
    "regionCode": "US"
  },
  "cycleEndTime": "2021-02-02T15:01:23Z",
  "freeTrialEndTime": "2021-01-02T15:01:23Z",
  "endUserEntitled": true,
  "state": "STATE_CANCELLED",
  "cancellationDetails": {
    "reason": "CANCELLATION_REASON_ACCOUNT_CLOSED"
  },
  "provisionTime": "2020-10-02T15:01:20Z",
  "createTime": "2020-10-02T15:01:23Z",
  "updateTime": "2020-10-08T15:01:23Z",
}