Currently the PayPal PayFlowPro account is the only type of PayPal account that is compatible with the TD Connect integration. Offices whose institutions have a PayPal account should make sure to check that the account type is PayFlowPro.

Overview

The PayPal TD Connect integration combines the benefits of the PayPal 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 PayPal TD Connect platform to take advantage of efficient, self-service use.

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

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

 

Getting Started with PayPal TD Connect

To get started with a PayPal TD Connect integration, you must first contact PayPal directly to request a PayPal PayFlowPro client account. The required values for a PayFlowPro account, such as a PayPal Merchant Login Name, Token URL, Gateway URL, Merchant User, Merchant Password, Key, and Merchant Partner, needed for the TD Connect integration will be provided by PayPal directly.

Important Note: The PayPal PayFlowPro account is the only type of PayPal account that is compatible with the TD Connect integration. Offices whose institutions have a PayPal account should make sure to check that the account type is PayFlowPro.

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

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

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

 

 

Your PayPal Sandbox   

You will need to work with PayPal to confirm that you have sandbox (test) and production environment access for your PayPal account. Without sandbox access, the testing of your payment gateway will not be successful.

To set up a PayPal sandbox account: 

1. Navigate to https://developer.paypal.com/.
2. Click "Log In".
3. Enter your email address and PayPal password in the pop-up window. Click "Log In".
4. Click "Dashboard" at the top of the page.
5. Click "Accounts" under the sandbox menu on the left side of the page.
6. Click "Create Account".
7. Enter the required information. Click "Create Account".

To activate the PayPal sandbox account:

1. Log into your sandbox at https://developer.paypal.com.
2. Click “Accounts” under sandbox.
3. Click the arrow left of the email address of the sandbox account and click “Profile”.
4. Click “Update to Pro” next to account type.

The next step will be to log into your PayPal Manager. From the top menu, select "Service Settings". Under "Hosted Checkout Pages", select "Set Up".

Under "Choose your settings", confirm that the Transaction Process Mode is set to "Test". If you are using PayPal to collect payments now through another process, then this setting is probably set to "Live". If this is true, then there are Terra Dotta settings that we will need to change. Please let us know if this is the case.

Under "Display options on payment page", leave all URL fields blank. Set "Cancel URL Method" to "POST".

 

Under "PayPal Express Checkout", no express checkout should be added. Confirm that "Enable PayPal Credit" is set to "No".

 

Important Note: Under "Billing Information", a field is designated as required when the box to the left of the field is populated with a check mark. Any fields marked as required under "Make these fields required" must also be marked as required under "Make these fields editable". The use of these fields is up to individual clients, but there must be consistency between "Make these fields required" and "Make these fields editable". For example, if "Phone" is marked as required under "Make these fields required", then "Phone" must able be marked as required under "Make these fields editable".

 

 

Under "Shipping Information", there are usually no fields marked as required under "Mark these fields required" and "Mark these fields editable". Terra Dotta clients generally do not ship anything as part of their payment process. If any of these fields are checked intentionally, then it is likely that there is code that Terra Dotta will need to change. Please let us know if this is the case, along with which field is marked as required.

 

Under "Payment Confirmation", locate the "Show confirmation page" setting. The button to the left of "On my website" should be selected. The field for "Enter Return URL " should be left blank as Terra Dotta passes that information in our process. Select "POST" from the "Return URL Method" menu.

 

 

Under "Silent Post for Data Transfer", confirm that "Use Silent Post" is set to "No".

 

Under "Security options" at the bottom of the page, confirm that "Enable Security Token" is set to "Yes".

 

 

Self-Service Setup 

After your PayPal 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" PayPal account settings (i.e. PayPal Merchant Login Name, Token URL, Gateway URL, Merchant User, Merchant Password, Key, and Merchant Partner) 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) Configure PayPal Settings

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

• Navigate to Settings > TD Connect > PayPal . Click on the cogwheel icon to open the PayPal modal.
• Check the box next to "Activate" to enable the PayPal 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 PayPal Merchant Login Name, Token URL, Gateway URL, Merchant User, Merchant Password, Key, Merchant Partner, and Pay Now Text, you will receive an error message.

The modal fields available for editing are as follows:

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

Merchant Login Name: This is the Merchant Login Name for the client used to access the client's PayPal Account.

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

Gateway URL: Enter the URL provided by PayPal . This key will be a URL specific to your production site and should not be changed.

Merchant User: This is the Merchant User for the client used to access the client's PayPal account.

Merchant Password: This is the Merchant Password for the client used to access the client's PayPal account.

Key: Enter the key provided by PayPal . This will be a key specific to your production site and should not be changed.

Merchant Partner: This is the Merchant Bank Processor for the client's PayPal account.

Merchant Comment:

• Choose to hardcode a value (i.e. store a fixed, default value) for the Merchant Comment to be used for all payments across the entire site. Or,
• Select one of the following options that would be used for transactions for the Merchant Comment:
  • Applicant Parameter
  • Program Name-Term-Year

Important Note: 

• Applicant parameters should be created before setting up the Merchant Comment. 
• Clients will have a different "test" PayPal Merchant Login Name, Token URL, Gateway URL, Merchant User, Merchant Password, Key, and Merchant Partner when connecting to a sandbox site (i.e. test environment) versus to a production site. The same interface will appear as described above.

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 PayPal 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 1) 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 2) Admins can select a program parameter to determine the Material Amount. This sets the value for the Material Amount. (Program parameters should be created before setting up the material.)

Example:

An admin creates a program parameter for the application fee amount. When creating a new payment material for an application fee, the admin would not enter a hard-coded value but would instead choose the application fee amount from the corresponding parameter amount 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:

• 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

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 PayPal 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 PayPal 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 in the "Payments" tab:

• Title: This displays the name of the payment material.
• Current Amount: This is the current amount set for this material.
• 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

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

Payment information is available to be queried and reported on through Terra Dotta's Analytics solution. More information regarding how to build an Analytics query and report can be found in the Analytics for Terra Dotta Study Abroad article. When using Analytics to review payment information, reference the field data points under the category of "Payment Tracking Information".