Difference between revisions of "NATS4 Upgrade Plus"
TMMStephenY (talk | contribs) |
|||
| (22 intermediate revisions by 8 users not shown) | |||
| Line 3: | Line 3: | ||
}} | }} | ||
| − | Upgrade Plus is a feature in [[NATS4]] that allows you to potentially shorten a Member's Trial by offering them incentives to upgrade in your Members Area. If the member chooses to opt out of their free trial with Upgrade Plus, you will need to update your member records after they complete the upgrade. | + | Upgrade Plus is a feature in [[NATS4]] that allows you to potentially shorten a [[Ct#Member|Member]]'s Trial by offering them incentives to upgrade in your Members Area. If the [[Ct#Member|member]] chooses to opt out of their free trial with Upgrade Plus, you will need to update your member records after they complete the upgrade. |
To do this, you can give the following link to your users in order to upgrade them: | To do this, you can give the following link to your users in order to upgrade them: | ||
<pre><nowiki>http://<linkdomain>/signup/upgradeplus.php?site=<siteid>&username=<username></nowiki></pre> | <pre><nowiki>http://<linkdomain>/signup/upgradeplus.php?site=<siteid>&username=<username></nowiki></pre> | ||
| − | Replace <linkdomain> with the site's actual [[ct#Link Domain|linkdomain]], then replace <siteid> with the site's NATS site I.D. number. Finally you must replace <username> with the user's NATS username. | + | Replace <linkdomain> with the site's actual [[ct#Link Domain|linkdomain]], then replace <siteid> with the [[Ct#Site|site]]'s [[NATS]] site I.D. number. Finally you must replace <username> with the user's NATS username. |
| − | + | == Using Custom Passthroughs (Available in NATS 4.1.17.2 & up) == | |
| − | <pre><nowiki>http://<linkdomain>/signup/upgradeplus.php?site=<siteid>&username=<username>& | + | In addition, you can update custom 1-10 fields during the upgradeplus page in one of two ways:<br> |
| + | 1.) Including a hidden variable "upgrade_vars[custom1]" on your upgrade template (gateway_upgrade/thirdparty_upgrade depending on biller(s) used). Example: | ||
| + | <pre><nowiki><input type="hidden" name="upgrade_vars[custom1]" value="test"></nowiki></pre> | ||
| + | OR<br> | ||
| + | 2.) Build a full submit url which passes in the 'upgrade_vars[custom1]' parameter. Example: | ||
| + | <pre><nowiki>http://<linkdomain>/signup/upgradeplus.php?site=<siteid>&username=<username>&submit=1&email=XXXX@XXXX.com&upgrade_vars[custom1]=test</nowiki></pre> | ||
| − | + | For both provided examples, the member record's 'custom1' field value would be updated to be "test". You can set custom1 - custom10 fields. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | For | ||
== Username == | == Username == | ||
| − | In NATS, you can replace <username> with <?=$_SERVER['REMOTE_USER']?>. In CARMA, you can replace <username> with {$username}. | + | In [[NATS]], you can replace <username> with <?=$_SERVER['REMOTE_USER']?>. In [[CARMA]], you can replace <username> with {$username}. |
== Updating Member Records == | == Updating Member Records == | ||
| − | After the biller upgrades the member, you need to update their account in your system. This means they probably need to login again. | + | After the [[Ct#Biller|biller]] upgrades the [[Ct#Member|member]], you need to update their account in your system. This means they probably need to login again. |
| − | If you use [[MySQL Auth]] in your Server to authenticate members using the NATS members table, you can add an additional check to see if a member is in their trial or full membership and give them the right access respectively. Go to [[Sites Admin]] and enter the the login page URL in the Upgrade Approval URL field or set up a Upgrade Approval Template that re-logs in the user. | + | If you use [[MySQL Auth]] in your Server to authenticate members using the [[NATS]] members table, you can add an additional check to see if a [[Ct#Member|member]] is in their trial or full membership and give them the right access respectively. Go to the [[NATS4 Sites Admin|Sites Admin]] and enter the the login page URL in the Upgrade Approval URL field or set up a Upgrade Approval Template that re-logs in the user. |
If you use your own user management system, you can use the Upgrade Post URL to send upgrade notifications to your own scripts. Your scripts should mark the member as upgrade. If your system requires the user to log in again, use the Upgrade Approval URL or Upgrade Approval Template as described above. | If you use your own user management system, you can use the Upgrade Post URL to send upgrade notifications to your own scripts. Your scripts should mark the member as upgrade. If your system requires the user to log in again, use the Upgrade Approval URL or Upgrade Approval Template as described above. | ||
| Line 33: | Line 33: | ||
== Multiple Sites == | == Multiple Sites == | ||
| − | If you have | + | If you have your Member's Area shared across multiple sites and can't be sure which [[Ct#Site|site]] the [[Ct#Member|member]] is coming from, you can send a comma separated list of siteids instead of just one. To do this, use the siteids field instead of the [[Ct#Site|site]] field. Be advised: If you have a member that belongs to multiple sites with the same username, NATS may not retrieve the correct member. In this situation, you should send the specific siteid of the member attempting to upgrade. |
<pre><nowiki>http://<linkdomain>/signup/upgradeplus.php?siteids=<siteid1>,<siteid2>&username=<username></nowiki></pre> | <pre><nowiki>http://<linkdomain>/signup/upgradeplus.php?siteids=<siteid1>,<siteid2>&username=<username></nowiki></pre> | ||
| − | Replace <siteid1> with the first site's NATS site I.D. number, <siteid2> with the I.D. of the second site, etc. Replace <username> with the user's NATS username. | + | Replace <siteid1> with the first site's [[NATS]] site I.D. number, <siteid2> with the I.D. of the second site, etc. Replace <username> with the user's NATS username. |
| − | Replace <linkdomain> with the site's linkdomain. | + | Replace <linkdomain> with the site's [[Ct#Linkdomain|linkdomain]]. |
| − | If you are using Epoch and this may be an epoch member, you will want to append this a returnurl field for epoch. | + | If you are using [[NATS4 Epoch|Epoch]] and this may be an epoch member, you will want to append this a returnurl field for epoch. |
<pre><nowiki>http://<linkdomain>/signup/upgradeplus.php?siteids=<siteid1>,<siteid2>&username=<username>&returnurl=http://<linkdomain>/signup/epoch_upgradeplus_returnurl.php</nowiki></pre> | <pre><nowiki>http://<linkdomain>/signup/upgradeplus.php?siteids=<siteid1>,<siteid2>&username=<username>&returnurl=http://<linkdomain>/signup/epoch_upgradeplus_returnurl.php</nowiki></pre> | ||
| − | If a non-Epoch member uses the the upgrade URL above, NATS removes the Return URL field and only sends the information needed. | + | If a non-Epoch [[Ct#Member|member]] uses the the upgrade URL above, [[NATS]] removes the Return URL field and only sends the information needed. |
== Additional Security == | == Additional Security == | ||
| − | As of [[ | + | As of [[NATS4.1]], Upgrade Plus offers additional security features that you can use to further secure your [[Ct#Member|member]] upgrades. The ''MEMBER_STRING_AUTH_UPGRADEPLUS'' variable allows you to choose whether or not you wish to use the new [[Ct#Member|member]] auth strings, which contain a variety of information and are designed to prevent unwanted upgrade attempts by outside sources. |
| − | + | This feature will be set to off by default. If you want to enable this feature for your Upgrade Plus transactions, you can add the following necessary code to the ''config.php'' script on your [[NATS]] server: | |
<pre> | <pre> | ||
| − | $config['MEMBER_STRING_AUTH_UPGRADEPLUS'] = | + | $config['MEMBER_STRING_AUTH_UPGRADEPLUS'] = 1; |
</pre> | </pre> | ||
| − | This | + | This will activate the ''MEMBER_STRING_AUTH_UPGRADEPLUS setting to use additional security for your [[Ct#Member|member]] authorization strings. Do not add the provided code if you want to leave this feature disabled. |
| − | Once you have activated this setting, you must use the ''get_member_instant_upgrade_string'' API call to get the correct auth string for the [[Ct#Member|member]] you want to upgrade. Please see our [[NATS4 API Get Member Instant Upgrade String|API Get Member Instant Upgrade String]] wiki | + | Once you have activated this setting, you must use the ''[[NATS4 API Get Member Instant Upgrade String|get_member_instant_upgrade_string]]'' API call to get the correct auth string for the [[Ct#Member|member]] you want to upgrade. Please see our [[NATS4 API Get Member Instant Upgrade String|API Get Member Instant Upgrade String]] or [[NATS5 REST API Member GET authstring|REST member GET authstring]] wiki articles for more information on this process. |
This function will return the auth string necessary for [[Ct#Member|members]] to get authenticated for the Upgrade Plus process. Include the auth string in the link for your [[Ct#Member|member]], and they will be able to perform an instant upgrade using Upgrade Plus using the ''MEMBER_STRING_AUTH_UPGRADEPLUS'' setting. | This function will return the auth string necessary for [[Ct#Member|members]] to get authenticated for the Upgrade Plus process. Include the auth string in the link for your [[Ct#Member|member]], and they will be able to perform an instant upgrade using Upgrade Plus using the ''MEMBER_STRING_AUTH_UPGRADEPLUS'' setting. | ||
| + | |||
| + | <pre> | ||
| + | http://<linkdomain>/signup/upgradeplus.php?site=<siteid>&username=<username>&authstring=<authstring> | ||
| + | </pre> | ||
| + | |||
| + | === Throttling === | ||
| + | |||
| + | Throttling is a security setting available in [[NATS4.1]], which allows you to lock out [[Ct#Surfer|surfers]] for a specified period of time if they make too many attempts on certain pages in [[NATS]]. | ||
| + | |||
| + | You can use the Throttling feature to help secure your ''upgradeplus.php'' page, preventing [[Ct#Surfer|surfers]] from forcing transactions without the correct auth string. Just go to the "Security" configuration page, found in the [[NATS4 Configuration Admin|Configuration Admin]]. | ||
| + | |||
| + | For more information on this feature, please see our '''[[Throttling]]''' wiki article. | ||
== More Detailed information on the page == | == More Detailed information on the page == | ||
* {list_tours full=1 site=$member.siteid} Populates the tours array with detailed information | * {list_tours full=1 site=$member.siteid} Populates the tours array with detailed information | ||
* $tours[$member.tourid] will be an array of all the tour data, such as link domain, etc, as specified for [[Nats_list_tours|list tours]] | * $tours[$member.tourid] will be an array of all the tour data, such as link domain, etc, as specified for [[Nats_list_tours|list tours]] | ||
| + | |||
| + | == Pass Through Data == | ||
| + | |||
| + | '''Note: this feature works for ALL billers that have a NATS Upgradeplus integration via a backend call. Only the following billers that have a NATS Upgradeplus integration via a redirect have this functionality'''<br> | ||
| + | Epoch - 5.0.2.7<br> | ||
| + | SegPay - 5.0.2.7<br> | ||
| + | |||
| + | As of version 5.0.2.7, NATS allows you to send subscription pass through data for instant upgrade transactions. You can use any of the available subscription pass through fields. For example, to send the member_subscription->passthrough2 field, you need to add the following to your upgradeplus.php link. | ||
| + | |||
| + | <pre> | ||
| + | &member_extra[0][subscription_passthrough2]=<your value here> | ||
| + | </pre> | ||
| + | |||
| + | You will also need to make sure that your Upgradeplus templates include the following code. | ||
| + | |||
| + | <pre> | ||
| + | {if !empty($memberExtra) && is_array($memberExtra)} | ||
| + | {foreach from=$memberExtra key=member_extra_key item=member_extra_val} | ||
| + | {if is_array($member_extra_val)} | ||
| + | {foreach from=$member_extra_val key=member_extra_key2 item=member_extra_val2} | ||
| + | <input type="hidden" name="member_extra[{$member_extra_key|escape:'htmlall'}][{$member_extra_key2|escape:'htmlall'}]" value="{$member_extra_val2}"/> | ||
| + | {/foreach} | ||
| + | {else} | ||
| + | <input type="hidden" name="member_extra[{$member_extra_key|escape:'htmlall'}]" value="{$member_extra_val}"/> | ||
| + | {/if} | ||
| + | {/foreach} | ||
| + | {/if} | ||
| + | </pre> | ||
| + | |||
| + | Additionally, you can use the UPGRADEPLUS_INHERIT_SUBSCRIPTION_PASSTHROUGH_DATA config setting (config admin -> surfer page, one-click systems section) to tell NATS how to deal with the subscription pass through variables. | ||
| + | {| class="wikitable" | ||
| + | |Do Not Inherit (default) | ||
| + | |blank out existing subscription pass through values, only use the values from the member_extra array | ||
| + | |- | ||
| + | |Inherit and Override | ||
| + | |override subscription pass through values with the values from the member_extra array | ||
| + | |- | ||
| + | |Inherit and Override blank values | ||
| + | |override subscription pass through values with the values from the member_extra array only if the existing value is blank (0 is not blank) | ||
| + | |- | ||
| + | |Inherit Only | ||
| + | |do not update the subscription pass through values, values from the member_extra array will be ignored | ||
| + | |} | ||
| + | |||
| + | |||
| + | [[Category:NATS4 Billers Admin]] | ||
| + | [[Category:NATS4 Sites]] | ||
Latest revision as of 16:32, 15 September 2020
Upgrade Plus is a feature in NATS4 that allows you to potentially shorten a Member's Trial by offering them incentives to upgrade in your Members Area. If the member chooses to opt out of their free trial with Upgrade Plus, you will need to update your member records after they complete the upgrade.
To do this, you can give the following link to your users in order to upgrade them:
http://<linkdomain>/signup/upgradeplus.php?site=<siteid>&username=<username>
Replace <linkdomain> with the site's actual linkdomain, then replace <siteid> with the site's NATS site I.D. number. Finally you must replace <username> with the user's NATS username.
Using Custom Passthroughs (Available in NATS 4.1.17.2 & up)
In addition, you can update custom 1-10 fields during the upgradeplus page in one of two ways:
1.) Including a hidden variable "upgrade_vars[custom1]" on your upgrade template (gateway_upgrade/thirdparty_upgrade depending on biller(s) used). Example:
<input type="hidden" name="upgrade_vars[custom1]" value="test">
OR
2.) Build a full submit url which passes in the 'upgrade_vars[custom1]' parameter. Example:
http://<linkdomain>/signup/upgradeplus.php?site=<siteid>&username=<username>&submit=1&email=XXXX@XXXX.com&upgrade_vars[custom1]=test
For both provided examples, the member record's 'custom1' field value would be updated to be "test". You can set custom1 - custom10 fields.
Username
In NATS, you can replace <username> with <?=$_SERVER['REMOTE_USER']?>. In CARMA, you can replace <username> with {$username}.
Updating Member Records
After the biller upgrades the member, you need to update their account in your system. This means they probably need to login again.
If you use MySQL Auth in your Server to authenticate members using the NATS members table, you can add an additional check to see if a member is in their trial or full membership and give them the right access respectively. Go to the Sites Admin and enter the the login page URL in the Upgrade Approval URL field or set up a Upgrade Approval Template that re-logs in the user.
If you use your own user management system, you can use the Upgrade Post URL to send upgrade notifications to your own scripts. Your scripts should mark the member as upgrade. If your system requires the user to log in again, use the Upgrade Approval URL or Upgrade Approval Template as described above.
Multiple Sites
If you have your Member's Area shared across multiple sites and can't be sure which site the member is coming from, you can send a comma separated list of siteids instead of just one. To do this, use the siteids field instead of the site field. Be advised: If you have a member that belongs to multiple sites with the same username, NATS may not retrieve the correct member. In this situation, you should send the specific siteid of the member attempting to upgrade.
http://<linkdomain>/signup/upgradeplus.php?siteids=<siteid1>,<siteid2>&username=<username>
Replace <siteid1> with the first site's NATS site I.D. number, <siteid2> with the I.D. of the second site, etc. Replace <username> with the user's NATS username. Replace <linkdomain> with the site's linkdomain.
If you are using Epoch and this may be an epoch member, you will want to append this a returnurl field for epoch.
http://<linkdomain>/signup/upgradeplus.php?siteids=<siteid1>,<siteid2>&username=<username>&returnurl=http://<linkdomain>/signup/epoch_upgradeplus_returnurl.php
If a non-Epoch member uses the the upgrade URL above, NATS removes the Return URL field and only sends the information needed.
Additional Security
As of NATS4.1, Upgrade Plus offers additional security features that you can use to further secure your member upgrades. The MEMBER_STRING_AUTH_UPGRADEPLUS variable allows you to choose whether or not you wish to use the new member auth strings, which contain a variety of information and are designed to prevent unwanted upgrade attempts by outside sources.
This feature will be set to off by default. If you want to enable this feature for your Upgrade Plus transactions, you can add the following necessary code to the config.php script on your NATS server:
$config['MEMBER_STRING_AUTH_UPGRADEPLUS'] = 1;
This will activate the MEMBER_STRING_AUTH_UPGRADEPLUS setting to use additional security for your member authorization strings. Do not add the provided code if you want to leave this feature disabled.
Once you have activated this setting, you must use the get_member_instant_upgrade_string API call to get the correct auth string for the member you want to upgrade. Please see our API Get Member Instant Upgrade String or REST member GET authstring wiki articles for more information on this process.
This function will return the auth string necessary for members to get authenticated for the Upgrade Plus process. Include the auth string in the link for your member, and they will be able to perform an instant upgrade using Upgrade Plus using the MEMBER_STRING_AUTH_UPGRADEPLUS setting.
http://<linkdomain>/signup/upgradeplus.php?site=<siteid>&username=<username>&authstring=<authstring>
Throttling
Throttling is a security setting available in NATS4.1, which allows you to lock out surfers for a specified period of time if they make too many attempts on certain pages in NATS.
You can use the Throttling feature to help secure your upgradeplus.php page, preventing surfers from forcing transactions without the correct auth string. Just go to the "Security" configuration page, found in the Configuration Admin.
For more information on this feature, please see our Throttling wiki article.
More Detailed information on the page
- {list_tours full=1 site=$member.siteid} Populates the tours array with detailed information
- $tours[$member.tourid] will be an array of all the tour data, such as link domain, etc, as specified for list tours
Pass Through Data
Note: this feature works for ALL billers that have a NATS Upgradeplus integration via a backend call. Only the following billers that have a NATS Upgradeplus integration via a redirect have this functionality
Epoch - 5.0.2.7
SegPay - 5.0.2.7
As of version 5.0.2.7, NATS allows you to send subscription pass through data for instant upgrade transactions. You can use any of the available subscription pass through fields. For example, to send the member_subscription->passthrough2 field, you need to add the following to your upgradeplus.php link.
&member_extra[0][subscription_passthrough2]=<your value here>
You will also need to make sure that your Upgradeplus templates include the following code.
{if !empty($memberExtra) && is_array($memberExtra)}
{foreach from=$memberExtra key=member_extra_key item=member_extra_val}
{if is_array($member_extra_val)}
{foreach from=$member_extra_val key=member_extra_key2 item=member_extra_val2}
<input type="hidden" name="member_extra[{$member_extra_key|escape:'htmlall'}][{$member_extra_key2|escape:'htmlall'}]" value="{$member_extra_val2}"/>
{/foreach}
{else}
<input type="hidden" name="member_extra[{$member_extra_key|escape:'htmlall'}]" value="{$member_extra_val}"/>
{/if}
{/foreach}
{/if}
Additionally, you can use the UPGRADEPLUS_INHERIT_SUBSCRIPTION_PASSTHROUGH_DATA config setting (config admin -> surfer page, one-click systems section) to tell NATS how to deal with the subscription pass through variables.
| Do Not Inherit (default) | blank out existing subscription pass through values, only use the values from the member_extra array |
| Inherit and Override | override subscription pass through values with the values from the member_extra array |
| Inherit and Override blank values | override subscription pass through values with the values from the member_extra array only if the existing value is blank (0 is not blank) |
| Inherit Only | do not update the subscription pass through values, values from the member_extra array will be ignored |
