1 of 30

Naviga Subscribe API

Subscribe API

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.

If you are upgrading to Subscribe Version 3.17.0 and calling the subscribe APIs externally, this migration is mandatory.

Introduction

Welcome to the Subscribe API documentation! This guide is intended to assist developers, system administrators, and API integration stakeholders to understand, mitigate, and effectively adapt to the breaking changes in application programming interfaces (APIs). Breaking changes are modifications that can interrupt the normal functioning of dependent systems, causing compatibility issues.

This guide explains how to migrate from the older to the newer APIs that have been listed below.

Migration from old Billing API endpoints to the new Payment API
Migration from old UserAPI endpoints to the new UsersOrchestrator API
Migration from Entitlements endpoints to the new EntitlementsOrchestrator API

Payments API

Migration to Payments API

This section outlines the process to be followed in order to migrate from the old Billing API endpoints to the new Payment API endpoints within the Payment, EZPay, Update EZPay Info, and Restart flows. Additionally, the "Create Payment Method" and "Get Payment Method By ID" endpoints of the Billing API have been refactored. This section also shows a comparison of the old and new APIs.

The endpoints covered in this section are as listed below:

Apply Payment
EZPay Sign Up
Update EZPay Info
Restart
Create Payment Method
Get Payment Method by Id
Add Tip

Apply Payment

Introduction

This endpoint is used to perform a one-time payment in Circulation Systems (NCS Circ, CircPro, and Matrix).

Comparison

Compared to the older model, the new input model requires just a few parameters, as explained in detail below.

Billing API (OLD)

Payments API (NEW)

URL

/Billing/Payments/{subscriptionId}/ApplyPayment

/Payment

Method

POST

Input Example

{
   "ExternalPaymentMethodId":"10200849",
   "CustomerId":null,
   "GiveTip":false,
   "TipAmount":0.0,
   "TotalAmount":9.99,
   "PaymentSelectedAmount":9.99,
   "CurrencyCode":null,
   "PaymentMethodType":0,
   "NewPaymentMethod":null,
   "TypeOfPayment":null,
   "ParentEventId":0,
   "GiveDonation":false,
   "DonationAmount":0.0,
   "Last4Digits":null,
   "AuthToken":"10200849",
   "AuthTokenPaymentMethodType":2,
   "SignUpToEzPay":false,
   "IsTipAutoRenew":null,
   "IsDonationAutoRenew":null,
   "ApplyToCredit":false,
   "ValidateMaxAmount":false,
   "InvoiceId":null,
   "CreateMapOnTheFly":false,
   "Notes":null,
   "Token":null,
   "RenewalTerm":"Month",
   "RenewalLength":"1",
   "RateCode":null,
   "RestartDate":null,
   "IgnoreFee":true,
   "TransactionId":null,
   "AccountInfo":{
      "SubscriptionId":102830,
      "SubscriberId":102311,
      "RegistrationId":0
   }
}

{
  "IgnoreFee": true,
  "DonationAmount": 0,
  "PaymentMethodId": 0,
  "SubscriptionId": 0,
  "TipAmount": 0,
  "TotalAmount": 0,
  "PaymentOptionAmount": 0,
  "TransactionId": "string",
  "ProcessingFeeAmount": 0,
  "ProcessingFeeTaxAmount": 0
}

Apply Payment

POST /Payment

This endpoint is used to perform a one-time payment in Circulation Systems.

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-MediaGroupCode*

String

Media Group Code of the Tenant

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

Request Body

Name

Type

Description

SubscriptionId*

Integer

Unique identifier of the Subscription in Naviga System

PaymentMethodId*

Integer

Unique identifier of the payment method in Naviga System

DonationAmount

Decimal

Donation amount

TipAmount

Decimal

Tip amount

TotalAmount*

Decimal

The total amount being paid (PaymentOptionAmount + TipAmount + DonationAmount + ProcessingFeeAmount + ProcessingFeeTaxAmount).

If the PaymentType is Credit Card for NCS clients, an Activation Fee is charged to the TotalAmount.

Total Amount for NCS = PaymentOptionAmount + TipAmount + DonationAmount + ProcessingFeeAmount + ProcessingFeeTaxAmount + ActivationFee

PaymentOptionAmount*

Decimal

The Payment Option Amount being paid.

IgnoreFee

Boolean

Indicate whether the Activation Fee should be ignored. Applicable for NCS clients.

TransactionId

String

Transaction ID created by the Payment Gateway when creating a new Payment Method. Applicable for Matrix clients.

ProcessingFeeAmount

Decimal

The Fee amount being paid. Applicable for NCS clients.

ProcessingFeeTaxAmount

Decimal

The Fee tax amount being paid. Applicable for NCS clients.

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

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

