Accept campaign donations with the NGP contribution API

UPDATE: This article is a follow-up to an earlier article on our blog about the NGP contribution API written by Eli Van Zoeren. We have since updated the code we use to integrate with NGP's contribution API. Our newest code is explained in this article.

New Media Campaigns works with many political clients that use the robust NGP fundraising and contact management platform. Unfortunately, the NGP donation API has proven a tough nut to crack due to sparse documentation. However, we’ve written a PHP class that makes it super easy to integrate with the NGP donation API so you can avoid the hassle and start accepting political campaign donations right away.

Using the NgpDonation class

The NGP donation API exposes a SOAP web service that consumes an XML request and returns an XML response. Our NgpDonation PHP class provides a human-friendly wrapper around the NGP SOAP API. Accepting contributions with the NGP donation API has never been easier.

Require the NgpDonation class

First, require the NgpDonation PHP class into your PHP script:

require 'NgpDonation.php';

Instantiate the NgpDonation class

Next, create an instance of NgpDonation. The class constructor accepts three arguments:

1. Your API credentials string provided by NGP.

2. A true or false value that will send or not send email notifications to the donor upon receipt.

3. An associative array of donation fields (see full list).

   $d = new NgpDonation('your-credentials', true, array(
       'FirstName' => 'John',
       'LastName' => 'Doe',
       'Address1' => '100 Elm Street',
       'Zip' => '12345',
       'Cycle' => '2012',
       'Amount' => '50.00',
       'CreditCardNumber' => '4111111111111111',
       'ExpYear' => '13',
       'ExpMonth' => '05'
   ));

The NGP API requires that you provide at least these fields (case-sensitive) to collect a donation:

• FirstName
• LastName
• Address1
• Zip
• Cycle
• Amount
• CreditCardNumber
• ExpYear
• ExpMonth

A list of all donation fields and field descriptions is available below.

Process Donation

Finally, accept and process the donation like this:

$result = $d->save();

The $result variable will be a boolean value indicating success or failure. If $result is false, you should inspect the NgpDonation instance for reasons why the donation failed.

Error Handling

Missing Fields or Transaction Errors

If you were unable to accept a donation, you may be missing required fields or the credit card may have been declined. Check for errors like this:

if ( $d->hasErrors() ) {
    $errors = $d->getErrors();
}

The $errors variable will be a one-dimensional array of error messages. Usually, this array will indicate that several required fields are empty or missing.

SOAP Fault

There may also be an error with the SOAP API itself. In this scenario, a SoapFault exception will be thrown and caught by your NgpDonation instance. You can check for and inspect the SoapFault exception like this:

if ( $d->hasFault() ) {
    $fault = $d->getFault();
}

In this example, $fault will be an instance of SoapFault that you may inspect as needed.

Inspect the API response

If all else fails, you can inspect the XML response from the NGP API with the NgpDonation instance’s getResult() method. This will return a SimpleXMLElement object.

$result = $d->getResult();
var_dump($result);

Example

HTML Form

<form action="" method="post" accept-charset="utf-8">
    <p>
        <label for="FirstName">First Name</label>
        <input type="text" 
                  id="FirstName"
                  name="donation[FirstName]"
                  value=""
                  required/>
    </p>
    <p>
        <label for="LastName">Last Name</label>
        <input type="text" 
                  id="LastName"
                  name="donation[LastName]"
                  value=""
                  required/>
    </p>
    <p>
        <label for="Address1">Address</label>
        <input type="text"
                  id="Address1"
                  name="donation[Address1]"
                  value=""
                  required/>
    </p>
    <p>
        <label for="Zip">Zip Code</label>
        <input type="text"
                  id="Zip"
                  name="donation[Zip]"
                  value=""
                  required/>
    </p>
    <p>
        <label>Amount</label>
        <input type="radio" 
                  name="donation[Amount]"
                  value="100"/> $100<br/>
        <input type="radio"
                  name="donation[Amount]"
                  value="500"/> $500<br/>
        <input type="radio"
                  name="donation[Amount]"
                  value="1000"/> $1000
    </p>
    <p>
        <label for="CreditCardNumber">Credit Card Number</label>
        <input type="text"
                  id="CreditCardNumber"
                  name="donation[CreditCardNumber]"
                  value=""
                  required/>
    </p>
    <p>
        <label>Credit Card Expiration</label>
        <select name="donation[ExpMonth]" required>
            <option value="01">01 - January</option>
            <option value="02">02 - February</option>
            <option value="03">03 - March</option>
            <option value="04">04 - April</option>
            <option value="05">05 - May</option>
            <option value="06">06 - June</option>
            <option value="07">07 - July</option>
            <option value="08">08 - August</option>
            <option value="09">09 - September</option>
            <option value="10">10 - October</option>
            <option value="11">11 - November</option>
            <option value="12">12 - December</option>
        </select>
        <select name="donation[ExpYear]" required>
            <option value="12">2012</option>
            <option value="13">2013</option>
            <option value="14">2014</option>
        </select>
    </p>
    <p>
        <input type="hidden" name="donation[Cycle]" value="2012"/>
        <input type="submit" value="Donate Now"/>
    </p>
</form>

PHP Script

<?php
require 'NgpDonation.php';
$donation = new NgpDonation('credentials', true, $_POST['donation']);
if ( $donation->save() ) {
    echo "Thank you for your donation!";
} else {
    if ( $donation->hasErrors() ) {
        $errors = $donation->getErrors();
        //Show errors to user
    } else if ($donation->hasFault() ) {
        $fault = $donation->getFault();
        //Log SoapFault for review
    } else {
        $result = $donation->getResult();
        //Log API response for review
    }
}
?>

NGP Donation Fields

This is a comprehensive list of all possible donation fields you may use to accept donations with NGP’s API. Required fields are shown in red.

Contributor Fields

LastName

String. The last name of the donor

FirstName

String. The first name of the donor

MiddleName

String. The middle name of the donor

Prefix

String. A prefix for the donor’s name (e.g. “Mrs.”)

Suffix

String. A suffix for the donor’s name (e.g “Ph.D”)

Address1

String. The donor’s street address

Address2

String. The donor’s street address continued

Address3

String. The donor’s street address continued

City

String. The donor’s city

State

String. The two-letter abbreviation of the donor’s state or region

Zip

String. The donor’s five-digit zip code

Salutation

String. The donor’s salutation

Email

String. The donor’s email address

HomePhone

String. The donor’s home phone number

WorkPhone

String. The donor’s work phone number

WorkExtension

String. The donor’s work phone number extension

FaxPhone

String. The donor’s fax number

Employer

String. The donor’s employer name

Occupation

String. The donor’s occupation

OptIn

Boolean. Should this donor receive future emails about the fundraising campaign?

Organization

String. The donor’s organization

Contribution Fields

Cycle

String. The fundraising campaign’s year cycle (e.g. “2012”)

Member

String.

Attribution

String.

Source

String.

RecurringContrib

Boolean. Will this be a recurring contribution?

RecurringContribNote

String. A note about this recurring contribution

Amount

Float. The amount of the contribution

Attend

String.

RecurringPeriod

String. The frequency on which total recurring contributions will be processed. Options are: MONT, WEEK, BIWK, FRWK, QTER, SMYR, YEAR

RecurringTerm

Integer. The total number of recurring donations

Payment Fields

CreditCardNumber

String. The donor’s credit card number

ExpYear

String. The donor’s two-digit credit card expiration year

ExpMonth

String. The donor’s two-digit credit card expiration month

CVV

String. The donor’s credit card number security code

Download

Our `NgpDonation` class is released under the MIT Public License.

Download the NgpDonation class