Overview

The TouchNet TD Connect integration combines the benefits of the TouchNet payment gateway processing service with the ease of self-service use through Terra Dotta's e-marketplace platform. Administrators can deploy a payment material to a program application, and applicants can easily make payments from their application page. Transactions are returned to Terra Dotta with a log of payment receipt details for both applicants and administrators.

Are you an existing client? No problem! Existing Terra Dotta clients with a payment gateway integration can transition to the TouchNet TD Connect platform to take advantage of efficient, self-service use.

This article introduces the TouchNet TD Connect integration and covers the following topics:

• Getting Started with TouchNet TD Connect: Contact the required parties.
• Self-Service Setup: Define your settings for TD Connect and payment materials.
• Applicant & Admin View: Review what information applicants and admins see with a TouchNet TD Connect integration. This includes the "Payments" tab in the Application Admin Manager for admins.
• Best Practice Information: Maintaining Your Payment Gateway
• Reporting

 

Getting Started with TouchNet TD Connect

To get started with a TouchNet TD Connect integration, you must first contact TouchNet directly to request a TouchNet T-Link UPay client account. The required value keys, such as a uPay site ID and URL, needed for the TD Connect integration will be provided by TouchNet directly.

Important Note: The TouchNet T-Link UPay account is the only type of TouchNet account that is compatible with the TD Connect integration. Offices whose institutions have a TouchNet account should make sure to check that the account type is TouchNet T-Link UPay.

After you’ve procured a TouchNet T-Link UPay account, contact Terra Dotta by submitting a Support request. Our team will guide you through the initial setup of the TouchNet TD Connect integration. 

For existing clients with or without a payment gateway integration: Submit a Support request and request access to the TouchNet TD Connect platform. 

For implementing TouchNet clients: By default, implementing TouchNet clients will integrate via the TouchNet TD Connect platform - no conversion is needed. To launch this solution, you'll work with both your Project Manager and Account Executive.

 

Self-Service Setup

After your TouchNet TD Connect integration has been turned on and you’ve received confirmation from Terra Dotta that all required configurations have been enabled, the self-service setup can begin. Terra Dotta is available to assist you in determining the proper settings for your respective site during this process.

Important Note: The self-service setup instructions below are the same for both a sandbox or production site as both will require their own respective setup. When engaging in the setup process on a sandbox site, use the "test" TouchNet account settings (i.e. uPay Site ID and URL) when applicable.  

The self-service setup starts with these steps:

1) Set Permissions

To view the TD Connect marketplace, an admin must have the "System Settings: TD Connect" permission enabled under Staff > Staff Permissions > Facilitators > System Settings.

Important Note: This permission does give an admin access to the entire listing of available TD Connect integrations on your production site.

2) Create a Credit Account Code and/or Payment Account Code Program Parameter (optional)

Using program parameters instead of hardcoding values for the Credit Account Code and/or Payment Account Code is an optional step. However, if you decide to utilize this functionality, these program parameters should be set up prior to configuring the related settings in the TouchNet TD Connect modal.

To create a program parameter of Credit Account Code:

• Navigate to Settings > Program Params > New Parameter. This brings you to the "Program Parameter: Add" page. 
• For Parameter Name, enter "Credit Account Code".
• For Parameter Type, choose "Single Selection" from the drop-down menu. This will trigger the appearance of a parameter options panel at the bottom of the page.
• Add the applicable options by entering a value one at a time in the "Add Option" field and clicking Add. Repeat as needed.
• Click "Update" to preserve your changes.

To create a program parameter of Payment Account Code:

• Navigate to Settings > Program Params > New Parameter. This brings you to the "Program Parameter: Add" page. 
• For Parameter Name, enter "Payment Account Code".
• For Parameter Type, choose "Single Selection" from the drop-down menu. This will trigger the appearance of a parameter options panel at the bottom of the page.
• Add the applicable options by entering a value one at a time in the "Add Option" field and clicking Add. Repeat as needed.
• Click "Update" to preserve your changes.

