NFG Client

A client to interact with the NFG (Network for Good) API via SOAP requests.

Installation

Install the gem:

gem install nfg-client

Or add it to your Gemfile:

gem "nfg-client"

Usage

Create a NFG Client instance using your NFG credentials:

nfg_client = NFGClient.new(partner_id, partner_password, partner_source, partner_campaign, use_sandbox)

The fifth parameter is optional (defaults to false), and indicates the Client which API URLs to use (sandbox or production).

Use the Client to make calls to the NFG API, each call will take a hash with the parameters you want to send along with it (apart from the NFG credentials).

Example:

nfg_client.get_donor_cofs({"DonorToken" => donor_token})

All required parameters for the different calls should have the name specified by the NFG documentation.

For more information, refer to the official NFG documentation:

http://www.thenetworkforgood.org/t5/Developer-Resource-Center/ct-p/Developer

Supported Calls

Below, the list of supported calls and examples of usage. All functions return a hash with the response from NFG.

CreateCOF

Creates a Card on File without a transaction.

Call

response = nfg_client.create_cof({
    "DonorToken" => "",
    "DonorFirstName" => "",
    "DonorLastName" => "",
    "DonorEmail" => "",
    "DonorAddress1" => "",
    "DonorAddress2" => "",
    "DonorCity" => "",
    "DonorState" => "",
    "DonorZip" => "",
    "DonorCountry" => "",
    "DonorPhone" => "",
    "CardType" => "", # Unk, Visa, Mastercard, Amex or Discover
    "NameOnCard" => "",
    "CardNumber" => "",
    "ExpMonth" => "",
    "ExpYear" => "",
    "CSC" => ""
})

Response on Success

{
    "StatusCode" => "Success", 
    "Message" => "", # Empty
    "ErrorDetails" => "", # Empty
    "CallDuration" => "x.x", 
    "DonorToken" => "x", 
    "COFId" => "x" # Integer
}

GetDonorCOFs

Gets a list of donor Cards on File.

Call

response = nfg_client.get_donor_cofs({
    "DonorToken" => ""
})

Response on Success

{
    "StatusCode" => "Success", 
    "Message" => "", # Empty
    "ErrorDetails" => "", # Empty
    "CallDuration" => "x.x", 
    "DonorToken" => "x", 
    "Cards" => [
        {
            "COFId" => "x", # Integer 
            "CardType" => "x", # e.g. Mastercard 
            "CCSuffix" => "xxxx", # Last four digits 
            "CCExpMonth" => "", # 1 or 2 digits 
            "CCExpYear" => "", # 4 digits
            "bInUseByLiveRD" => "", # true or false 
            "COFEmailAddress" => ""
        },
        ...
    ]
}

DeleteDonorCOF

Removes an existing Card on File.

Call

response = nfg_client.delete_donor_cof({
    "DonorToken" => "",
    "COFId" => ""
})

Response on Success

{
    "StatusCode" => "Success", 
    "Message" => "", # Empty
    "ErrorDetails" => "", # Empty
    "CallDuration" => "x.xx"
}

MakeCOFDonation

Triggers a one-time or recurring donation to one or more charities with an existing Card on File.

Call

response = nfg_client.make_cof_donation({
    "DonationLineItems" => {
        "DonationItem1" => {
            "NpoEin" => "",
            "donorVis" => "", # ProvideAll, ProvideNameAndEmailOnly or Anonymous
            "ItemAmount" => "",
            "RecurType" => "", # NotRecurring, Monthly, Quarterly or Annually
            "Designation" => ""
            "Dedication" => ""
        },
        "DonationItem2" => {
            ...
        },
        ...
    },
    "TotalAmount" => "",
    "TipAmount" => "",
    "DonorIpAddress" => "",
    "DonorToken" => "",
    "COFId" => ""
})

Response on Success

{
    "StatusCode" => "Success", 
    "Message" => "", # Empty
    "ErrorDetails" => "", # Empty
    "CallDuration" => "x.x", 
    "ChargeId" => "x",  # Integer
    "COFId" => "0"
}

MakeDonationAddCOF

Triggers a one-time or recurring donation to one or more charities with a new Card on File.

Call

response = nfg_client.make_donation_add_cof({
    "DonationLineItems" => {
        "DonationItem1" => {
            "NpoEin" => "",
            "donorVis" => "", # ProvideAll, ProvideNameAndEmailOnly or Anonymous
            "ItemAmount" => "",
            "RecurType" => "", # NotRecurring, Monthly, Quarterly or Annually
            "Designation" => ""
            "Dedication" => ""
        },
        "DonationItem2" => {
            ...
        },
        ...
    },
    "TotalAmount" => "",
    "TipAmount" => "",
    "DonorIpAddress" => "",
    "DonorToken" => "",
    "COFId" => "",
    "DonorFirstName" => "",
    "DonorLastName" => "",
    "DonorEmail" => "",
    "DonorAddress1" => "",
    "DonorAddress2" => "",
    "DonorCity" => "",
    "DonorState" => "",
    "DonorZip" => "",
    "DonorCountry" => "",
    "DonorPhone" => "",
    "CardType" => "", # Unk, Visa, Mastercard, Amex or Discover
    "NameOnCard" => "",
    "CardNumber" => "",
    "ExpMonth" => "",
    "ExpYear" => "",
    "CSC" => ""
})

