Taking Digital Payments on UBC CMS

The way you take credit or debit card payments on your CMS site is changing.

UBC CMS Team’s Goals with DPP Integration

In short, for version 1, the CMS team is aiming for feature parity between the old ePayment plugin and the new DPP plugin. We’ve built a robust, more easy-to-maintain plugin that deeply integrates with Gravity Forms. This approach has allowed us to create a plugin that feels native to WordPress for site administrators, and provides a seamless payment path for your site’s visitors.

Version 2 of the plugin, which we will work on once all existing CMS ePayment sites are transitioned to use the new DPP plugin, will add the ability to provide multiple payment overrides (meaning you can split up the payment amount between different accounts) and the ability to make content on your site visible to only those who have successfully completed payment on a particular form (which will be an integration with the Content Visibility suite of plugins).

Taking Digital Payments on UBC CMS

The documentation is split into two sections:

1. The first is for sites that are new to taking payments on their CMS website and
2. the second is for sites that need to migrate from the old UBC ePayment system to the new Digital Payments Processing system.

Below this documentation is a section for frequently asked questions about taking payments on sites on CMS.

---

Taking payments on new sites or websites that have never used ePayments before on CMS

Taking Digital Payments through UBC’s approved payments processor on sites on CMS is done through creating 1 or more web forms on your website that contains a product field. This is done using the Gravity Forms plugin and a custom add-on to Gravity Forms that the UBC CMS team has written.

Gravity Forms is an incredibly powerful plugin that you can use for lots of purposes, but for this documentation we will concentrate on how to use it to collect digital payments. To find out more about what you can do with Gravity Forms read the documentation provided by Rocket Genius (the plugin’s author).

Before you can start collecting payments on your UBC CMS website, 2 things need to happen.

1. You have got in touch with us to have the DPP Plugin activated on your CMS Website
2. You have been through the onboarding with the UBC IT Digital Payment Program team for uPay.

Onboarding Details

After you have got in touch and we have activated the new DPP Plugin for you, from the dashboard of your CMS site you can navigate to Forms > Settings > Digital Payments (See Fig. 1 below). There you will be greeted with the details that you will need in order to fill out the onboarding spreadsheet required by the UBC IT DPP Team. Please ensure that you choose to send an email receipt to anyone paying for items on your site. This email comes from the payment merchant and will be the official receipt that the payee can use to prove they have successfully paid for an item from your site.

Note If you have used the old ePayments plugin on CMS then this settings screen is in a different location to the old plugin. This helps us differentiate it from the old plugin as well as help make this feel more integrated into gravity forms.

These 6 URLs are required by the UBC IT DPP team in order to onboard you. They have the same names in the spreadsheet that they will ask you to complete. You can copy and paste them from this screen into the spreadsheet. It is absolutely vital that you get these URLs correct in the spreadsheet so please double check them before you send it to the UBC IT DPP Team.

After you send the spreadsheet to the UBC IT DPP Team they will complete your onboarding and in doing so they will create a uPay site for you. Once that’s done they will send you credentials and keys for a testing environment. Continue with this documentation with these testing credentials. Once you have completed testing, you can inform the DPP Team and they will send you production credentials. These credentials are important and it is imperative you keep them private.

Site-wide settings

Now that you have the credentials, you can toggle the ‘On-boarding complete’ toggle (See Fig. 1 above) and press Save Settings. This will now present you with your site-wide settings for both the testing and production environments.

These 8 boxes (see Fig. 2 above) – 4 for the testing environment and 4 for the production environment – are very important. You will not be able to accept payments on your site without filling in these details correctly.

The testing environment is exactly that – it will allow you to test your payments without spending any actual money using fake credit cards. The production environment will be what you use when you’re ready to accept real payments. We’ll explain how you can switch between these environments later when we set up a form, but for now, fill in these 8 boxes with the details given to you by the DPP Team.

These settings apply to all of your Digital Payment forms and you only need to input them once.

Once you have filled in each of the boxes, press Save Settings. You should see green ticks – one next to each field you just completed. You are now ready to create your first form for Digital Payments.

Creating a form to collect Digital Payments

In order to collect digital payments on your site 3 things need to happen.

1. You create a form which contains a product field with a non-zero price
2. You assign that form to be a Digital Payments Form in the form’s settings
3. You embed that form onto a page on your CMS website

If you have no familiarity with Gravity Forms, we highly recommend you read through the Getting started Guides on the Gravity Forms Documentation site. We’ll be creating a very simple form that collects some arbitrary information – in this case the person’s Name – and allowing them to purchase one or more of 2 different ‘products’ that you are ‘selling’.

In the UBC Context rarely will you be using this like a regular eCommerce store (although you absolutely could) where you are ‘selling’ products. Rather, you’re likely taking payment for an event, or some official university business. However, it’s useful — and perhaps easier — to think of the two things as analogous. The payment for attendance to an event (for example) is the same as you selling a ticket (product) to that event.

Visit Forms > New Form and give the form a name and an optional description. When done, press the Create Form button. See Fig. 3 below.

You now have an empty form into which you are able to add fields. For this example we’re going to add a single line text field for the person’s name, and two product fields. Product fields are under the ‘Pricing Fields’ dropdown in the ‘Add Fields’ tab on the right hand side. (and a Text field is under the first, default-to-open ‘Normal Fields’ dropdown)