These parameters are available as configuration options from the TouchNet TD Connect modal.

For detailed information about program parameters, visit our Managing Program Parameters Knowledgebase (KB) article.

3) Configure TouchNet Settings

From the TouchNet TD Connect modal, an admin can activate the service on their site and independently set applicable values and parameters. To configure the TouchNet TD Connect settings, follow these steps:

• Navigate to Settings > TD Connect > TouchNet. Click on the cogwheel icon to open the TouchNet modal.
• Check the box next to "Activate" to enable the TouchNet TD Connect service on your site. 
• Make the respective edits to the available modal fields.
• Click "Save" to preserve your changes.

Important Note: If you attempt to select "Activate" and click "Save" before entering the uPay Site ID, URL, and Pay Now Text, you will receive an error message

The modal fields available for editing are as follows:

uPay Site ID: Enter the parameter provided by TouchNet. If the uPay Site ID will be set at the material level, then a default value should be entered.

"Pay Now" Text: Customize the text which displays on the payment button. Example: Pay Today.

uPay URL: Enter the parameter provided by TouchNet. This will be a URL specific to your production site and should not be changed.

Clients will have a different "test" uPay Site ID and URL when connecting to a sandbox (test environment) site versus to a production site. The same interface will appear as described above. 

Credit Account Code

• Choose to hardcode a value (meaning store a fixed, default value) for the Credit Account code to be used for all payments across the entire site. Or,
• Select one program parameter that would be used for programs for the credit account code.

Payment Account Code

• Choose to hardcode a value for the Payment Account Code that would be the same for all payments across your entire site. Or,
• Select one program parameter that would be used for the payment account code. 

Important Note: Program parameters should be created before setting up the Credit and/or Payment Account Codes.

4) Create Payment Program Parameter (optional)

Payment program parameters should be configured before creating the payment material. To create a payment program parameter: 

• Navigate to Settings > Program Params > New Parameter. This brings you to the "Program Parameter: Add" page. 
• For Parameter Type, select "Payment" from the drop-down menu. This will trigger the appearance of a parameter options panel at the bottom of the page.
• Add the applicable numeric options, such as 10, 100, 1000, one at a time by entering the value, clicking "Add", and repeating this action.
• Once done, click "Save" to preserve your changes. 

5) Apply Program-Level Payment Amount (optional)

Once you have created a payment program parameter, you can choose to assign it at the program level by following these steps:

• Navigate to Programs > List All (or search) > (edit program) > Parameters tab.
• Click the edit pencil for the respective payment program parameter. Choose one option from the "Available'" box. Click "Add" to move this option down to the "Selected" box.
• Click the "Add" button at the bottom of the page to preserve your changes.

6) Create Payment Materials

Admins have the ability to set a material process element as a payment material and make edits without the need to submit a Support request.

Important Note: The option to create a payment material in the Admin Console's Content Management only appears after both the TouchNet TD Connect solution is live and Terra Dotta has updated the required system setting. Admins should keep this in mind before creating payment materials and deploying them to programs that are actively accepting applications. If a payment material has been created for testing purposes and is deployed to an application prior to confirming the desired settings, then the payment process could either fail or process payments with the wrong settings.  

Materials should be assigned to a deployment rule so that when the desired conditions of the rule are met, the material will be deployed to the program application. For more information, see the Admin Console: Deployment Rules article.  

To create a new payment material, follow these steps:

• Navigate to Admin Console > Content Management and click on the "Material Submissions" tab.
• Click on the "+" icon in the lower right of the screen. This opens the "Materials: Add" page from which you can configure your material.
• Material Title: Provide a name for your material which reflects the payment type. For example: "Application Fee". The recommended best practice is to not reference a monetary amount in the material title as this amount could change.
• Is this a Payment Material: Clients must enable this toggle in order for the payment functionality to operate (this toggle is deactivated by default). Enabling this setting will trigger the appearance of additional payment setting options which provide admins with additional choices:

Option A) Admins can hard-code values for this material across all programs to which it is deployed.

Example:

