Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
This guide is to explain how NCS Circ/Subscribe one-time and auto-renew payment options are displayed on the front-end applications and how payments are processed. This is a technical documentation
Make sure you meet the following pre-requisites before starting the how-to steps:
Have Subscribe 3.13.1 version or above
Previous outstanding balance. Use ‘Balance Due’ field from Circulation API, This value includes tax.
Next Payment term and rates: Use ‘Renewal Total Cost’ from Customer Service API. This value includes tax.
Authorize and capture the sum of ‘Balance Due’ and ‘Renewal Total Cost’
Previous outstanding balance: Use ‘Balance Due’ field from Circulation API. This value includes tax.
Next Payment term and rates: Use ‘Renewal Total Cost’ from Customer Service API. This value includes tax.
Auto-renew sign up. This is a billing change request in NCS Circ. No payment is authorized and captured.
Previous outstanding balance. Authorize and capture ‘Balance Due’.
‘Grace Owned’ is different than ‘Balance Due’ in NCS Circ Customer Service API. ‘Grace Owned’ is assigned when a subscription is stopped and payment is not settled whereas ‘Balance due’ is for active subscriptions.
This feature allows users to leave a tip as a gratitude to the carrier. This is applicable only for subscriptions with printed products as the tip is the payment to the carrier. For those subscriptions on auto-renew there are two options for leaving a tip:
One-time tip - one-time payment to the carrier without any additional payment
Recurring tip - the tip amount will be added to your monthly payment
The feature is available both in Self-Service and One CSR portal.
Make sure you meet the following pre-requisites:
Have NCS Circ 2018.5+SP1+SP2 and Subscribe 3.13 or above for one-time tip
Have NCS Circ 2020.2.1 and Subscribe 3.14 or above for recurring tip
After you updated the NCS circ version please remember to go to CMS and setup a link to the page in Self-Service
Please note that the restriction for the tip to be available for print subscriptions only will work correctly starting from 3.13.1
At the 'Payment/Billing' tab of One CSR Portal for EZPay subscribers, there is an 'Add tip' button. Clicking on this button will open the form with the input for the tip and a 'Recurring' checkbox.
If you tick the checkbox then the tip will be a recurring tip, i.e. made each time an auto-renew payment is made. The same payment method will be used for the tip as for the recurring payment.
If the checkbox is left unticked then the tip will be a one-time payment. You have to select a payment method (credit card or bank account) and enter the payment details.
After a recurring tip has been successfully added you will see a confirmation message
After the one-time payment has been successfully paid you will see a confirmation notification and the payment will appear as a row in the payment table at the bottom of the page. Payment details and tip amount can be found in the ‘Details’ of the table.
Please note that it might not be reflected correctly right after you left a tip as it might take up to 24h to process the tip transaction
At Self-Service a new page has been developed under the /autopay/addtip URL. This page doesn't need to be hidden for all the subscribers except those on auto-renew in CMS as this restriction is done from the API side.
If you tick the 'I want to leave a recurring tip' checkbox then the tip will be a recurring tip, i.e. made each time an auto-renew payment is made. The same payment method will be used for the tip as for the recurring payment. After the recurring tip has been successfully added the confirmation message will be displayed to the user.
If the checkbox is left unticked then the tip will be a one-time payment. You have to select a payment method (credit card or bank account) and enter the payment details. In case a one-time tip has been successfully paid then a confirmation will be displayed to a user with the payment details.
This feature enables NCS Circ clients to apply a surcharge (processing fee) for credit card payments without explicitly itemizing it. When a credit card is selected as the payment method, the surcharge is automatically added to the term amount and displayed as part of the total amount payable, without showing the surcharge as a separate line item. Conversely, if the payment method is a bank account (ACH) or bank draft, no surcharge is applied. As a result, for the same subscription or offer, users will see a difference in pricing depending on whether they choose a credit card or a bank account/draft as their payment method.
The Variable Pricing is not available for payments initiated from SubCon Admin and is not applicable for payments through PayPal.
Day pass subscriptions do not support Variable Pricing.
Subscribe does not calculate the credit card surcharge amount. The surcharge amount is received from the NCS Circ for each transaction.
Make sure you meet the following pre-requisites:
NCS Circ version: 2025-0.0
Subscribe version: 3.17.2
To enable the Variable Pricing functionality, set the MG2 control API Setting Keys
DTI.CashDiscounting to 1
Billing.CreditCard.ProcessingFee.Enable to 0 (this disables Processing Fee flow)
For an end-to-end flow of Variable Pricing, respective Business Rules must be set up in NCS Circ.
The 'Processing Fee' and 'Variable Pricing' features cannot be used simultaneously. If both features are enabled for a client, the Processing Fee feature takes priority. Disabling Processing Fee flow is recommended if you opt for Variable Pricing.
With the Variable Pricing feature, a surcharge will be applied if the payment method involves a credit card—including but not limited to options such as Google Pay or Apple Pay (non-ACH). Conversely, no surcharge will be applied if the payment method is a bank account (ACH) or PayPal.
When Variable Pricing is enabled through the CMS component and the MG2 control key, the subscription cost displayed to users selecting a credit card payment option includes the surcharge amount. However, this surcharge will not be itemized in the payment details (such as processing fees, activation fees, etc.) and will instead be integrated into the total amount shown.
Below is an illustrative new start flow set up in a 'Simple' CMS theme:
Landing page where the users get to see different offers.
Offer details are displayed followed by the display of the components such as User Information, Address Information, Payment Information, and Order summary.
User Information - In this tab, the user enters the email. If the user is new, the user will be prompted to enter a password and confirm the entered password. If the user is already known, an info message such as "This email is already used" will be displayed. (is the email ID already available in the Subscribe database or Auth0?). The user clicks Continue button.
Address Information - The user enters address details.
Payment Information - In this tab, the subscription payment is displayed and the price changes based on the selected Payment Method.
Order Summary
The final Congratulatory page
Landing Page - Heading
Landing Tile - Title & Subtitle
Digital Offer Tile Top - configuration
(Page V3 > Landing-Tiles V3 > Promotion Digital V3 > Tile top Text)
Digital Offer Title & Subtitle - configuration
Digital Offer Details - configuration
(Page V3 > Landing-Tiles V3 > Promotion Digital V3 > Body > Insert an image with offer details)
Components page - Title
Components page Title - configuration
Components page Active sign - configuration
(Page V3 > Offer Selector Tiles V3 > Sign Hide: OFF Active sign color: < # >
Components Page Marketing Text - configuration
Payment Information - Price details
The above configuration is one of the most important prerequisites for the Variable Pricing feature.
If the Variable Pricing feature is enabled in the Self-Service, the credit card surcharge is applied only to the base amount of the offer and any outstanding dues. Elements such as donations, tips, taxes, etc., are excluded from the surcharge calculation. The surcharge amount and the base amount of the offer are sent to NCS. However, these amounts are combined and presented as a single rate term to the end-user on the Self-Service page. As a result, the surcharge is not displayed as a separate line item and remains invisible to the end-user.
Variable pricing can be applied to the following payment flows:
One-time payment
Autopay (EZPay signup)
Restarts
When the Variable Pricing feature is enabled, on the Payment page, there will be two Rate columns in the Rate grid, (one for Credit Card and the other for Bank account) clearly highlighting the rate difference for the same offer with respect to the payment method.
Below is an example list of CMS Contents on each page that can be customized as per your requirement:
(CMS > Content > Select the Page (Payment/SubscriptionRestart/AutoPaySignUp) > Select the appropriate property and edit the label text as per your requirement)
Payment Page -> PaymentOptionsHeader.ACHAmount
Payment -> AutoPaySignUpHeader.ACHAmount
SubscriptionRestart -> PaymentOptionsHeader.ACHAmount
AutoPaySignUp -> AutoPaySignUpHeader.ACHAmount
One-time payments include making a one-time payment for an active subscription that is not on autopay, paying a Tip, or a donation.
The credit card surcharge is not applicable for Tip and Donation amounts even when the payment is done using credit cards.
Hence for one-time Tip and donation payments, the variable pricing will not be in effect since the credit card surcharge is not calculated in these payments. Tip Payment
Adding a Tip feature is ideally not applied to Digital subscriptions.
For a non-digital subscriber, the 'Add Tip' hyperlink will be available on the Dashboard page. Clicking on it opens up the Add a Tip page where the user can enter the Tip amount.
Given below is an example of a one-time Tip payment for an active user who is not on Autopay. The user needs to pay only the Tip amount even when the payment method is a Credit card.
Donation Payment
Both digital and non-digital subscribers can pay for donations. Just like Tip payments, donations are free of surcharges, and hence, variable pricing does not affect donation payment.
Subscription Payment
However, for subscription cost payment, the credit card surcharge will be added to the rate amount, and it will be displayed as a single rate term if the payment method is a credit card.
Below is the Dashboard page of a user who is not on Autopay.
The user clicks on the 'Sign up to EZPay' link.
The rate grid displays varying price details for credit card options and ACH options (bank account) for offers. For an offer with a term length of 4 months, CC Amount is $180.0 whereas ACH Amount (Bank account) is $100.00.
In the above example, the selected payment method is the Credit card option. After entering the credit card details, the final Payment Confirmation page will be displayed as shown below. Please note that during EZPay signup, the user may also opt to pay a Donation amount. The subscription amount will be deducted later.
A subscription can be restarted if,
it is already stopped and stopped within a certain number of days (the number of days is configurable using the MG2 Control key Restart.MaxStoppedDays)
there have been no payment events in the last 24 hours and/or no already pending Restart request with a future date.
it is not a Trial or Complimentary subscription
The visibility of the 'Restart subscription' hyperlink is determined solely by the CMS link restrictions.
When the user clicks on the 'Restart' hyperlink on the Self-Service Dashboard page, the Restart workflow starts.
Restarts with Negative balance: When restarting a stopped subscription, if there is any outstanding amount from the previous subscription, the end-user must pay the negative balance along with the subscription cost.
In this case, the credit card surcharge is calculated on the subscription cost amount and a grace cc surcharge is calculated on the due amount to be paid. These surcharges (cc surcharge and grace cc surcharge) are then added to the subscription cost and will be displayed as a single term in the Amount column of the rate grid. Hence the credit card surcharges are not visible to the end user. The negative balance (debt) will also be displayed separately. Refer to the image below.
Restarts without a Negative balance (no due amount):
For credit card payments, the subscription cost displayed in the Amount column will include the actual cost plus the credit card surcharge. Additionally, the user may choose to pay a donation or tip amount during the restart process. For Bank account payments, the user has to pay just the subscription cost.
When Variable Pricing is enabled and if the payment provider is Fluid Pay via Naviga Pay, split transaction is applicable. For more details on split transactions, refer : Split Transactions for Fluid Pay via Naviga Pay.
Apple Pay offers the possibility to have an electronic wallet under Apple platform during Subscribe checkout flow. The goal of this guide is to help you understand Apple Payments integration in Subscribe for the NCS Circ and Payway clients.
Make sure you meet the following pre-requisites:
Minimum NCS Circ version required is 2020.2
Minimum Subscribe version required is 3.13.1
Subscribe must use PaywayWS to support Apple Pay. This service is a wrapper of EccoWS and PW_Web services
Every Payway request needs to go through PaywayWS
Client have to use Naviga Pay
For Braintree, the Minimum Subscribe version required is 3.15.1
Front end: Subscription Panel via Apple Pay JS and Payway
Back end: Subscribe APIs, NCS Circ, Naviga Pay
Subscription Panel interacts with an Apple Pay JS library. Subscription Panel offers the possibility to use ApplePay for Billing if a client is using Apple device. A user can select one of the two available options:
Apple Pay option within the checkout pages - is supported in frictionless checkout starting from 3.15.0
Apple Pay option as part of offer selector - Please note that this option is not supported in frictionless checkout
You can find the CMS set up details and screenshots of the flow in the table below for each of these two options
From the CMS dashboard:
Select subscription panel then presentations.
Choose your desired presentation from the drop-down menu.
Add the ApplePay V3 as a child component to the PaymentMethods V3 component.
Select save and clear your app's cache by selecting the manage cache button, then the relevant app.
For this type of setup the end-user will have to fill delivery and billing address and user information
The way payment option is displayed can also be changed via CMS by using there is a property called PaymentMethodSelectorStyle property of PaymentMethods V3
Please see the example of the payment step at the screenshot below
From the CMS dashboard:
Select subscription panel then presentations.
Choose your desired presentation from the drop-down menu.
Add the Offer Selector - ApplePay V3 as a child component to the checkout Page V3 component.
Select save and clear your app's cache by selecting the manage cache button, then the relevant app.
Please note that this option is not supported in frictionless checkout.
Note:
This option skips steps like filling up billing address and user information. By clicking on ‘Buy with Apple Pay’ data would come from Apple Pay;
All the steps within check out flow including registration are skipped and user sees confirmation page. You can show an option to register on the confirmation screen;
Data stored in Subscribe/NCS circ if we use Apple pay start as part of offer selector: it depends on user’s wallet settings in Apple. Some fields are optional. A fully set up apple pay account provides the same set of data as collected within subscription panel.
Offer selector screen
Screen after ‘Buy with Apple Pay’ click:
CMS Set up:
From the Solicitor Concierge dashboard:
Select offer groups from the left sidebar. Your offer groups will appear in a list to the right.
Select an offer group from the list, or create a new offer group.
Select the additional options category, then select the payment method drop-down menu.
Check the Apple Pay box. For Braintree, please select the Apple Pay - Braintree checkbox.
Select update or save as new.
When you're viewing a Subscription purchased with ApplePay in Classic CSR Portal you will be able to see a corresponding mark.
A huge Payload is sent to the Subscribe API, which is responsible of decrypting it. For doing so, an algorithm was included as part of the Encryption Library NuGet package.
To decrypt the value, the API provides the NuGet package with the MID and Private Key to be used. These are stored in MG2 Control just like any other setting.
The Encryption Library generates a Shared Secret with the Private Key (provided by API) and the Public Key (payload.Token.PaymentData.Header.EphemeralPublicKey from the Payload).
Then, the symmetric key gets generated by using the secret key and the MID. This is used to decrypt the payload.Token.PaymentData.Data (after a Base64 decode).
Once the data is decrypted, the API performs the regular Newstart flow: Authorization, Create Subscription, Capture Funds, Payment in Circ, Update Transaction. Refer to the sections Circ System and Payment Gateway for more information.
Please input a Salesforce case requesting the Naviga team to setup ApplePay Certificates on your behalf.
Note updated on 04-Jul-23.
You can use existing merchant ids on Payway. All GPAY and ApplePay leverage your existing merchant accounts at TSYS unlike PayPal or Amazon Pay;
All transactions are identified on Payway through the virtual terminal as a Credit Card, ACH, ApplePay, GPAY, etc. for all research inquiries (reports, etc). Note that we have engineered the virtual terminal to operate like credit cards on wallet transactions. That is, you can perform a SALE, CREDIT or VOID on GPAY or ApplePay accounts like you can do with credit cards from within the payway virtual terminal;
Disputes would be handled similarly but with one caveat for ApplePay transactions. The last four and expiry date that NCS receives and also assigned in payway for ApplePay transactions is not the customer’s actual credit card but rather the DPAN or device account number assigned to the customer’s card in the phone/IOS device. So, if there is a dispute, the CSR needs to ask the customer what the last four of the device account number is in their wallet on their device. That is just how applePay works.
From a recurring model, payway assigns our standard token to all transactions for recurring processing.
Management of CC update/expiry etc. in Apple: There is no communication with Apple. The token is valid in Payway if that device account number is valid. If a customer removes that card from their wallet, the token is invalid, and it would get declined.
This guide explores activation fees for one-time payments in NCS Circ.
Make sure you meet the following pre-requisites before starting the how-to steps:
Have NCS Circ 2018.5 or greater
Have set up an adjustment code (eg code: Actfee) for your activation fee in the NCS Circ database
Provide Naviga Implementation Manager with your activation fee code and amount to be configured in Subscribe database.
The front-end application calls NCS Circ's customer service API and GETS Single Payment Terms Info to fetch the one-time payment options. Along with the payment options, the activation fee is displayed.
After entering the payment information and selecting submit, the API POST the payment through NCS Circ and passes the adjustment code 1 and adjustment fee1 as an activation fee code and amount in real-time.
Notes:
If the client uses both the donation and activation fee options for one-time payments, then:
* Adjustment code 1 and amount 1 of the circ API is used for the activation fee code and the amount.
* Adjustment code 2 and amount 2 of the circ API is used for the donation code and the donation amount.
If the NCS Circ API payment calls Payment Amount = (Term) + (Donation) + (Fee), then the tip is not included in the total payment amount. Instead its sent in the tip field.
Donation is not supported in EZ Pay
Google Pay offers the user an opportunity to purchase a Subscription using Google Pay electronic wallet during Subscribe checkout flow. The goal of this guide is to help you understand integration details in Subscribe for the NCS Circulation systems and Payway and Braintree payment processors.
Make sure you meet the following pre-requisites:
Minimum NCS Circ version required is 2020.2-1
Minimum Subscribe version required is 3.14.2 for Payway and 3.16.0 for Braintree
For Payway payment processor Subscribe must use PaywayWS .This service is a wrapper of EccoWS and PW_Web services.
For Payway payment processor every Payway request needs to go through PaywayWS.
Please connect to your implementation manager to turn this feature on. The customer will be responsible for this setup. More information can be found in the .
For the feature to work valid GatewayMerchantId is required, please see Google tutorial on how to request production access .
Please note that Google developer account is required to view Google documentation
The MerchantId needs to be put into a JS file for both test and production environments as shown below
From the Solicitor Concierge dashboard:
Select offer groups from the left sidebar. Your offer groups will appear in a list to the right.
Select an offer group from the list, or create a new offer group.
Select the additional options category, then select the payment method drop-down menu.
Check the GooglePay box.
Select update or save as new.
From the CMS dashboard:
Select subscription panel then presentations. Be sure to apply these changes to the newspaper level.
Choose your desired presentation from the drop-down menu.
Add the GooglePay V3 as a child component to the Payment Method V3 component.
Select save and clear your app's cache by selecting the manage cache button, then the relevant app.
Please note that GooglePay for Frictionless checkout is supported starting from 3.15.0
Congratulations! You've configured a Subscription Purchase with GooglePay electronic wallet. During checkout process you will see 'Pay with Google Pay' button.
Landing Page Heading - configuration (Page V3 > Subtitle)
Landing Tile Title & Subtitle - configuration (Page V3 > Landing-Tiles V3 > Title / Subtitle)
Digital Offer - Tile Top
Digital Offer - Title and Subtitle
(Page V3 > Landing-Tiles V3 > Promotion Digital V3 > Title / Subtitle)
Digital Offer - Details
(Page V3 > Title)
Components page - Subtitle
Components page Subtitle - configuration (Page V3 > Offer Selector - Tiles V3 > Title)
Components page - Active sign
Active sign background color: < # >)
Components page - Marketing Text
(These details come from the SolCon settings of the selected Offer Group. Offer Groups > Marketing text. The components in the Marketing text can be configured as follows: Inventory > Marketing Text > Attributes & Images Title Price)
Payment Information - Price details (if Tax is applicable for the Zipcode entered in the Address)s
Payment Information Price details - configuration (Page V3 > Step V3 > Toggle ON the Pricing labels)
You can also configure the pricing labels' text in the above component properties as given below:
Order summary - Price details
Order Summary - Price details (if Tax is applicable for the zip code entered in the address)
Order Summary Price details - configuration (Page V3 > Step V3 > toggle ON the pricing labels) You can also configure the pricing labels' text in the above component properties as given below:
Note: The property ‘Cash Discounting Enable’ in the PaymentMethodsV3 component should be toggled ON in your CMS Presentation as below: (Page V3 > Step V3 > Payment Methods V3 > Toggle ON the property 'Cash Discounting Enable".
For Bank account payments, the user has to pay just the subscription cost and the debt amount.
