Express Donations

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.org. 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.org. We're always happy to assist you.