Embedding Online Giving

February 25th 2016 Online Giving

The following document outlines how to embed your Online Giving website directly into a church website. Our embed feature is included free of charge with every account. Using embedded giving you can seamlessly display any of the Online Giving pages as part of your website. However, for most churches we recommend simply direct linking to your Online Giving website. Direct linking is the quickest method of linking your church website to Online Giving. Direct linking also eliminates the need for your church website to maintain a SSL Certificate for embedded pages and removes any risk involved with man-in-the-middle attacks.


Embed Document Sections


Getting Started

  • The Online Giving embed API requires an Online Giving account. If you have not already signed up, please visit our sign-up page to get started today.
  • Got a question or issue? Drop us a line at support@onlinegiving.cc. We shall be happy to guide you with the embed process.

Prerequisites

  • Active Account - If you have not already signed up for Online Giving, please visit our sign-up page to get started today.
  • Church Code - Your church code is the same as your church sub-domain. For example in https://mychurch.onlinegiving.cc the "mychurch" sub-domain is the church code.
  • Basic HTML Skills - Embedding anything on the internet requires very basic knowledge of HTML. If you are having trouble please do not hesitate to contact us.

SSL/TLS and Online Giving

SSL (Secure Sockets Layer) and TLS (Transport Layer Security) are used for encrypting website communication from a web browser using HTTPS (Hypertext Transfer Protocol Secure). Online Giving uses HTTPS on all pages without the option to use HTTP. Meaning, the end user that reaches an Online Giving page will be on a HTTPS connection.

Do I need to use a SSL/TLS (HTTPS) on my embedded payment pages?

YES, any page that contains the Online Giving embed code will need to be accessed by the donor from a SSL/TLD secured page. Meaning, your church website will need to install and use a SSL certificate before using Online Giving's embed option for a couple of reasons:
  • It's more secure. Having a SSL/TLS (HTTPS) embed page reduces the risk of being exposed to a man-in-the-middle attack.
  • Most donors will check the parent website address bar for a green icon and HTTPS to feel secure.

Authentication

Using the embed option Online Giving will still require a donor to be authenticated before reaching any internal pages such as profile, donate or recurring giving. To allow public donations without login you may use our donate as guest page.

Are you a Ministry Platform church?
Great news, we've integrated directly with Ministry Platform. Ministry Platform churches may bypass the Online Giving login pages when linking in embed method 1 below. Please click here for a how to video for embedding with the MP Portal

Are you looking to skip the Online Giving sign-in and registration pages?
If you are a Ministry Platform church please see the section above. For others we currently require the Online Giving lock screen except for the donate as guest page. However, stay tuned as we're working hard on an authentication API that you may integrate against for the near future. Need it sooner? Drop us a line at support@onlinegiving.cc.

Online Giving Embed Code


The Embed Code

Embed Code Attributes

  • src - Required. Set to https://www.onlinegiving.org/assets/embed.js
  • data-id - Required. Set to og-embed-script
  • data-church-code - Required. Set to your church code. Your church code is the sub-domain of your giving website. For TLD .org domains please append _org after sub-domain (e.g. subdomain_org).
  • data-default-page - Optional. When blank details to donation form page. Otherwise see valid pages below:
    • Valid Page Values:
    • /donate/index - Donation form page.
    • /donate/profile - Donation profile page.
    • /donate/textgiving - Donation text giving page.
    • /donate/history - Donation history page.
    • /donate/recurring - Donation recurring page.
    • /donate/guest_donate - Donation as guest page.
    • /donate/form/:id - Custom Giving Page.
    • /donate/customform/:id - Custom Form Page.
    • /donate/sermonnotes/:id - Sermon Notes Page.
  • data-token-type - Optional. Set to mp-token for Ministry Platform Portal embedding only.
  • data-mp-token - Optional. Set to [MPP_User_Data] for Ministry Platform Portal embedding only.
  • data-container-id - Optional. Set to CSS selector of desired HTML element. For use when it's desirable to place embed tag in main template.
  • data-bg-color - Optional. Set to hex color code to change background color of Online Giving page.

Embed Code Playground

For your convenience included below is the embed code playground. You may also click here to edit the code on the playground.

See the Pen JGQQLY by Online Giving (@onlinegiving) on CodePen.

Using the Online Giving Embed Code


Overview

When using the embed code there are two methods of implementation which are defined below. The main difference in the methods below is method 2 will allow you to create custom pages URLs vs supplying the Online Giving page as a GET param in a link.

Embed Method 1

The first method of embedding online giving is to have a dedicated page on your website with the embed code and then simply link to that page with the Online Giving a special GET param that will inform the embed code which page to load. Using this method you only need to create one new page and then link to that page.

Step 1 - Create New Page With Embed Code
  1. Create new web page for embed code using your website CMS or template.
  2. Copy and paste the embed code below into the new page body and change data-church-code attribute to your church code.
Step 2 - Link to New Page
  1. Get the URL to the page created in Step 1 above.
  2. Update website navigation or other with links to embed page. Example links are provided below:

Embed Method 2

The second method of embedding online giving is to have a dedicated page on your website for each online giving page you which to embed. Then link to those pages from your website. The goal of this method is to allow the website owner more control of the donation link since each donation page will have it's own page and embed code.

Step 1 - Create New Page With Embed Code
  1. Create new web page for embed code using your website CMS or template.
  2. Copy and paste the embed code below into the new page body:
    • Change data-church-code attribute to your church code.
    • Change data-page-default attribute to one of the allowed page values.
  3. Repeat steps 1 and 2 above for each online giving page you would like to embed.
Step 2 - Link to New Pages
  1. Get the URLs to the pages created in Step 1 above.
  2. Update website navigation or other with links to embed page.

How to cancel embed session for direct linking on embed page

A scenario exists where you may wish to have a link directly to your church giving website and embed link on the same page. Perhaps you would like to embed guest giving on a page with a link to sign-in above. It's important to note that embedded giving creates an embed session that will follow the donor. In order to link out to your giving website once a donor has reached an embedded giving page you must add "embed=n" as a GET paramiter to your giving website link. The "embed=n" GET param will inform your giving website to cancel the embed session and display the default header/footer and social sign-in features. In the event you have embedded giving on your church website you may wish to include this optional GET param on all outbound links to your Online Giving website.

Example: https://yourchurch.onlinegiving.org/donate?embed=n