Response on Success

{
    "StatusCode" => "Success", 
    "Message" => "", # Empty
    "ErrorDetails" => "", # Empty
    "CallDuration" => "x.x", 
    "ChargeId" => "x",  # Integer
    "COFId" => "0"
}

GetFee

Calculates the fee for a transaction that would ultimately be used with payment functions.

Call

response = nfg_client.get_fee({
    "DonationLineItems" => {
        "DonationItem1" => {
            "NpoEin" => "",
            "donorVis" => "", # ProvideAll, ProvideNameAndEmailOnly or Anonymous
            "ItemAmount" => "",
            "RecurType" => "", # NotRecurring, Monthly, Quarterly or Annually
            "Designation" => ""
            "Dedication" => ""
        },
        "DonationItem2" => {
            ...
        },
        ...
    },
    "TipAmount" => "",
    "CardType" => ""
})

Response on Success

{
    "Message" => "", # Empty
    "ErrorDetails" => "", # Empty
    "CallDuration" => "x.x", 
    "TotalChargeAmount" => "x.x", 
    "TotalAddFee" => "x.x", 
    "TotalDeductFee" => "x.x",
    "TipAmount" => "x.x"
 }

GetDonorDonationHistory

Gets donor transactions.

Call

response = nfg_client.get_donor_donation_history({
    "DonorToken" => ""
})

Response on Success

{
    "StatusCode" => "Success", 
    "Message" => "", # Empty
    "ErrorDetails" => "", # Empty
    "CallDuration" => "x.x", 
    "DonorToken" => "x", 
    "Donations"=>[
        {
            "DonationDate" => "xxxx-xx-xxTxx:xx:xx.xx", 
            "RecurType" => "x", # e.g. NotRecurring 
            "IsTpcAddOnFee" => "", # true or false 
            "NpoName" => "", # e.g. Smithsonian Institution 
            "Designation" => "", 
            "Dedication" => "", 
            "Amount" => "x.x", 
            "ChargeId" => "x" # Integer
        },
        ...
    ]
}

GetDonationReport

Returns a report of partner transactions during a specific period of time.

Call

response = nfg_client.get_donation_report({
    "StartDate" => "",
    "EndDate" => "",
    "DonationReportType" => "" # All, OneTime or Recurring
})

Response on Success

{
    "StatusCode" => "Success", 
    "Message" => "", # Empty
    "ErrorDetails" => "", # Empty
    "CallDuration" => "x.x", 
    "ReturnCount" => "x", 
    "ReportResults"=>[
        {
            "Source" => "x", 
            "Campaign" => "x", 
            "ChargeId" => "x", # Integer 
            "ShareWithCharity" => "x", # e.g. No Donor Info - Anonymous
            "DonorEmail" => "x", 
            "DonorFirstName" => "x",
            "DonorLastName" => "x", 
            "DonorAddress1" => "x", 
            "DonorAddress2" => "x", 
            "DonorCity" => "x", 
            "DonorState" => "x", 
            "DonorZip" => "x", 
            "DonorCountry" => "x", 
            "DonorPhone" => "x", 
            "Designation" => "", 
            "DonateInName" => "", 
            "RecurringPeriod" => "", 
            "EventDate" => "xxxx-xx-xxTxx:xx:xx.xxxZ", 
            "NpoEIN" => "x", 
            "NpoName" => "x", 
            "ChargeStatus" => "", # e.g. CS_SUCCESS 
            "ChargeAmount" => "x.x", 
            "NpoTPC" => "x.x", 
            "DonationItemAmount" => "x.x", 
            "TotalDonationAmount" => "x.x", 
            "HistoryRecordId" => "x"
        },
        ...
    ]
}

Failed calls

When a call fails (i.e. the "StatusCode" is different than "Success"), it's usually possible to find out more about the error looking at the "Message" and "ErrorDetails" fields. "Message" is a string, while "ErrorDetails" is a hash with the following format:

{
        "StatusCode" => "Other", 
        "Message" => "x",
        "ErrorDetails" => {
            "ErrorInfo"=>{
                "ErrCode" => "x", 
                "ErrData" => "x"
            }
        }
        "CallDuration" => "x.x",
        ...
}

Contributors

Special thanks to:

• Tom Hoen, for the addition of the test suite and code refactoring.

Copyright

Copyright (c) 2014 by Antonio Ruano Cuesta. See LICENSE for details.