Newstart InApp (Webhooks)

DISCLAIMER

Product Information contained within this document, including technical information and functional specifications, is subject to change without notice. Naviga reserves the right to make any changes to the information in this document at any time without notice. Naviga makes no warranty, representation, or guarantee regarding the suitability of its products and services for any particular purpose.

Introduction

New subscriptions that have been created through InApp marketplaces rather than through the Naviga Subscribe platform are referred to as "Newstart InApp" subscriptions. This page provides an overview of the steps that must be followed in order to successfully migrate a client from the previous External Payments system to the new Webhooks system.

This will allow the client to begin processing the new InApp Newstart that will be created from an external app using PurchaseAPI, as well as the Webhooks notification that will be created from the external markets using Webhooks API.

Before You Start

A minimum Subscribe version of 3.16.3.6 and above is required to use the new InApp endpoints.

Client Implementation Steps

1. Client-side Market Configuration

• In order to make sure that the notifications have been correctly received, it will be necessary to set up the authentication credentials, such as API keys, access tokens, etc., that have been associated with the in-app market.

  Market	Details
  Google	Credentials should be in JavaScript Object Notation (JSON) format.
  Apple V1	Credentials should be in String format of 32 characters.
  Apple V2	Credentials should be in JSON Web Token (JWT) format.

• The URL of the Webhook has to be updated in the specific marketplace console (Google, Apple V1, Apple V2) in order to receive the notification status information in the new Webhooks flow.

  Market	Details
  Google	POST “Webhooks/Google/{MediaGroup}/{ClientCode}/{PaperCode}”
  Apple V1	POST “Webhooks/Apple/V1/{MediaGroup}/{ClientCode}/{PaperCode}”
  Apple V2	POST “Webhooks/Apple/V2/{MediaGroup}/{ClientCode}/{PaperCode}”

---

2. Newstart InApp Subscription Endpoint

For Newstarts InApp subscriptions, the new URL endpoints must be used along with the new bearer authentication.

Newstart InApp Subscription Endpoint

POST {SubscribeApiUrl}/Purchases/InApp

This endpoint is used to create a Newstart InApp subscription.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Headers

Name	Type	Description
Authorization*	String	JSON Web Token used for security purposes
X-SourceSystem*	String	To identify the consumer or the Source System
X-ClientCode*	String	Client Code of the Tenant
X-PaperCode*	String	Paper Code of the Tenant
X-MediaGroupCode*	String	Media Group Code of the Tenant

Request Body

Name	Type	Description
CustomerRegistrationId*	String	Unique identifier of a customer in Naviga System
OfferId*	Integer	Unique identifier of the offer in Naviga System
OfferGroupId*	Integer	Unique identifier of the offer group in Naviga System
OfferCode	String	Unique code of the offer in Naviga System
AppleInfo.Receipt*	String	Receipt information for the Apple InApp market. It is required only if it is an Apple InApp Newstart.
GoogleInfo.Receipt*	String	Receipt information for the Google InApp market. It is required only if it is an Google InApp Newstart.
Subscriber.Email	String	Email of the subscriber
Subscriber.Country	String	Country of the subscriber
Subscriber.CompanyType	String	Company type of the subscriber
Subscriber.CompanyName	String	Company name of the subscriber
Subscriber.Title	String	Title of the subscriber
Subscriber.LastName	String	Last name of the subscriber
Subscriber.FirstName	String	First name of the subscriber
PaymentTypeId*	Integer	Unique identifier of the payment type in Naviga System
StartDate*	dateTime	Start date of the subscription
EmailAddress*	String	Email address of the subscriber
Subscriber.Phone	String	Phone of the subscriber
Product.MerchantProductId	String	Unique identifier of the merchant product
Product.ProductQuantity	Integer	Quantity of the product required
Product.ExternalProductId	String	Unique identifier of the external product
Products	Array
RegistrationId	Integer	Unique identifier of a registration in Naviga System
Product.ProductId	Integer	Unique identifier of the product

200: OK Success Response

{
  "Code": 200,
  "Errors": [],
  "Result": {
    "EventId": 0,
    "AccountNumber": "string",
    "PaymentAuthorizationCode": "string",
    "TwoSteps": false
  },
  "SessionId": "string",
  "RequestId": "string"
}

400: Bad Request Authorization is missing

{
    "error": "Authorization is missing."
}

400: Bad Request X-SourceSystem is missing