• Material Title: Application Fee
• Fixed Amount Field: $100. This is the application fee for all applications that fall within the 2019/2020 app cycles.

For 2020/2021, the application fee goes up to $150. The software does utilize process version management, so if this application fee change does not cascade to the old app cycles, it will stay $100 for the old applications and $150 for the new ones.

Option B) Admins can select a program parameter to determine the Amount, Credit Account Code, Payment Account Code, or uPay Site ID. This sets the value associated with the material for these items at the program level. (Program parameters should be created before setting up the material.)

Example:

An admin creates a program parameter for the application fee amount, deposit fee amount, and final payment amount. When creating a new payment material for an application fee, the admin would not enter a payment account code but would instead choose the application fee parameter from the corresponding payment account code drop-down menu.

• Use the WYSIWYG editor to add desired content. A rich-text editor provides styling options, mail merge options, and the ability to embed media.
• Click "Add" or "Add and Create Rule" to preserve your changes.

Important Notes:

• Edits that are made to the credit account code and/or payment account code fields for a particular payment material via Content Management > Materials: Add or Materials: Edit will overwrite what was set in the TD Connect modal.
  • Example: If this is an application fee and all application fees are associated with one credit account code, you can hard code that within this particular material. Or, if the fee varies by program, you can use a program parameter to set the credit account code for this particular material.
• The aforementioned instructions (for "Create Payment Materials") are unique to the payment material and are required. Otherwise, follow the general instructions for creating a Material process element which are outlined in the "Material Submissions" section of the Admin Console: Content Management article.

 

Applicant and Admin View

Applicant View

On the application page, a payment material will appear by its designated material title as an online requirement.

 

 

When an applicant clicks on the material title, for example "Application Fee", a payment button will appear. After clicking on the payment button, a new window will open. The applicant will be redirected to TouchNet to complete their payment. Once the payment has been processed, applicants are directed back to Terra Dotta where a message of their transaction (i.e. success/failure/cancelled) will appear.

Admin View

The TouchNet TD Connect integration presents admins with updated options in Application Admin Manager. Here, a "Payments" tab will appear when an admin views an application that contains a payment material. Note that a TD Connect Payment Gateway integration must be configured to benefit from this feature.

Information is organized in columns, from left to right, as follows:

• Title: This displays the name of the payment material.
• Current Amount
• Determined By: This is the method by which the payment amount has been determined.
  • A "fixed" amount is configured in the payment material.
  • A "manual override" displays when the admin edits the default amount.
• Payments: This column tracks payment history.
• Actions: An admin can edit, cancel an edit action, or reset the "Current Amount" to the default.

After a payment has been paid and information is a payment history is available to view, the icon under the "Payments" column will become clickable. Clicking that icon will expand the row to display the full payment details.

 

 

Best Practice Information: Maintaining Your Payment Gateway

Test Payment Gateway Program

It's recommended that your sandbox and production sites have a "Test Payment Gateway" program which can be used to review updated payment material and related parameter settings. All payment materials should be associated with the "Test Payment Gateway" program. When investigating payment gateway behavior on your site, Terra Dotta Support may need to create applications for the "support@terradotta.com" user for the "Test Payment Gateway" program. These applications can be scrubbed after the investigation has concluded.

Reporting Unexpected Behavior

If you need to report unexpected behavior related to your payment gateway material, submit a Support request and provide the following information:

• The name of the user experiencing the issue.
• The name of the program and the term for which the application was created.
• The name of the material impacted.
• A description of the unexpected behavior: What steps were taken to arrive at the behavior?
• The date and time of the unexpected behavior and if the behavior is still occurring.

 

Reporting

Terra Dotta's Analytics reporting tool provides the option to create reports on payment information. Use the available "SA-Payment Report" template to generate a query for payment materials with a payment status of "Success". This payment status filter can be modified to view other payment statuses, such as "Initiated" or "Failed". For more information, including a list of related data points for payment information, see the "Query Templates" section of the Analytics for Terra Dotta Study Abroad article