Blog

Where we discuss our work, thoughts, and process

Accept campaign donations with the NGP contribution API

Screenshot of the NGP login page

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

Comments

Aaron Hunter's avatar
Aaron Hunter
Nice work, as always!

Would this vary in any substantial way for an email signup or volunteer form?
Josh Lockhart's avatar
Josh Lockhart NMC team member
@Aaron The donation API and volunteer sign up API are similar but use different endpoints and slightly different XML request schemas. We actually have a separate PHP class we created specifically for Volunteer sign ups. We'll be posting that in a separate blog post later this week.

Thanks!
Josh
John Donoso's avatar
John Donoso
Excellent and very useful work writing up a PHP interface for this! Your Salsa post is interesting too, actually =) However, I'm very curious about that separate blog post you were talking about - would love to see a similar interface for the Volunteer signup API!

Absolutely all the best -
ian johnson's avatar
ian johnson
thank you! thanks for posting this, it's a real timesaver. I've integrated this with the wordpress gravity forms plugin if anyone wants a lead on that.
Peter Martin's avatar
Peter Martin
Ian - I'd love to hear more about the Gravity Forms integration, can you send along? Thanks!
Ben's avatar
Ben NMC team member
Thanks for the information. I'm also working on integrating an email/signup form with the NGP api. Do you have any examples of that and/or could you pass along information about how to hook this up with the gravity forms wordpress plugin. That would be so helpful. The documentation does seem lacking...
Chris Baily's avatar
Chris Baily
Did you ever get a chance to post the email sign up class you referred to?
Greg Hauenstein's avatar
Greg Hauenstein
When I fill out the form and hit "submit" the form just resets and no donation is made.

What could be causing this to happen?
Sean Robertson's avatar
Sean Robertson
FWIW, I did most of the work on the CRMNGP Drupal module which provides integration with this same API as well as the COO API (allowing integration with a variety of Drupal modules to pull contact info into COO). You can find that here:

http://drupal.org/project/crmngp

It is a fairly complex API and documentation is definitely an issue, but you might find some useful information in that source code. I'd also started working on a standalone PHP class for it along similar lines to what was done here, but hadn't been able to devote the time towards getting it finished before I left NGP.
Michael Spitzer-Rubenstein's avatar
Michael Spitzer-Rubenstein
Hi, I came across this blog post and did you ever release the documentation for email signups?

Michael

Leave a comment

Real Time Web Analytics