Fovea.Billing

is now IAPTIC, please go to the new and better version of our system.

Webhook

Webhook
Server-to-Server Real-time Notifications.

Requirements

Description

Pulling regularly the Customer Purchases API for all your customers isn’t a great solution. Instead, you can setup a endpoint on your server that Fovea will call whenever a user’s purchases might have changed. This Webhook will be called as when the user validates a receipt or when Apple or Google themselves sends a notification (for subscription events).

Important:

  • Your endpoint should use SSL, using an https:// endpoint. Self-signed certificates are accepted.
  • Make sure to return status 200 for all calls, even for unrecognized webhook types. The webhook might be extended with new message types.

The format of the request sent to your server is described below.

Webhook Request

Fovea will call your webhook URL request using the POST method. The body will be a JSON object containing the webhook type and the associateed data.

Property name Type Description
type string Only one possible value for now:

  • purchases.updated – A user’s purchases collection have been refreshed
applicationUsername string Your application user identifier. See the applicationUsername documentation.
purchases object The Purchases Collection object, see below. Only available it type is purchases.updated.
password string Should match your account’s Secret Key (found in your Dashboard Settings), to ensure that Fovea is calling your endpoint and not someone else.

Purchases Collection

An object whose keys are product identifiers and values are Purchase objects. See below.

Purchase

A purchase object.

Property name Type Description
productId string The unique identifier of the product.
purchaseId string The unique identifier of the purchase.
platform string Platform vendor that generated the purchase (apple, google, …)
sandbox boolean Whether the purchase was made in a sandbox or a production environment.
purchaseDate date-time Time at which the product was granted, in the ISO 8601 date-time format.
expirationDate date-time Time at which the current (or last active) subscription is set to expire, in the ISO 8601 date-time format.
isExpired boolean Whether a subscription has expired. Check the cancelationReason field to know the reason why the subscription has expired.
renewalIntent string Whether the customer intents to let a subscription be renewed when it reaches its current expiry time. Possible values:

  • Renew – The subscription will renew at the end of the current subscription period.
  • Lapse – The customer has turned off automatic renewal for the subscription. Check the cancelationReason field for details.
renewalIntentChangeDate date-time Last time the customer or system changed the renewalIntent status.
cancelationReason string The reason why a transaction was canceled, a subscription is not auto-renewing or expired. Possible values are:

  • Developer – Subscription canceled by the developer.
  • System – Subscription canceled by the system for an unspecified reason.
  • System.Replaced – Subscription upgraded or downgraded to a new subscription.
  • System.ProductUnavailable – Product not
    available for purchase at the time of renewal.
  • System.BillingError – Billing error; for example customer’s payment information is no longer valid.
  • System.Deleted – Subscription is gone; generally when the user account has been deleted.
  • Customer – Subscription canceled by the user for an unspecified reason.
  • Customer.TechnicalIssues – Customer canceled their transaction due to an actual or perceived issue within your app.
  • Customer.PriceIncrease – Customer did not agree to a recent price increase. See also priceConsentStatus.
  • Customer.Cost – Customer canceled for cost-related reasons.
  • Customer.FoundBetterApp – Customer claimed to have found a better app.
  • Customer.NotUsefulEnough – Customer did not feel he is using this service enough.
  • Customer.OtherReason – Subscription canceled for another reason; for example, if the customer made the purchase accidentally.
  • Unknown – Subscription canceled for unknown reasons.

You can use this value to display an alternative subscription product in your app, to win back the customer, such as a lower-level subscription plan to which the user can downgrade from their current plan. Consider presenting an attractive upgrade or downgrade offer.
isBillingRetryPeriod boolean Whether an auto-renewable subscription is in the billing retry period.

  • true – The platform is attempting to renew the subscription.
  • false – The platform has stopped attempting to renew the subscription.

This field indicates whether the platform is attempting to renew an expired subscription automatically. If the customer’s subscription failed to renew because the platform was unable to complete the transaction, this value reflects whether the platform is still trying to renew the subscription. You can use this field to:

  • Inform the user that there may be an issue with their billing information. For example, an expired credit card or insufficient balance could prevent this customer’s account from being billed.
  • Implement a grace period to improve recovery, if the value is true and the isExpired field is set. A grace period is free or limited subscription access while a subscriber is in a billing retry state.
isTrialPeriod boolean Whether a subscription is in the free trial period. Possible values are:

  • true – The subscription is in the free trial period
  • false – The subscription is not in the free trial period
isIntroPeriod boolean Whether an auto-renewable subscription is in the introductory price period.
discountId string Identifier of the subscription offer redeemed by the user. (iOS only)
You provide this value in the Promotional Offer Product Code field when you create the subscription offer in App Store Connect. You can use this value to:

  • Confirm that the sale of the subscription was from a subscription offer.
  • Confirm which subscription offer was redeemed.
  • Keep track of the subscription offers that a user has redeemed to limit discounts you offer, according to your business model.
priceConsentStatus string Price consent status for a subscription price increase. Possible values:

  • Notified – Customer has been notified of the price increase but did not agree to it.
  • Agreed – Customer agreed to the price increase.