Bango uses cookies to give you the best website experience. By using this website you agree to let Bango use cookies. More info
OK
Bango Developer
  1. Bango Resale
  2. For resellers
  3. Reseller API reference
  4. Asynchronous notifications

Asynchronous notifications

Updates sent by the Bango Platform

The Bango Resale API is a RESTful API: you make requests, and the Bango Platform returns responses. However, in some cases the Bango Platform can send you updates without an explicit request from your code. There are three main use cases:

  • Users may be asked to complete a required merchant process before service activation or update. For example, a merchant may require a user to register for a service before activating the entitlement (and users may decline to complete the process).
  • Merchants can cancel or revoke entitlements at any time. For example, a merchant might cancel an entitlement if the user does not renew their subscription or cancels the service with the merchant directly, and it might revoke an entitlement if it detects fraudulent activity on the user's account.

To receive a notification from the Bango Platform whenever a merchant or the Bango Platform changes an entitlement's status for any reason, set the notificationUrl parameter when you create the entitlement (or later, by updating the entitlement).

Bango recommends you always set the notificationUrl. Invalid URLs trigger an HTTP 400 BAD_REQUEST response.

The Bango Platform does not add or remove any query parameters from the URL you supply.

Notification content

POST Entitlement notification {notificationUrl}
Body parameters
responseCode string

Result of the request.

responseMessage string

A short human-readable message describing responseCode. Not for use by code.

parameters string or null

entitlementId string

The unique, persistent ID of the entitlement.

activationCode string or null

The merchant's activation code, if applicable.

customerIdentifier string

Your unique user identifier for the customer accessing the service.

productKey string

The identifier for the merchant service.

entitlementDisplayName string

The user-visible string describing the entitlement.

offerKey string or null

Any offer identifier recorded for the entitlement.

merchantAccountKey string

The identifier for the merchant supplying the service.

status string

The current status of the entitlement, either Active, Suspended, Cancelled, Revoked, Pending, or Failed.

dateCreated string

yyyy-MM-ddTHH:mm:ss.fff timestamp for the entitlement creation time.

dateActivated string

yyyy-MM-ddTHH:mm:ss.fff timestamp for the entitlement's last activation time. 0001-01-01T00:00:00.000 if the entitlement has never been active.

dateExpiry string

yyyy-MM-ddTHH:mm:ss.fff timestamp of the moment the user's entitlement to the service ends. 0001-01-01T00:00:00.000 if no dateExpiry set been set.

dateFailed string

yyyy-MM-ddTHH:mm:ss.fff timestamp of the moment the user's entitlement to the service ends. 0001-01-01T00:00:00.000 if the entitlement has never failed.

dateEnded string

yyyy-MM-ddTHH:mm:ss.fff timestamp for when the entitlement was last canceled or revoked. 0001-01-01T00:00:00.000 if never.

dateSuspended string or null

yyyy-MM-ddTHH:mm:ss.fff timestamp of the last request to suspend the entitlement. null otherwise.

dateResumed string or null

yyyy-MM-ddTHH:mm:ss.fff timestamp of the last request to resume the entitlement. null otherwise.

dateLastUpdated string or null

yyyy-MM-ddTHH:mm:ss.fff timestamp for the last time the entitlement was modified.

notificationReason string or null

The reason for the notification. The value will be an enum controlled by Bango Resale.

  • ACTIVATION_SUCCESS: The entitlement has been successfully activated
  • TERMINATION_SUCCESS: The entitlement has been successfully terminated
  • PRODUCT_UPDATE: The productKey on the entitlement has been successfully updated
  • SUSPENSION_SUCCESS: The entitlement has been successfully suspended
  • RESUMPTION_SUCCESS: The entitlement has been successfully resumed
extensionDataList object

The collection of arbitrary string keys and values you've associated with the entitlement.

customDataList object

The collection of arbitrary string keys and values you've associated with the entitlement.

extensionData object

The collection of arbitrary string keys and values you've associated with the entitlement.

extraInformation object

The value specified on the entitlement. The object won't be in the body if extraInformation isn't sent in the post or patch request.

Security considerations

Always use HTTPS for notification URLs.

The Bango Platform does not include any credentials in the notification POST headers. Bango suggests you use notification URLs that are publicly accessible but not widely known, with safeguards to detect malicious activity. Some suggestions:

  • Derive your own unique ID for each entitlement, and validate it on receipt of a notification
  • Include a nonce value in an entitlement's extensionData or in the notification URL (as a path parameter or query parameter), and validate it on receipt of a notification
Copyright © 2000–2020 Bango.net Limited