{
   "Code":400,
   "Errors":[
      {
         "Message":"The Total Amount is invalid.",
         "Code":"Payments_29",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Error getting newspaper configuration settings",
         "Code":"Payments_18",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Subscription not found.",
         "Code":"Payments_03",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"SubscriberData not found.",
         "Code":"Payments_04",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Payment Method not found.",
         "Code":"Payments_05",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Payment Method Type is not allowed.",
         "Code":"Payments_06",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"COMP subscription are not allowed to make payments",
         "Code":"Payments_27",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The currency is empty in subscription.",
         "Code":"Payments_23",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The subscription is on EzPay already",
         "Code":"Payments_07",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Invalid subscription status",
         "Code":"Payments_19",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The subscription already made a payment over the last 24 hours",
         "Code":"Payments_13",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Failed to create Payment event.",
         "Code":"Payments_02",
         "Type":{
            "Id":1,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Authorized funds has failed.",
         "Code":"Payments_09",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Failed when Processing Circ System.",
         "Code":"Payments_10",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Update Subscription Data failed.",
         "Code":"Payments_20",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Update Subscription Payment Method Id failed.",
         "Code":"Payments_21",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The amount of retries to validate your payment session reached the maximum allowed",
         "Code":"Payments_26",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The surcharge amounts only apply for Credit Card payment methods",
         "Code":"Payments_16",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

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

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

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

{
    "error": "Invalid authorization."
}

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

EZPay Sign Up

Introduction

This endpoint is used to create a payment method for a recurring payment (EZPay) in Circulation Systems (NCS Circ, CircPro, Saxo, and Matrix) and assign it to a subscription in Naviga System.

Comparison

Compared to the older model, the new input model requires just a few parameters, as explained in detail below.

Billing API (OLD)

Payments API (NEW)

URL

/Billing/Payments/{subscriptionId}/EzPaySignup

/Payment/EzPay

Method

POST

Input Example

{
   "ExternalPaymentMethodId":"mt8wvvpf",
   "CustomerId":null,
   "GiveTip":false,
   "TipAmount":0.0,
   "TotalAmount":0.0,
   "PaymentSelectedAmount":7.62,
   "TermsAndConditionsAccepted":true,
   "NewPaymentMethod":null,
   "ParentEventId":0,
   "GiveDonation":false,
   "DonationAmount":0.0,
   "Last4Digits":null,
   "AuthToken":null,
   "AuthTokenPaymentMethodType":0,
   "IsTipAutoRenew":null,
   "IsDonationAutoRenew":null,
   "ValidateMaxAmount":null,
   "Token":null,
   "RenewalTerm":"Week",
   "RenewalLength":"4",
   "RateCode":null,
   "AccountInfo":{
      "SubscriptionId":257175,
      "SubscriberId":91646,
      "RegistrationId":543
   }
}

NCS (DTI)

{ 
  "SubscriptionId": 2122613, 
  "PaymentMethodId": 3044934, 
  "RenewalTerm":"Week",
  "RenewalLength":"12",
  "PaymentOptionAmount":7.62,
  "TipAmount": 1.0,
}

Saxo (DSI)

{ 
  "SubscriptionId": 2122613, 
  "PaymentMethodId": 3044934, 
  "PaymentOptionAmount":7.62,
  "TipAmount": 1.0,
  "DonationAmount": 1.0,
}

CircPro

{ 
  "SubscriptionId": 2122613, 
  "PaymentMethodId": 3044934, 
  "RenewalTerm":"M",
  "RenewalLength":"1",
  "PaymentOptionAmount":7.62,
}

Matrix

{ 
  "SubscriptionId": 2122613, 
  "PaymentMethodId": 3044934, 
  "RenewalTerm":"1 MONTH",
  "PaymentOptionAmount":7.62,
  "TipAmount": 1.0,
}

POST /Payment/EzPay

This endpoint is used to create a payment method for a recurring payment (EZPay) in Circulation Systems and assign it to a subscription in Naviga System.

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-MediaGroupCode*

String

Media Group Code of the Tenant

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

Request Body

Name

Type

Description

SubscriptionId*

Integer

Unique identifier of the Subscription in Naviga System.

PaymentMethodId*

Integer

Unique identifier of the payment method in Naviga System.

DonationAmount

Decimal

Donation amount.

TipAmount

Decimal

Tip amount.

PaymentOptionAmount

Decimal

EZPay Option Amount that will be paid.

RenewalTerm

String

Indicates the term to the Circulation System Provider. Applicable only for Matrix, CircPro, and NCS.

RenewalLength

String

Indicates the length to the Circulation System Provider. Applicable only for Matrix, CircPro, and NCS.

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

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

{
   "Code":400,
   "Errors":[
      {
         "Message":"Subscription not found.",
         "Code":"Payments_03",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The subscription is on EzPay already",
         "Code":"Payments_07",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Payment Method not found.",
         "Code":"Payments_05",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Not eligible for EzPay. Only Active subscriptions can sign up for EzPay",
         "Code":"Payments_08",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The currency is empty in subscription.",
         "Code":"Payments_23",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Operation is not allowed because subscription has a permanent stop scheduled at a future date",
         "Code":"Payments_14",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The subscription already made a payment over the last 24 hours",
         "Code":"Payments_13",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The amount of retries to validate your payment session reached the maximum allowed",
         "Code":"Payments_26",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

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

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

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

{
    "error": "Invalid authorization."
}

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

{
   "Code":400,
   "Errors":[
      {
         "Message":"COMP subscription are not allowed to make payments",
         "Code":"Payments_27",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Create Event EzPay failed.",
         "Code":"Payments_15",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Update Subscription Data failed.",
         "Code":"Payments_20",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

Update EZPay Info

Introduction

This endpoint is used to update the payment method for a recurring payment (EZPay) in Circulation Systems (NCS Circ, CircPro, and Matrix) and assign it to a subscription in Naviga System

Comparison

Compared to the older model, the new input model requires just a few parameters, as explained in detail below.

The new endpoint fires the CHGCC/CHGACH event and assigns the payment method to the subscription.

Billing API (OLD)

Payments API (NEW)

URL

/Billing/{subscriptionId}/PaymentMethods

/Payment/EzPay

Method

PUT

Input Example

{
   "PaymentMethod":{
      "PaymentMethodId":0,
      "ExternalPaymentMethodId":"10203992",
      "PaymentMethodType":1,
      "PaymentMethodTypeName":"CreditCard",
      "PlatformSpecificTypeName":null,
      "AccountHolder":"EARL HROZA",
      "CreditCard":{
         "CardType":2,
         "CreditCardType":2,
         "CreditCardNumber":"XXXXXXXXXXXX1111",
         "ExpirationYear":2028,
         "ExpirationMonth":2,
         "CardSecurityCode":"",
         "CardOwner":"john smith",
         "LastFourDigits":"1111"
      },
      "BankAccount":null,
      "PayPalInfo":null,
      "OfflinePayment":null,
      "BillingAddress":{
         "AddressId":1700202,
         "BillingSystemAddressId":null,
         "PrimaryAddress":null,
         "AlternateAddresses":null,
         "CountryName":null,
         "CityName":null,
         "DistrictName":null,
         "ProvinceOrTerritory":null,
         "PhoneNumber":null,
         "ZipCode":null,
         "AddressName":null
      },
      "PaymentSource":null,
      "TermsAndConditionsAccepted":true,
      "ExternalToken":"10203992",
      "ExternalCustomerId":null,
      "IsDefault":false
   },
   "BillingAddressId":1700202,
   "ValidateAddress":null,
   "AccountInfo":{
      "SubscriptionId":245316,
      "SubscriberId":4784,
      "RegistrationId":0
   }
}

{
  "PaymentMethodId": 789496
  "SubscriptionId": 238778
}

Update EzPay Info

PUT /Payment/EzPay

This endpoint is used to update the payment method for a recurring payment (EZPay) in Circulation Systems and assign it to a subscription in Naviga System.

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-MediaGroupCode*

String

Media Group Code of the Tenant

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

Request Body

Name

Type

Description

SubscriptionId*

Integer

Unique identifier of the Subscription in Naviga System.

PaymentMethodId*

Integer

Unique identifier of the payment method in Naviga System.

{
  "Code": 200,
  "Errors": [],
  "Result": {
    "EventId": 0,
    "IsSuccess": true
  },
  "SessionId": "string",
  "RequestId": "string"
}

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

{
   "Code":400,
   "Errors":[
      {
         "Message":"Subscription not found.",
         "Code":"Payments_03",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Payment Method not found.",
         "Code":"Payments_05",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The currency is empty in subscription.",
         "Code":"Payments_23",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The payment method was already modified over the last 24 hours.",
         "Code":"Payments_32",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The amount of retries to validate your payment session reached the maximum allowed",
         "Code":"Payments_26",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

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

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

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

{
    "error": "Invalid authorization."
}

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

{
   "Code":400,
   "Errors":[
      {
         "Message":"COMP subscription are not allowed to make payments",
         "Code":"Payments_27",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The subscription is not on EzPay.",
         "Code":"Payments_28",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Failed to create Payment event.",
         "Code":"Payments_02",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Update Subscription Payment Method Id failed.",
         "Code":"Payments_21",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

Restart

Introduction

This endpoint is used to restart a stopped subscription in Circulation Systems (NCS Circ and Matrix).

Comparison

Compared to the older model, the new input model requires just a few parameters, as explained in detail below.

Billing API (OLD)

Payments API (NEW)

URL

/Billing/Payments/{subscriptionId}/RestartPayment

/Payment/Restart

Method

POST

Input Example

{
   "ExternalPaymentMethodId":"4d9fbd88-d523-4ccd-baf2-fb30a83f8bd2",
   "CustomerId":null,
   "GiveTip":false,
   "TipAmount":0.0,
   "TotalAmount":106.90,
   "PaymentSelectedAmount":100.0,
   "CurrencyCode":null,
   "PaymentMethodType":0,
   "NewPaymentMethod":null,
   "TypeOfPayment":null,
   "ParentEventId":0,
   "GiveDonation":false,
   "DonationAmount":0.0,
   "Last4Digits":null,
   "AuthToken":null,
   "AuthTokenPaymentMethodType":0,
   "SignUpToEzPay":false,
   "IsTipAutoRenew":null,
   "IsDonationAutoRenew":null,
   "ApplyToCredit":false,
   "ValidateMaxAmount":null,
   "InvoiceId":null,
   "CreateMapOnTheFly":false,
   "Notes":null,
   "Token":"4d9fbd88-d523-4ccd-baf2-fb30a83f8bd2",
   "RenewalTerm":"Month",
   "RenewalLength":"3",
   "RateCode":"VCP7DOnlineUS",
   "RestartDate":"2023-05-24T00:00:00",
   "IgnoreFee":false,
   "TransactionId":null,
   "AccountInfo":{
      "SubscriptionId":105842,
      "SubscriberId":104327,
      "RegistrationId":4127
   }
}

{
   "PaymentMethodId":73746,
   "TotalAmount":3.46,
   "PaymentOptionAmount":1.46,
   "TipAmount": 2.0,
   "DonationAmount": 0.0,
   "SubscriptionId":74250,
   "RenewalTerm":null,
   "RenewalLength":null,
   "RestartDate":null,
   "TransactionId":null,
   "ProcessingFeeAmount": 2.0,
   "ProcessingFeeTaxAmount": 3.0
}

Restart

POST /Payment/Restart

This endpoint is used to restart a stopped subscription in Circulation Systems (NCS Circ and Matrix)

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-MediaGroupCode*

String

Media Group Code of the Tenant

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

Request Body

Name

Type

Description

SubscriptionId*

Integer

Unique identifier of the Subscription in Naviga System

PaymentMethodId*

Integer

Unique identifier of the payment method in Naviga System

DonationAmount

Decimal

Donation amount

TipAmount

Decimal

Tip amount

TotalAmount*

Decimal

The total amount being paid (PaymentOptionAmount + TipAmount + DonationAmount + ProcessingFeeAmount + ProcessingFeeTaxAmount - Subscription’s Balance).

If the MG2 Control Setting "Restart.ApplyCreditBalance" has been turned off and the Subscription’s Balance is positive, then it won’t be deducted from the total. If Subscription’s Balance is negative (debt), it should always be in the math.

Take into consideration that each consumer application should do the math, so the setting should be consumed there too.

PaymentOptionAmount*

Decimal

The Restart Option Amount being paid.

TransactionId

String

Transaction ID created by the Payment Gateway when creating a new Payment Method. Applicable for Matrix clients.

ProcessingFeeAmount

Decimal

The Fee amount being paid. Applicable for NCS clients.

ProcessingFeeTaxAmount

Decimal

The Fee tax amount being paid. Applicable for NCS clients.

CreateRestartEvent

Boolean

Indicates whether to create the RESTART event.

For Saxo, CreateRestartEvent can be set to False if the client chooses to restart payment without restarting the subscription. Otherwise, this is optional.

RenewalLength

String

Indicates the Circulation System Provider's renewal length. Applicable for CircPro and NCS.

RenewalTerm

String

Indicates the Circulation System Provider's renewal term. Applicable for CircPro and NCS.

RestartDate

DateTime

Indicates the Subscription’s Restart Date. Currently, this is applicable for CircPro and Matrix.

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

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

{
   "Code":400,
   "Errors":[
      {
         "Message":"The Total Amount is invalid.",
         "Code":"Payments_29",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Error getting newspaper configuration settings",
         "Code":"Payments_18",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Subscription not found.",
         "Code":"Payments_03",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"SubscriberData not found.",
         "Code":"Payments_04",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Payment Method not found.",
         "Code":"Payments_05",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"COMP subscription are not allowed to make payments",
         "Code":"Payments_27",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The currency is empty in subscription.",
         "Code":"Payments_23",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The subscription already made a payment over the last 24 hours",
         "Code":"Payments_13",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Failed to create Payment event.",
         "Code":"Payments_02",
         "Type":{
            "Id":1,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Authorized funds has failed.",
         "Code":"Payments_09",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Update Subscription Data failed.",
         "Code":"Payments_20",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The amount of retries to validate your payment session reached the maximum allowed",
         "Code":"Payments_26",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The surcharge amounts only apply for Credit Card payment methods",
         "Code":"Payments_16",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

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

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

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

{
    "error": "Invalid authorization."
}

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

{
   "Code":400,
   "Errors":[
      {
         "Message":"The payment cannot be processed. The subscription is not Stop.",
         "Code":"Payments_22",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Restart Payment event failed.",
         "Code":"Payments_24",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Restart Subscription event failed.",
         "Code":"Payments_25",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Capture funds has failed.",
         "Code":"Payments_11",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Restart date cannot be in the past",
         "Code":"Payments_33",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

Create Payment Method

Introduction

This endpoint is used to create a new payment method for a Subscriber using either a Credit Card or a Bank Account and to create a new record in the PaymentMethod table in the database.

Comparison

Compared to the older model, the new input model requires just a few parameters, as explained in detail below.

Note: For the time being, both the old and new endpoints are in the Billing API.

Billing API (OLD)

Billing API (NEW)

URL

/Billing/{subscriptionId}/PaymentMethods

/Billing/PaymentMethods

Method

POST

Input Example

{
   "PaymentMethod":{
      "PaymentMethodId":0,
      "ExternalPaymentMethodId":"10203992",
      "PaymentMethodType":1,
      "PaymentMethodTypeName":"CreditCard",
      "PlatformSpecificTypeName":null,
      "AccountHolder":"EARL HROZA",
      "CreditCard":{
         "CardType":2,
         "CreditCardType":2,
         "CreditCardNumber":"XXXXXXXXXXXX1111",
         "ExpirationYear":2028,
         "ExpirationMonth":2,
         "CardSecurityCode":"",
         "CardOwner":"john smith",
         "LastFourDigits":"1111"
      },
      "BankAccount":null,
      "PayPalInfo":null,
      "OfflinePayment":null,
      "BillingAddress":{
         "AddressId":1700202,
         "BillingSystemAddressId":null,
         "PrimaryAddress":null,
         "AlternateAddresses":null,
         "CountryName":null,
         "CityName":null,
         "DistrictName":null,
         "ProvinceOrTerritory":null,
         "PhoneNumber":null,
         "ZipCode":null,
         "AddressName":null
      },
      "PaymentSource":null,
      "TermsAndConditionsAccepted":true,
      "ExternalToken":"10203992",
      "ExternalCustomerId":null,
      "IsDefault":false
   },
   "BillingAddressId":1700202,
   "ValidateAddress":null,
   "AccountInfo":{
      "SubscriptionId":245316,
      "SubscriberId":4784,
      "RegistrationId":0
   }
}

Credit Card example:

{
  "HolderName": "Clark Kent",
  "CreditCard": {
    "CreditCardExpirationMonth": "06",
    "CreditCardExpirationYear": "12",
    "CreditCardNumber": "4111********1111",
    "CreditCardType": 1
  },
  "BillingAddressId": 1859629,
  "BillingSystemPaymentMethodId": "test",
  "PaymentGatewayToken": "ASFWE234234",
  "PaymentGatewayCustomerId": "HKUSDYISD"
  "SubscriptionId": 20,
  "PaymentMethodType": 1
}

BankAccount example:

{
  "HolderName": "Bruce Wayne",
  "BankAccount": {
    "BankAccountNumber": "123456",
    "BankAccountType": 1,
    "BankName": "Gotham City Bank",
    "BankRoutingNumber": "3456324"
  },
  "BillingAddressId": 0,
  "SubscriptionId": 20,
  "PaymentMethodType": 2
}

Create Payment Method

POST /Billing/PaymentMethods

This endpoint is used to create a new payment method for a Subscriber using either a Credit Card or a Bank Account and to create a new record in the PaymentMethod table in the database.

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-MediaGroupCode*

String

Media Group Code of the Tenant

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

Request Body

Name

Type

Description

SubscriptionId*

Integer

Unique identifier of the Subscription in Naviga System

BillingAddressId

Integer

Unique identifier of the current Subscriber Billing address in Naviga System.

BillingSystemPaymentMethodId

String

Unique identifier of the payment method in Naviga System.

(Used by the data team.)

HolderName*

String

For a Bank Account payment method, it’s the Subscriber’s name, and for a Credit Card payment method, it’s the Credit Card name.

CreditCard.CreditCardType

Integer

Represents the credit card type. Possible values: American Express (1), Visa (2), MasterCard (3), Diners (4), Discover (5).

CreditCard.CreditCardNumber

String

Masked Credit Card number.

Required if Payment Method is Credit Card.

CreditCard.CreditCardExpirationYear

Integer

Credit card expiration year.

Required if Payment Method is Credit Card.

CreditCard.CreditCardExpirationMonth

Integer

Credit card expiration month.

Required if Payment Method is Credit Card.

BankAccount.BankAccountNumber

String

Bank account number.

Required if Payment Method is Bank Account.

BankAccount.BankName

String

Name of the bank.

Required if Payment Method is Bank Account.

BankAccount.BankAccountType

Integer

Represents the bank account type.

Required if Payment Method is Bank Account.

Possible values: CheckingsAccount(1), SavingsAccount (2), CorporateCheckingsAccount(3).

PaymentMethodType

Integer

Represents the payment method type.

Possible values: CreditCard(1), BankAccount(2), MerchantAcceptedPayment(3), Coupon(4), PayPal(5), PayPalExpress(6), iTunes(7), GooglePlay(8), ApplePay(9), AmazonInApp(10), SubscribeWithGoogle(11), GooglePay(12), ExternalPayment(13), Piano(14)

PaymentGatewayCustomerId

String

Unique identifier of the Payment Method’s owner in the Payment Gateway Systems.

Required if Payment Method is Credit Card.

Note: This parameter is not managed by all payment gateways; however, Stripe, Braintree, and NavigaPay do.

PaymentGatewayToken

String

Unique identifier of the Payment Method in the Payment Gateway Systems (Payway, AuthorizeNET, Stripe, Braintree, NavigaPay, etc).

Required (and mandatory) if Payment Method is Credit Card.

PaymentMethod.CreditCard.CardOwner

String

Credit card Owner name.

Required if Payment Method is Credit Card.

BankAccount.BankRoutingNumber

String

Bank account routing number.

Required if Payment Method is Bank Account.

{
  "Code": 200,
  "Errors": [],
  "Result": {
    "PaymentMethodId": 789507
  },
  "SessionId": null,
  "RequestId": null
}

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

{
   "Code":400,
   "Errors":[
      {
         "Message":"Subscription not found.",
         "Code":"Billing_01",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Billing Address not found.",
         "Code":"Billing_03",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":500,
   "Errors":[
      {
         "Message":"Error getting newspaper configuration settings.",
         "Code":"Billing_02",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":500,
   "Errors":[
      {
         "Message":"Failed to create ADDPAYMENTMETHOD Event.",
         "Code":"Billing_04",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":500,
   "Errors":[
      {
         "Message":"Failed to update ADDPAYMENTMETHOD Event.",
         "Code":"Billing_05",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Failed when saving Payment Method to DB.",
         "Code":"Billing_06",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

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

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

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

{
    "error": "Invalid authorization."
}

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

Get Payment Method by Id

Introduction

This endpoint is used to retrieve the payment method information from the Naviga System based on the provided input parameter, PaymentMethodId.

Comparison

Note: For the time being, both the old and new endpoints are in the Billing API.

Billing API (OLD)

Billing API (NEW)

URL

/Billing/{subscriptionId}/PaymentMethods/{paymentMethodId}

/Billing/PaymentMethods/{paymentMethodId}

Method

GET

Input Example

FromUri, subscriptionId and paymentMethodId

/Billing/1/PaymentMethods/1

FromUri, paymentMethodId

/Billing/PaymentMethods/1

Get Payment Method by Id

GET /Billing/PaymentMethods/{paymentMethodId}

This endpoint is used to retrieve the payment method information from the Naviga System based on the provided input parameter, PaymentMethodId.

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-MediaGroupCode*

String

Media Group Code of the Tenant

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

Request Body

Name

Type

Description

PaymentMethodId*

Integer

Unique identifier of the payment method in Naviga System

{
  "Code": 200,
  "Errors": [],
  "Result": {
    "PaymentMethod": {
      "HolderName": "Test Test",
      "BankAccount": null,
      "BillingAddress": {
        "AddressId": 1859629,
        "StreetAddress": "424 B ST APT 11",
        "CityName": "MARYSVILLE",
        "StateCode": "CA",
        "ZipCode": "95901-5721",
        "ProvinceOrTerritory": "CA",
        "CountryCode": "US",
        "HouseNumber": "424",
        "StreetName": "B",
        "StreetSuffix": "ST",
        "DistrictName": "YUBA",
        "FipsCode": "06115",
        "UnitType": "APT",
        "UnitNumber": "11",
        "AddressName": "",
        "PhoneNumber": "",
        "BillingSystemAddressId": "1001634"
      },
      "CreditCard": {
        "CardOwner": "Test Test",
        "CreditCardType": 0,
        "CreditCardNumber": "411111******1111",
        "CreditCardExpirationMonth": "12",
        "CreditCardExpirationYear": "26"
      },
      "PaymentMethodId": 789496,
      "BillingSystemPaymentMethodId": "10193724",
      "PaymentGatewayToken": null,
      "PaymentGatewayCustomerId": null,
      "PaymentMethodTypeId": 1
    }
  },
  "SessionId": "27ec1745-8678-46ec-8fb7-fab743716383",
  "RequestId": "test"
}

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

{
   "Code":404,
   "Errors":[
      {
         "Message":".",
         "Code":"Billing_07",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

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

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

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

{
    "error": "Invalid authorization."
}

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

Add Tip

Introduction

This endpoint is used to handle the one-time and recurring payment transactions to add tips.

Comparison

Compared to the older model, the new input model requires just a few parameters, as explained in detail below.

Billing API (OLD)

Payments API (NEW)

URL

/Billing/Payments/{subscriptionId}/AddTip

/Payment/Tip

Method

POST

Input Example

{
   "ExternalPaymentMethodId":"10200849",
   "CustomerId":null,
   "TipAmount":0.0,
   "CurrencyCode":null,
   "PaymentMethodType":0,
   "NewPaymentMethod":null,
   "TypeOfPayment":null,
   "ParentEventId":0,
   "Last4Digits":null,
   "AuthToken":"10200849",
   "AuthTokenPaymentMethodType":2,
   "IsTipAutoRenew":null,
   "ApplyToCredit":false,
   "ValidateMaxAmount":false,
   "InvoiceId":null,
   "CreateMapOnTheFly":false,
   "Notes":null,
   "Token":null,
   "RenewalTerm":"Month",
   "RenewalLength":"1",
   "RateCode":null,
   "RestartDate":null
}

{
   "PaymentMethodId":789771,
   "SubscriptionId":245316,
   "TipAmount":2.0,
   "TotalAmount":7.0,
   "IsTipAutoRenew":true,
   "ProcessingFeeAmount": 2.0,
   "ProcessingFeeTaxAmount": 3.0
}

Add Tip

POST /Payment

This endpoint is used to handle the one-time and recurring payment transactions to add tips.

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-MediaGroupCode*

String

Media Group Code of the Tenant

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

Request Body

Name

Type

Description

SubscriptionId*

Integer

Unique identifier of the Subscription in Naviga System

PaymentMethodId*

Integer

Unique identifier of the payment method in Naviga System

TipAmount*

Decimal

Tip amount

ProcessingFeeAmount

Decimal

The Fee amount being paid. Applicable for NCS clients.

ProcessingFeeTaxAmount

Decimal

The Fee tax amount being paid. Applicable for NCS clients.

IsTipAutoRenew*

Boolean

Indicates whether the Tip amount should be auto-renewed.

TotalAmount*

Decimal

Total amount being paid (TipAmount + ProcessingFeeAmount + ProcessingFeeTaxAmount)

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

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

{
   "Code":400,
   "Errors":[
      {
         "Message":"The Total Amount is invalid.",
         "Code":"Payments_29",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Error getting newspaper configuration settings",
         "Code":"Payments_18",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Subscription not found.",
         "Code":"Payments_03",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"SubscriberData not found.",
         "Code":"Payments_04",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Payment Method not found.",
         "Code":"Payments_05",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Payment Method Type is not allowed.",
         "Code":"Payments_06",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"COMP subscription are not allowed to make payments",
         "Code":"Payments_27",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The currency is empty in subscription.",
         "Code":"Payments_23",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Invalid subscription status",
         "Code":"Payments_19",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The subscription already made a payment over the last 24 hours",
         "Code":"Payments_13",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Failed to create Payment event.",
         "Code":"Payments_02",
         "Type":{
            "Id":1,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Authorized funds has failed.",
         "Code":"Payments_09",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Failed when Processing Circ System.",
         "Code":"Payments_10",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Update Subscription Data failed.",
         "Code":"Payments_20",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Update Subscription Payment Method Id failed.",
         "Code":"Payments_21",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The amount of retries to validate your payment session reached the maximum allowed",
         "Code":"Payments_26",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The surcharge amounts only apply for Credit Card payment methods",
         "Code":"Payments_16",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

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

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

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

{
    "error": "Invalid authorization."
}

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

{
   "Code":400,
   "Errors":[
      {
         "Message":"The payment method was already modified over the last 24 hours.",
         "Code":"Payments_32",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"To set up an auto renew tip the subscription has to be on EzPay.",
         "Code":"Payments_31",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"The tip amount exceeds the maximum allowed.",
         "Code":"Payments_17",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Capture funds has failed.",
         "Code":"Payments_11",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

{
   "Code":400,
   "Errors":[
      {
         "Message":"Update transaction failed.",
         "Code":"Payments_12",
         "Type":{
            "Id":2,
            "Code":"Processing"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}

Users Orchestrator API

Migration to UsersOrchestrator API

Introduction

This section outlines the process to be followed in order to migrate from the old UserAPI endpoints to the new UsersOrchestratorAPI endpoints. This section also shows a comparison of the old and new APIs.

The endpoints covered in this section are as listed below:

Get By Id
Get By Email
Get By Query String
Get By Encrypted Email
Get By Encrypted Id
Get By Token
Create User
Create Passwordless User
Update User
Update Password
Update Email
Authenticate / Authenticate By Token
ForgotPassword
Verify Email
Send Verification Code

ProxyAPI Information

In order to redirect to UserAPI or to UsersOrchestratorAPI, ProxyAPI must have the following settings in place:

MG2 Control Internal setting, UsersOrchestrator - Its value includes a "string.Format" that must be utilized to determine the correct API route. The value by default is "{0}/UsersOrchestrator".

Note: Since the ProxyAPI directly calls the UsersOrchestratorAPI, GatewayAPI is not involved in the request chain.

IgnoreProvider Considerations

This flag is included in the Body or QueryString of certain endpoints.
This parameter is used to retrieve only SubscribeRegistration results while ignoring third-party integration services. This is an optional parameter that modifies the workflow execution.

User States

The UserOrchestrator API also includes the registration status in the API response.

The GET /Users and GET /Users/id endpoints will include the output parameter, State, which returns the status of a registration.
- The registration's status will be returned as follows:
  - If the tenant has been associated with a third-party authentication system such as Auth0, Firefly, etc., the State will be returned as Standard.
  - If the tenant has been associated with MG2 Auth:
    When the Password field in the database remains blank, the State will be Lite.
    When the Verified field in the database has been set to False, the State will be Unverified.
    When the Password field hasn't been blank and the Verified field has been set to true, the State will be Standard.
The POST /Users endpoint will display an error when trying to create a registration that already exists in the database and has the Verified field set to false.
The POST /Users/Authentication endpoint will display an error when trying to login with an Unverified or Lite registration.

Get By Id

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API.

With the input parameter Customer Registration ID (CRID), the API gets the user's information from both the integration service and the subscribe registration. The response displays the combined information.

Based on the value of Flow.UserProvider and the IgnoreProvider input parameter, the API gives user information in the following way:

If no valid value is provided in Flow.UserProvider, the API retrieves user information from the Subscribe Registration API.
If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to True, the API retrieves user information from the Subscribe Registration API.
If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to False, the user's details are retrieved from both the integration service and the subscribe registration. The combined information is displayed in the response.

Note

MG2 control flow setting: Flow.UserProvider value should be set to "Auth0," "Gigya," "SSOR", or "Firefly", depending on the third-party system or integration service being used.
MG2 control flow setting, "Flow.Users.RedirectToOrchestrator", value has to be set to 1 for the ProxyAPI redirection to the UsersOrchestratorAPI instead of the UserAPI.

Comparison

Parameters

The parameter, Type, has been deprecated.
A new parameter, IgnoreProvider, has been added.

Note: The old model is in PascalCase, while the new model is in CamelCase.

Get User by Id

GET /v4/Users/{customerRegistrationId}/?ignoreProvider={boolean}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the CustomerRegistrationId.

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

Path Parameters

Query Parameters

Headers

{
    "message": {
        "code": "UsersOrchestrator_S200_01",
        "text": "GetById completed.",
        "type": "Success"
    },
    "data": {
        "customerRegistrationId": "string",
        "encryptedCustomerRegistrationId": "string",
        "email": "string",
        "verified": true,
        "state": "UserStates",
        "lastLogoutDate": "Date",
        "firstName": "string",
        "lastName": "string",
        "metadata": {
            "title": "",
            "phoneNumber": "",
            "gender": "",
            "age": "",
            "dob": "",
            "dobYYYY": "",
            "acceptsEmailOffers": "",
            "acceptsEmailAds": "",
            "acceptsEmailPromotions": "",
            "address": "",
            "city": "",
            "country": "",
            "position": "",
            "isOkToEmail": "",
            "isOkToPhone": "",
            "isOkToMail": "",
            "workPhone": "",
            "timeZone": "",
            "scoreMember": "",
            "companyName": "",
            "postalCode": "",
            "cellPhone": "",
            "acceptsEENotification": "",
            "ebill_flag": "",
            "eadvan_flag": "",
            "eedition_flag": "",
            "ee_email_flag": "",
            "promo_flag": "",
            "feat_flag": "",
            "dealdigger_flag": "",
            "ads_flag": "",
            "member_event_flag": "",
            "contentEngagement_flag": "",
            "subcom_flag": "",
            "survey_flag": "",
            "accountUpdates_flag": "",
            "photo": "",
            "displayName": "",
            "optOutMarketing": "",
            "agreeToTerms": "",
            "bounceType": "",
        },
        "addDate": "Date",
        "addSource": "string",
        "changeDate": "Date",
        "changeSource": "string"
    }
}

Error Code: UsersOrchestrator_E400 Error Message: Bad Request
Error Code: UsersOrchestrator_E400_01
Error Message: Invalid Id

Error Code: UsersOrchestrator_E500 Error Message: Internal Server Error
Error Code: UsersOrchestrator_E500_01
Error Message: There was a problem during the GetById workflow.

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Get By Email

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API.

With the input parameter Email (Subscriber’s email), the API gets the user's information from both the integration service and the subscribe registration. The response displays the combined information.

Based on the value of Flow.UserProvider and the IgnoreProvider input parameter, the API gives user information in the following way:

If no valid value is provided in Flow.UserProvider, the API retrieves user information from the Subscribe Registration API.
If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to True, the API retrieves user information from the Subscribe Registration API.
If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to False, the user's details are retrieved from both the integration service and the subscribe registration. The combined information is displayed in the response.

Comparison

Parameters

The parameter, Type, has been deprecated.
A new parameter, IgnoreProvider, has been added.

Note: The old model is in PascalCase, while the new model is in CamelCase.

User API

Users Orchestrator API

Get By Email

GET /v4/Users?email={email}&ignoreProvider={boolean}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the Email.

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

Query Parameters

Headers

{
    "message": {
        "code": "UsersOrchestrator_S200_02",
        "text": "Get completed.",
        "type": "Success"
    },
    "data": [
        {
            "customerRegistrationId": "string",
            "encryptedCustomerRegistrationId": "string",
            "email": "string",
            "firstName": "string",
            "lastName": "string",
            "state": "UserStates",
            "metadata": {
                "title": "",
                "phoneNumber": "",
                "gender": "",
                "age": "",
                "dob": "",
                "dobYYYY": "",
                "acceptsEmailOffers": "",
                "acceptsEmailAds": "",
                "acceptsEmailPromotions": "",
                "address": "",
                "city": "",
                "country": "",
                "position": "",
                "isOkToEmail": "",
                "isOkToPhone": "",
                "isOkToMail": "",
                "workPhone": "",
                "timeZone": "",
                "scoreMember": "",
                "companyName": "",
                "postalCode": "",
                "cellPhone": "",
                "acceptsEENotification": "",
                "ebill_flag": "",
                "eadvan_flag": "",
                "eedition_flag": "",
                "ee_email_flag": "",
                "promo_flag": "",
                "feat_flag": "",
                "dealdigger_flag": "",
                "ads_flag": "",
                "member_event_flag": "",
                "contentEngagement_flag": "",
                "subcom_flag": "",
                "survey_flag": "",
                "accountUpdates_flag": "",
                "photo": "",
                "displayName": "",
                "optOutMarketing": "",
                "agreeToTerms": "",
                "bounceType": "",
            },
            "verified": true
        }
    ],
    "meta": {
        "totalRecords": 0
    }
}

Error Code: UsersOrchestrator_E400_02 Error Message: Invalid InputModel
Error Code: UsersOrchestrator_E400 Error Message: Bad Request

Error Code: UsersOrchestrator_E500 Error Message: Internal Server Error
Error Code: UsersOrchestrator_E500_02
Error Message: There was a problem during the Get workflow.

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Get By Query String

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to retrieve the user's information based on the provided Query String parameters.

Based on the value of Flow.UserProvider and the IgnoreProvider input parameter, the API gives user information in the following way:

If no valid value is provided in Flow.UserProvider, the API retrieves user information from the Subscribe Registration API.
If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to True, the API retrieves user information from the Subscribe Registration API.
If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to False, the user's details are retrieved from both the integration service and the subscribe registration. The combined information is displayed in the response.

Note

MG2 control flow setting: Flow.UserProvider value should be set to "Auth0," "Gigya," "SSOR", or "Firefly", depending on the third-party system or integration service being used.
MG2 control flow setting, "Flow.Users.RedirectToOrchestrator", value has to be set to 1 for the ProxyAPI redirection to the UsersOrchestratorAPI instead of the UserAPI.

Comparison

Parameters

The following parameters have been deprecated.
1. Type
2. OnlyActive
3. SortBy
4. SortOrder
5. UsersPerPage
6. LookupInUserProvider
7. AuthSystemId
A set of new parameters has been added.
1. PageSize
2. OrderBy
3. OrderByType
4. IgnoreProvider

Note: The old model is in PascalCase, while the new model is in CamelCase.

User API

Users Orchestrator API

URL

/User/{queryString}

/v4/Users/{queryString}

Method

GET

Response

{
  "Code": 0,
  "Errors": [
    {
      "Message": "string",
      "Code": "string",
      "Type": {
        "Id": 0,
        "Code": "string"
      },
      "ErrorSource": "string"
    }
  ],
  "Result": {
    "Users": [
      {
        "RegistrationId": 0,
        "LoginName": "string",
        "LoginPassword": "string",
        "CustomerRegistrationId": "string",
        "EncryptedCustomerRegistrationId": "string",
        "FirstName": "string",
        "LastName": "string",
        "Email": "string",
        "Gender": "string",
        "Phone": "string",
        "MobilePhone": "string",
        "OptInEVantageSubscriberRewards": true,
        "OptInSpecialOffers": true,
        "OptInContestAndPromotions": true,
        "OptInPaperlessBilling": true,
        "OptInEEdition": true,
        "OptInEEditionEmailNotification": true,
        "OptInSubscriberDiscounts": true,
        "OptInAdvertiserEmails": true,
        "MemberEvent": true,
        "ContentEngagement": true,
        "SUBCOM": true,
        "Survey": true,
        "AccountUpdates": true,
        "DateOfBirth": "string",
        "BirthYear": "string",
        "AcceptsEmailOffers": 0,
        "AcceptsEmailAds": 0,
        "AcceptsEmailPromotions": 0,
        "IsOkToEmail": 0,
        "IsOkToPhone": 0,
        "IsOkToMail": 0,
        "AcceptsEENotification": 0,
        "ChangeDate": "2023-06-05T18:43:26.757Z",
        "DateRegistered": "2023-06-05T18:43:26.757Z",
        "AddDate": "2023-06-05T18:43:26.757Z",
        "Photos": [
          {
            "Id": "string",
            "Value": "string",
            "Type": "string"
          }
        ],
        "IsSocial": true,
        "DisplayName": "string",
        "AgreeToTerms": true,
        "OptOutMarketing": true,
        "Photo": "string",
        "VerificationCode": "string",
        "Verified": true,
        "AuthSystem": {
          "AuthSystemId": 0,
          "AuthSystemCode": "string",
          "AuthSystemName": "string"
        },
        "UserState": {
          "UserStateId": 0,
          "UserStateCode": "string"
        },
        "BounceType": "string",
        "LastLogoutDate": "2023-06-05T18:43:26.757Z",
        "UrlPasswordChangeTicket": "string",
        "Metadata": {}
      }
    ],
    "TotalUsersFound": 0
  },
  "SessionId": "string",
  "RequestId": "string"
}

{
    "message": {
        "code": "string",
        "text": "string",
        "type": 0
    },
    "meta": {
        "totalRecords": 0
    },
    "data": [
        {
            "customerRegistrationId": "string",
            "encryptedCustomerRegistrationId": "string",
            "email": "string",
            "verified": true,
            "firstName": "string",
            "lastName": "string",
            "state": UserState,
            "metadata": {
                "title": "",
                "phoneNumber": "",
                "gender": "",
                "age": "",
                "dob": "",
                "dobYYYY": "",
                "acceptsEmailOffers": "",
                "acceptsEmailAds": "",
                "acceptsEmailPromotions": "",
                "address": "",
                "city": "",
                "country": "",
                "position": "",
                "isOkToEmail": "",
                "isOkToPhone": "",
                "isOkToMail": "",
                "workPhone": "",
                "timeZone": "",
                "scoreMember": "",
                "companyName": "",
                "postalCode": "",
                "cellPhone": "",
                "acceptsEENotification": "",
                "ebill_flag": "",
                "eadvan_flag": "",
                "eedition_flag": "",
                "ee_email_flag": "",
                "promo_flag": "",
                "feat_flag": "",
                "dealdigger_flag": "",
                "ads_flag": "",
                "member_event_flag": "",
                "contentEngagement_flag": "",
                "subcom_flag": "",
                "survey_flag": "",
                "accountUpdates_flag": "",
                "photo": "",
                "displayName": "",
                "optOutMarketing": "",
                "agreeToTerms": "",
                "bounceType": "",
            }
        }
    ]
}

Get User by Query String

GET /v4/Users/{queryString}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the provided Query String parameters.

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

Path Parameters

Name

Type

Description

CustomerRegistrationId*

String

Unique identifier for the user in the authentication provider.

Query Parameters

Name

Type

Description

IgnoreProvider

Boolean

Indicates whether to retrieve the user details from the integration service.

EncryptedEmail

String

Encrypted email of the user

String

Email or partial email address of the user

PageSize

Integer

Maximum number of items returned per request.

Default value 10.

PageNumber

Integer

Requested page number of pagination. Default value 1.

OrderByType

Integer

Sort the records in ascending (0) or descending (1) order.

OrderBy

Integer

Sort the records based on the column number.

FirstName

String

User’s first name.

LastName

String

User’s last name.

Metadata

Dictionary <String, String>

Since it is a dictionary query parameter, each "Key-Value" pair must be sent individually with the prefix "metadata.".

For example, if the purpose is to filter users based on their first and last names, the query string will be: https://UrlBase/Users?metadata.firstName=FirstName&metadata.lastName=LastName”

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-ClientGroupCode*

String

Client Group Code of the Tenant

{
    "message": {
        "code": "UsersOrchestrator_S200_02",
        "text": "Get completed.",
        "type": "Success"
    },
    "data": [
        {
            "customerRegistrationId": "string",
            "encryptedCustomerRegistrationId": "string",
            "email": "string",
            "firstName": "string",
            "lastName": "string",
            "state": "UserStates",
            "metadata": {
                "title": "",
                "phoneNumber": "",
                "gender": "",
                "age": "",
                "dob": "",
                "dobYYYY": "",
                "acceptsEmailOffers": "",
                "acceptsEmailAds": "",
                "acceptsEmailPromotions": "",
                "address": "",
                "city": "",
                "country": "",
                "position": "",
                "isOkToEmail": "",
                "isOkToPhone": "",
                "isOkToMail": "",
                "workPhone": "",
                "timeZone": "",
                "scoreMember": "",
                "companyName": "",
                "postalCode": "",
                "cellPhone": "",
                "acceptsEENotification": "",
                "ebill_flag": "",
                "eadvan_flag": "",
                "eedition_flag": "",
                "ee_email_flag": "",
                "promo_flag": "",
                "feat_flag": "",
                "dealdigger_flag": "",
                "ads_flag": "",
                "member_event_flag": "",
                "contentEngagement_flag": "",
                "subcom_flag": "",
                "survey_flag": "",
                "accountUpdates_flag": "",
                "photo": "",
                "displayName": "",
                "optOutMarketing": "",
                "agreeToTerms": "",
                "bounceType": "",
            },
            "verified": true
        }
    ],
    "meta": {
        "totalRecords": 0
    }
}

Error Code: UsersOrchestrator_E400 Error Message: Bad Request
Error Code: UsersOrchestrator_E400_02
Error Message: Invalid InputModel

Error Code: UsersOrchestrator_E500 Error Message: Internal Server Error
Error Code: UsersOrchestrator_E500_02
Error Message: There was a problem during the Get workflow.

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Current

New

Note

SUBSCRIBE_USER_GET (4000)

New event created to get User from Subscribe

Get By Encrypted Email

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API.

With the input parameter Encrypted Email (Subscriber’s encrypted email), the API gets the user's information from both the integration service and the subscribe registration. The response displays the combined information.

Comparison

Note: The old model is in PascalCase, while the new model is in CamelCase.

User API

Users Orchestrator API

Get By Encrypted Email

GET /v4/Users?email={email}&ignoreProvider={boolean}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the Encrypted Email.

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

Query Parameters

Name

Type

Description

Headers

{
    "message": {
        "code": "string",
        "text": "string",
        "type": 0
    },
    "meta": {
        "totalRecords": 0
    },
    "data": [
        {
            "customerRegistrationId": "string",
            "encryptedCustomerRegistrationId": "string",
            "email": "string",
            "verified": true,
            "firstName": "string",
            "lastName": "string",
            "state": "UserState",
            "metadata": {
                "title": "",
                "phoneNumber": "",
                "gender": "",
                "age": "",
                "dob": "",
                "dobYYYY": "",
                "acceptsEmailOffers": "",
                "acceptsEmailAds": "",
                "acceptsEmailPromotions": "",
                "address": "",
                "city": "",
                "country": "",
                "position": "",
                "isOkToEmail": "",
                "isOkToPhone": "",
                "isOkToMail": "",
                "workPhone": "",
                "timeZone": "",
                "scoreMember": "",
                "companyName": "",
                "postalCode": "",
                "cellPhone": "",
                "acceptsEENotification": "",
                "ebill_flag": "",
                "eadvan_flag": "",
                "eedition_flag": "",
                "ee_email_flag": "",
                "promo_flag": "",
                "feat_flag": "",
                "dealdigger_flag": "",
                "ads_flag": "",
                "member_event_flag": "",
                "contentEngagement_flag": "",
                "subcom_flag": "",
                "survey_flag": "",
                "accountUpdates_flag": "",
                "photo": "",
                "displayName": "",
                "optOutMarketing": "",
                "agreeToTerms": "",
                "bounceType": "",
            }
        }
    ]
}

Error Code: UsersOrchestrator_E400_02 Error Message: Invalid InputModel
Error Code: UsersOrchestrator_E400
Error Message: Bad Request

Error Code: UsersOrchestrator_E500 Error Message: Internal Server Error
Error Code: UsersOrchestrator_E500_02
Error Message: There was a problem during the Get workflow.

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Get By Encrypted Id

Introduction

This endpoint retrieves the user's information from both the integration service and the subscribe registration based on the input parameter Encrypted Customer Registration ID.

With the input parameter Encrypted CRID, the API gets the user's information from both the integration service and the subscribe registration. The response displays the combined information.

Comparison

Note: The old model is in PascalCase, while the new model is in CamelCase.

User API

Users Orchestrator API

Get By Encrypted ID

GET /v4/Users?encryptedCustomerRegistrationId={encryptedCustomerRegistrationId}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the Encrypted Customer Registration ID.

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

Query Parameters

Name

Type

Description

Headers

{
    "message": {
        "code": "string",
        "text": "string",
        "type": 0
    },
    "meta": {
        "totalRecords": 0
    },
    "data": [
        {
            "customerRegistrationId": "string",
            "encryptedCustomerRegistrationId": "string",
            "email": "string",
            "verified": true,
            "firstName": "string",
            "lastName": "string",
            "state": "UserState",
            "metadata": {
                "title": "",
                "phoneNumber": "",
                "gender": "",
                "age": "",
                "dob": "",
                "dobYYYY": "",
                "acceptsEmailOffers": "",
                "acceptsEmailAds": "",
                "acceptsEmailPromotions": "",
                "address": "",
                "city": "",
                "country": "",
                "position": "",
                "isOkToEmail": "",
                "isOkToPhone": "",
                "isOkToMail": "",
                "workPhone": "",
                "timeZone": "",
                "scoreMember": "",
                "companyName": "",
                "postalCode": "",
                "cellPhone": "",
                "acceptsEENotification": "",
                "ebill_flag": "",
                "eadvan_flag": "",
                "eedition_flag": "",
                "ee_email_flag": "",
                "promo_flag": "",
                "feat_flag": "",
                "dealdigger_flag": "",
                "ads_flag": "",
                "member_event_flag": "",
                "contentEngagement_flag": "",
                "subcom_flag": "",
                "survey_flag": "",
                "accountUpdates_flag": "",
                "photo": "",
                "displayName": "",
                "optOutMarketing": "",
                "agreeToTerms": "",
                "bounceType": "",
            }
        }
    ]
}

Error Code: UsersOrchestrator_E400_02 Error Message: Invalid InputModel
Error Code: UsersOrchestrator_E400
Error Message: Bad Request

Error Code: UsersOrchestrator_E500 Error Message: Internal Server Error
Error Code: UsersOrchestrator_E500_02
Error Message: There was a problem during the Get workflow.

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Get By Token

Introduction

This endpoint retrieves the user's information from both the integration service and the subscribe registration based on the input parameter Token (access token generated in the consumer application).

UsersOrchestrator doesn’t support this operation.

Current Proxy URL: POST User/Token

Create User

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to create a user.

Comparison

Note:

The old model is in PascalCase, while the new model is in CamelCase.
Cookie tokens will not be returned by the UsersOrchestrator API.
For custom fields, use Metadata.

User API

Users Orchestrator API

Create User

POST /v4/Users

This endpoint is used to create a user.

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

Headers

Request Body

{
  "message":{
      "code": "UsersOrchestrator_S200_06",
      "text": "Create completed.",
      "type": "Success"
  },
  "data": {
      "customerRegistrationId": "string",
      "encryptedCustomerRegistrationId": "string"     
  }
}

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Create Passwordless User

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to create a user.

Comparison

When creating a passwordless user, UsersOrchestrator will generate a dummy password and the proper Change Password URL.

Note:

The old model is in PascalCase, while the new model is in CamelCase.
Cookie tokens will not be returned by the UsersOrchestrator API.
For custom fields, use Metadata.

User API

Users Orchestrator API

Create Passwordless User

POST /v4/Users

This endpoint is used to create a user without a password.

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

Headers

Request Body

{
    "message": {
        "code": "UsersOrchestrator_S200_06",
        "text": "Create completed.",
        "type": "Success"
    },
    "data": {
        "customerRegistrationId": "string",
        "encryptedCustomerRegistrationId": "string"
    }
}

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Update User

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to update a user based on the provided CustomerRegistrationId.

Comparison

Note:

The old model is in PascalCase, while the new model is in CamelCase.
Cookie tokens will not be returned by the UsersOrchestrator API.
For custom fields, use Metadata.

User API

Users Orchestrator API

Update User

PUT /v4/Users/{customerRegistrationId}/

This endpoint is used to update a user.

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

Path Parameters

Headers

Request Body

{
  "message":{
      "code": "UsersOrchestrator_S200_07",
      "text": "Update completed.",
      "type": "Success"
  },
  meta: null
}

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Entitlements Orchestrator API