Express Donations

May 31st 2017 Online Giving

The following document outlines how to use Express Donations on your website. Express Donations are included free of charge with every account and specifically designed for church web developers who have a need to handoff a gift with the donor to be returned back their website for further processing. An example of this might be a split form scenario where a church collects specific information, then sends the donor to complete their gift and finalizes the collected information upon return of the donor.

Please do not use Express Donations as your primary donation method on your church website. Although it's very possible to use Express Donations as your primary donation form we do not recommend it as you will be omiting valuable features such as text giving sign-up and recurring gift conversion. For primary giving please use direct linking or embedded giving. 

 


Getting Started

  • Express Donations require 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 process.

Prerequisites

  • Active Account - If you have not already signed up for Online Giving, please visit our sign-up page to get started today.
  • Basic HTML Skills  - Requires basic knowledge of HTML. If you are having trouble please do not hesitate to contact us.

Express Donations Flow 

Supported Methods

  • GET - You may supply the fields below as HTTP GET form request or link
  • POST - You may supply the fields below as HTTP POST form request

Link & Form Generator

For your convenience a link and form generator for Express Donations is located in the Online Giving Control Panel > Giving Settings > Express Donations. Below you will find a list of supported fields. These same fields are included in our link/form generator located in the control panel. We recommend taking advantage of this feature when getting started as it makes it easy to generate various types of forms.

Supported Fields

redirect_url
Required
The redirect URL to your website landing page. The donor will be redirected back to this page after payment.
redirect_label
Required
The redirect button label shown to the donor on the gift thank you page. Set this to a friendly name of your church landing page/website.
state
Optional
Optional state value that is returned in the token data to the redirect url. Max 500 characters. Can be used to pass state identifiers. For example: JSON payload, CSV Payload or similar.
amount
Optional
Optional payment amount.
description
Optional
Optional fund description to place under notes for fund.
fund
Optional
Optional fund code. When supplied donation form will display only the fund matching the code provided. You can find fund codes in your Online Giving control panel > Manage Funds.
sub_fund
Optional
Optional sub fund code. When supplied donation form will display only the sub fund matching the code provided. Primary fund code must also be supplied when using this field. You can find sub fund codes in your Online Giving control panel > Mange Funds > Sub Funds.
type
Optional
Optional gift type/frequency. When supplied donation form will preselect supplied gift type/frequency.

Supported Gift Type Values:

one-time
One Time Gift
monthly
Monthly Gift
weekly
Weekly Gift
2weeks
Every 2 Weeks Gift
quarterly
Quarterly Gift
yearly
Yearly Gift
first_name
Optional
Optional first name of donor. When supplied donation form will populate first name with this value (unless donor is signed in).
last_name
Optional
Optional last name of donor. When supplied donation form will populate last name with this value (unless donor is signed in).
email
Optional
Optional email of donor. When supplied donation form will populate email with this value (unless donor is signed in).
address
Optional
Optional street address of donor. When supplied donation form will populate street address with this value (unless donor is signed in).
administrative_area_level_2
Optional
Optional city/region of donor. When supplied donation form will populate city/region with this value (unless donor is signed in).
administrative_area_level_1
Optional
Optional state/province of donor. When supplied donation form will populate state/province with this value (unless donor is signed in).
postal_code
Optional
Optional postal code of donor. When supplied donation form will populate postal code with this value (unless donor is signed in).
country
Optional
Optional two digit country code (ISO2) of donor. When supplied donation form will preselect country matching ISO2 value (unless donor is signed in).
custom_form_id
Optional
Optional custom form id. When supplied express donations will display the associated custom form instead of the main donation.

Church Landing Page

Once a gift is successfully completed the donor is redirect to the church landing page supplied in the Express Donation request (see redirect_url above). Along with redirecting the donor, Online Giving will send a signed JSON web token containing important information about the completed donation. In the sections below we will outline the data included in the payload and how to verify the signed token.

JSON Web Token

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties. Online Giving returns a HTTP GET param named "token" that is a signed JSON web token. JSON web tokens are not designed to be encrypted. Instead they are signed based 64 encoded JSON payload and can be decoded using your Online Giving public key. Online Giving will return a token that has been signed specifically for your church. The signed aspect is important as it provides means for your church website to verify the JSON web token is authentic (not fake or spam). No post back is required as verification can be achieved by validating the signature of the JSON web token using your church public key.

Express Donations Public Key

As noted above you will need your Express Donations public key to verify the signed token returned as a HTTP GET "token" param. You can access your church public key directly in your Online Giving control panel > Giving Settings > Express Donations > Public Key.

Token Decoding

Along with your church's public key you'll need an JSON Web Token open source library to verify and decode the returned HTTP GET "token" param. Fortunately there are an amazing amount of JSON Web Token open source libraries designed specifically for this purpose. You can find a library in almost any coding language at the website JWT.io.

In the example below we use Google's firebase/php-jwt library. However, you can easily perform the following example using any of the open source libraries as noted above.

Token Payload

state
The state value provided with request.
amount
The amount of the completed donation.
transaction_id
The transaction id of the completed donation.
gateway_txn_id
The gateway transaction id of the completed donation.
status
The status of the completed donation. Will always be approved.
user_id
The Online Giving user id of the donor.
email
The email address of the donor.
address
The street address of donor.
administrative_area_level_2
The city/region of donor.
administrative_area_level_1
The state/province of donor.
postal_code
The postal code of donor.
country
The two digit country code of donor (ISO2).

Web Hook Alternative

Although we recommend using the return "token". You may also configure a JSON web hook payload to a private URL on your church website. You can set the web hook URL directly in your Online Giving control panel > Giving Settings > Web Hook.

Getting Support

Having trouble or got questions? Drop us a line at support@onlinegiving.cc. We're always happy to assist you.