{
    "error": "X-SourceSystem is missing."
}

401: Unauthorized Invalid Source System

{
    "error": "Invalid Source System."
}

500: Internal Server Error Something went wrong. Please try again later.

{
    "error": "Something went wrong. Please try again later."
}

400: Bad Request Invalid Input

{
   "Code":400,
   "Errors":[
      {
         "Message":"Invalid Input.",
         "Code":"Subscriptions01",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

400: Bad Request Failed To Add External Subscription

{
  "Code": 400,
  "Errors": [
    {
      "Message": "Failed To Add External Subscription",
      "Code": "Subscriptions422",
      "Type": {
        "Id": 0,
        "Code": "Validation"
      },
      "ErrorSource": null
    }
  ],
  "Result": null,
  "SessionId": null,
  "RequestId": null
}

400: Bad Request Existing External Subscription

{
  "Code": 400,
  "Errors": [
    {
      "Message": "Existing External Subscription",
      "Code": "Subscriptions421",
      "Type": {
        "Id": 0,
        "Code": "Validation"
      },
      "ErrorSource": null
    }
  ],
  "Result": null,
  "SessionId": null,
  "RequestId": null
}

400: Bad Request Invalid Receipt Info

{
  "Code": 400,
  "Errors": [
    {
      "Message": "Invalid Receipt Info",
      "Code": "Subscriptions420",
      "Type": {
        "Id": 0,
        "Code": "Validation"
      },
      "ErrorSource": null
    }
  ],
  "Result": null,
  "SessionId": null,
  "RequestId": null
}

400: Bad Request Failed To Verify Receipt Info

{
  "Code": 400,
  "Errors": [
    {
      "Message": "Failed To Verify Receipt Info",
      "Code": "Subscriptions417",
      "Type": {
        "Id": 0,
        "Code": "Validation"
      },
      "ErrorSource": null
    }
  ],
  "Result": null,
  "SessionId": null,
  "RequestId": null
}

400: Bad Request Invalid Apple Token Secret

{
  "Code": 400,
  "Errors": [
    {
      "Message": "Invalid Apple Token Secret. Token secret cannot be null or empty",
      "Code": "Subscriptions435",
      "Type": {
        "Id": 0,
        "Code": "Validation"
      },
      "ErrorSource": null
    }
  ],
  "Result": null,
  "SessionId": null,
  "RequestId": null
}

400: Bad Request offer does not exist

{
  "Code": 400,
  "Errors": [
    {
      "Message": "The offer does not exist or it is not available.",
      "Code": "Subscriptions29",
      "Type": {
        "Id": 0,
        "Code": "Validation"
      },
      "ErrorSource": null
    }
  ],
  "Result": null,
  "SessionId": null,
  "RequestId": null
}

400: Bad Request start date cannot be null

{
   "Code":400,
   "Errors":[
      {
         "Message":"The start date cannot be null",
         "Code":"Subscriptions451",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

401: Unauthorized Invalid authorization

{
    "error": "Invalid authorization."
}

---

3. Naviga Implementation Steps

For detailed implementation steps of the Newstart InApp migration from the old ExternalPayments system to the new Webhooks system, please refer to the internal Confluence documentation.

3.1 Migration of data from External Payments DB to Subsvc DB

Naviga Implementation team should migrate the data for existing InApp subscriptions from the old External Payments database to the new tables in the Subsvc database.

3.2. MG2 Control DB

3.2.1. Market-based API Settings

Market	Setting name	Details
Google	Google.VerifyReceiptCredential	The client provides the credentials in JSON format. The value differs depending on the newspaper client.
Apple V1	Apple.VerifyUrl	The universal URL endpoint for verification of receipts. The value remains the same for all clients.
Apple V1	Apple.VerifySecret	The client provides the credentials in String format of 32 characters. The value differs depending on the newspaper client.
Apple V2	Apple.AppleTokenSecretWebhooksApi	The client provides the credentials in JWT format. The value differs depending on the newspaper client.

3.2.2. API Settings

Setting	Details
Flow.Purchase.InApp.Redirect	The value should be set for a specific client. The default value has been set to 1 (true). If the value has been set to 0 (false), the Purchase API will process the Newstart subscription. If the value has been set to 1 (true), the request will be redirected to the Subscriptions API to process the Newstart subscription.
InAppNotification.NotificationRetryLimitWebhooksApi	Whenever the system finds that the processed status of an InApp notification does not indicate "OK," it will attempt to process the notification again. This setting determines the maximum number of times that the notification can be reprocessed.

3.3. Event Types Configuration

Set the following information in the [EventTypes] and [NewspaperEventProcessorAssignments] tables based on the specific market to be configured:

• Set the configuration for the event type, GOOGLEVERIFYRECEIPT (1195), to have active = 1 (true) and triggers_post = 1 (true).

  • It should also be associated with NewspaperEventProcessorAssignments, with the 'EventProcessorId' value set to 41 (Google).

• Set the configuration for the event type, APPLEVERIFYRECEIPT (1194), to have active = 1 (true) and triggers_post = 1 (true).

  • It should also be associated with NewspaperEventProcessorAssignments, with the 'EventProcessorId' value set to 43 (Apple).

3.4. Bearer Authentication

A new bearer authentication should be generated for the client. The bearer token should have PurchaseAPI resource added with the 'write' access.

3.5. Set up Hangfire with OnPremise API

Hangfire is integrated into the OnPremise API, which manages background jobs and scheduled tasks.

Prerequisites

1. The below-listed MG2 Control API settings should be in place.

   Setting	Details
   OnPremiseStorageConnectionString	This setting is used to define the "DB Connection string" in order to designate a specific database as a repository for managing queue(s). Example value: Data Source=IP;Initial Catalog=MG2_Control;User Id=xxxxx;Password=xxxxx;
   SubConConnectionString	This is a global setting that specifies the connection string for connecting to the Subsvc DB. Example value: Data Source=IP;Initial Catalog=subsvc_SomeClient_test;Persist Security Info=True;User ID=xxxxx;pwd=xxxxx;
   MG2API	This setting is used as the base URL for calling the Subscribe APIs. Example value: http://aws-test.subscriberconcierge.com/

2. Before configuring Hangfire, the following stored procedures must exist:

   • dbo.OnPremise_InAppRetryNotification_GetData

   • dbo.OnPremise_StopExternalSubscriptions_GetData

Hangfire Setup:

3.5.1. Retry Notification endpoint

Hangfire will generate a task cycle that will run every time as specified in the input model's instructions.

POST: https://aws-test.subscriberconcierge.com/Notifications/InApp/Retry/Configure

Sample Input Model:

{
  "RunEveryDayAtHour": 19, -> Hour Time UTC
  "RunEveryDayAtMinute": 30, ->  Minute Time UTC
  "TaskKey": "testKey1234" -> Unique Key
}

The task will retry failed market notifications by calling the Webhooks API Retry endpoint (POST: https://aws-test.subscriberconcierge.com/Notifications/{id}/Retry) with the same request Headers used in the request.

3.5.2. External Subscription endpoint

Hangfire will generate a task cycle that will run every time as specified in the input model's instructions.

POST: https://aws-test.subscriberconcierge.com/Notifications/InApp/Retry/Configure

Sample Input Model:

{
  "RunEveryDayAtHour": 19, -> Hour Time UTC
  "RunEveryDayAtMinute": 30, ->  Minute Time UTC
  "TaskKey": "testKey1234" -> Unique Key
}

This task searches the Subscribe database for external subscriptions with an active status (L) and a stop date prior to the current date (< today). It then calls the SubscriptionsAPI endpoint (POST: https://aws-test.subscriberconcierge.com/ExternalSubscription/{0}/Stop) with the same request Headers used in the request to stop each external subscription.

External markets such as GooglePlay or Apple may notify of an expiry date in the future; in this case, wait for this Hangfire task to be processed, which will stop the subscription at the appropriate time.

3.5.3. Remove Created Task

To remove a Notification or External Subscription task that has been created, call the Webhooks API endpoint mentioned below.

DELETE: https://aws-test.subscriberconcierge.com/Notifications/InApp/Retry/Remove/{taskKey}

Sample Input Model:

taskKey input parameter is nullable. If taskKey is null then taskKey = MediaGroupCode_ClientCode_PaperCode

3.6. OnPremise API Website Configuration

Hangfire is an open-source framework that helps to create and process background jobs, and the Hangfire server operates within the OnPremise API because this is an ASP.NET Framework web site hosted on IIS.

The Hangfire server is subject to the same events as a website (such as Application_Start, Application_End, etc.), causing it to simply shut down if the website becomes inactive.

For OnPremise API website configuration, please refer to the Confluence documentation.