Click Single Line Text in the sidebar on the right. This will add the field to your form. It will say ‘untitled’. Click the newly added field and the sidebar on the right will switch to the Field Settings tab for this field. Change the field label – in this case to ‘Your Name’.

Now switch back to the Add Fields tab in the sidebar on the right and towards the bottom you will see ‘Pricing Fields’. Click the down arrow next to that to open up the accordion which lists all of the pricing fields available to you.

Click Product to add your first product field to the form. There are several types of product field, but for this example we’ll leave the default which is ‘single product’. To see the different product fields and how to use them, see the Gravity Forms Product Field documentation.

Click the newly added product field to see its settings. Give the field a label and choose a price. Optionally, add a description.

Now repeat the process for a second product (or, if you’re looking for a super minimal example, skip this step).

Optionally, but recommended for a better user experience, you can add a Total field (Total Field Documentation). This will automatically calculate the total value of all of the products that a user will pay for.

Press Save Form towards the top right.

Your form should now look similar to Fig.4 above.

Setting up a form for Digital Payments

Now hover over ‘Settings’ at the top of the screen (slightly left of centre, next to ‘Entries’) and then click Digital Payments (See Fig 5. below).

This takes you to the digital payments settings page for this particular form. See Fig. 6 below.

If you are ready to test (or fully deploy) this form as a Digital Payments Form then click the toggle to Enable Digital Payments and then select the Payment Environment you wish to use. The test environment will allow you to test for form to ensure everything works as expected using dummy credit cards. No money will change hands on the test environment. Once you are ready to fully deploy this form come back to this screen and switch to use the Production environment.

As of version one of this plugin you have the ability to have one workday override. This provides the same functionality as the old CBM plugin. In the future, you will have the ability to provide multiple workday overrides allowing you to split the payment between different funds. As with Fig. 7 below, you will need to enter Ledger Account ID, Revenue Category ID, Fund ID, Function ID, and the Cost Centre ID. Additionally, optionally, you can include a Program ID or Project ID.

Adding your Digital Payments Form to a Page on your website

Now we need to make this form available for people to fill in on your website. We do that by embedding this form on a page (or post). Visit Pages > Add New to add a new page (or you can edit an existing page on your site should you wish).

There’s 2 ways to add a form to a page – using the Gravity Form block or using a shortcode. We’re going to show you how to use the block here as that is the preferred method (as it means you’re using the Block Editor which will be better for you in the long run; something we wish to encourage).

Press the plus button in the top left or, into a new paragraph block, type /form and click the Gravity Forms block. See Fig. 8 below.

Now select the form we just created from the dropdown and a representation of the form will be shown in the editor (see Fig. 9 below). Under the ‘Advanced’ tab for the Gravity Forms block, ensure that the AJAX toggle is off (this is the default).

Press Publish (or Update if you’re adding this form to an already-published page) and your Digital Payments Form will be live to the world.

Alternatively, if you don’t wish to (or can’t, as your site isn’t using the Block Editor yet) use the Block, for details on the Gravity Forms shortcode, please read the official documentation on the shortcode.

What it looks like for your end users

Once you have your form live, you can advertise it to your users. When someone visits your form’s page and chooses an item to buy they will be redirected to TouchNet to pay. It’s a 3-step process for your users; 1) Enter details including credit card info and address etc. 2) Verify the details they have entered and pay. 3) View receipt.

Your users can then either close the browser window or they can continue which will redirect them back to your site and the rules you have set in the form’s confirmation settings will apply such as a redirect to a specific page or show a message on the screen. The user will also receive an email from TouchNet (as you must set this up during the onboarding) which will act as their official receipt for the transaction.

For each transaction, Gravity Forms creates an entry in the dashboard. Visit Forms > Entries and select the appropriate form, and you will see a list of payments along with their payment status, the environment the payment was made on (Test or Production), the Payment Amount, and the Payment Request Number. See Fig. 11 below.

---

Changing a CMS site from the old ePayments (CBM) service to the new Digital Payments service

If you have existing forms that use the old CBM ePayments plugin, the process is similar to the above documentation on starting from scratch. You will still need to go through onboarding with the DPP Team, and you will still need need to set up the site-wide settings on your existing site. Please go through 4.1.1 (onboarding) and 4.1.2 (site-wide settings) above before continuing.

Next, the good news: Your forms themselves do not need to change.

There is no bad news.

The only additional piece of work you will need to do is 4.1.4 (setting up a form for digital payments) above which will enable your form to use the new DPP plugin as well as choosing the environment (test or production). You will need to do this for each form you have on your site that currently uses CBM ePayments that you now wish to move to use Digital Payments.

You can have the old CBM ePayments plugin running at the same time as the new Digital Payments Plugin. However, when both plugins are active at the same time, you will only be able to use the Testing environment on the new Digital Payments environment. When you are ready to switch all of your forms from CBM to DPP, please deactivate the old plugin (from Dashboard > Plugins, see Fig. 12 below). The old plugin — the one you need to disable — is named UBC e-Payment version 0.8.7.

Once you have deactivated the old plugin, you will be able to select the Production environment under the Digital Payment settings for each form.

---

Frequently Asked Questions

If the documentation above doesn’t answer your questions, here’s answers some questions we commonly hear about taking payments on your CMS website.