Submit a Donation

tip

NOTE: You must enter sign the terms of service agreement with GlobalGiving to use this API feature. Please download, sign and email a copy of the terms of service agreement here, and return to api@globalgiving.org to enable this feature. You must certify that you will handle donor input and data in compliance with PCI-DSS standards when handling sensitive information. Mainly this means ensuring your connections are HTTPS, your servers are secure, and you never store a users creditcard information.

This operation allows a user to submit a donation request. This is a secure request as indicated by the '/secure/' element in the URL path, therefore, an access token (authentication) is required. Donations can be made by:

  1. submitting credit card information
  2. by providing a valid gift certificate number
  3. by submitting credit card information along with a gift certificate number

Since a donation can be made with either a credit card or a gift certificate, the <payment_detail> and <giftCertificate_detail> elements are both optional, however, at least one must be provided in a single donation request. Also, if there is not enough value remaining on the gift certificate to meet the donation amount, both elements are required to complete the donation successfully.

HTTP Method:

POST

Content Type:

xml, json

Accept Type:

xml, json

Path:

https://api.globalgiving.org/api/secure/givingservice/donations

Query String Parameters:

&api_key described in the API Key section, required

&api_token described in the Access Token section, required

&is_test when set to true credit card information (<creditCardNumber>, <expiryDateYear>, <expiryDateMonth>, <securityCode>) may be omitted as test data will be used and the transaction will not be processed, optional

Query String Example:

/api/secure/givingservice/donations?api_key=YOUR_API_KEY&api_token= SOME_API_TOKEN

Data Parameters:

refcode - your external identifier for this request which is returned in the response, required (maximum 100 characters)

transactionId - your unique transaction identifier for this transaction stored in our records for future reference and possible reporting, optional (maximum 100 characters)

email - required (maximum 50 characters)

twitter_username - optional (maximum 15 characters)

amount - a numeric value greater than $10 USD or £5 when donating using a GlobalGiving UK api key, required

NOTE: the minimum amount for gift certificate redemptions is $1

currencyCode - optional; defaults to "USD" (for US Dollars)

addon; - optional

amount - a numeric value greater than zero, required if addon element is provided

project;

id - the numeric identifier for an '<status>active</status>' project (projects with a '<status>retired</status>', or '<status>funded</status>' status will not accept further donations), required

noteToOrganization - optional *

signupForGGNewsletter - optional; defaults to false

signupForCharityNewsletter - optional; defaults to false

payment_detail; - optional if giftCertificate_detail is provided

firstname - required (maximum 100 characters)

lastname - required (maximum 100 characters)

address - required (maximum 50 characters)

address2 - optional (maximum 50 characters)

city - required (maximum 25 characters)

state - required (maximum 25 characters)

iso3166CountryCode - the ISO 3166 country code identifier for a specific country, required

zip - required (maximum 10 characters)

phone - optional (maximum 20 characters)

creditCardNumber - required (maximum 20 characters); optional if query parameter &is_test=true is provided

securityCode - required (maximum 10 characters); optional if query parameter &is_test=true is provided

expiryDateMonth - required (maximum 10 characters); optional if query parameter &is_test=true is provided

expiryDateYear - required (maximum 10 characters); optional if query parameter &is_test=true is provided

giftCertificate_detail; - optional if payment_detail is provided

giftCertificateNumber - required (maximum 20 characters)

HTTP POST Request paying with credit card, using cURL:

                  curl -H "Accept: application/xml" -H "Content-Type: application/xml" -d "<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
                  <donation>
                     <refcode>123456789</refcode>
                     <transactionId>abc123</transactionId>
                     <email>john.doe@hotmail.com</email>
                     <amount>25</amount>
                     <project>
                        <id>1883</id>
                     </project>
                     <signupForGGNewsletter>true</signupForGGNewsletter>
                     <signupForCharityNewsletter>true</signupForCharityNewsletter>
                     <payment_detail>
                        <firstname>John</firstname>
                        <lastname>Doe</lastname>   
                        <address>3380 Pearlman Avenue</address>
                        <address2>Suite 200</address2>
                        <city>Washington</city>
                        <state>DC</state>
                        <iso3166CountryCode>US</iso3166CountryCode>
                        <zip>20001</zip>           
                        <creditCardNumber>4111111111111111</creditCardNumber>
                        <securityCode>123</securityCode>
                        <expiryDateMonth>12</expiryDateMonth>
                        <expiryDateYear>2013</expiryDateYear>
                     </payment_detail>
                  </donation>" -X POST "https://api.globalgiving.org/api/secure/givingservice/donations?api_key=YOUR_API_KEY&api_token=SOME_API_TOKEN"

NOTE: Above request has carriage returns for readability.

XML Response:

            
                  <?xml version="1.0" encoding="utf-8" standalone="yes"?>
                  <donation>
                     <amount>25.00</amount>
                     <chargedAmount>25.00</chargedAmount>
                     <currencyCode>USD</currencyCode>
                     <datetime>2008-08-21T18:26:22.717-07:00</datetime>
                     <email>john.doe@hotmail.com</email>
                     <project>
                        <funding>5897.47</funding>
                        <goal>62500</goal>
                        <id>1883</id>
                        <numberOfDonations>75</numberOfDonations>
                        <progressReportLink>http://www.globalgiving.org/pr/1900/proj1883a.html#progressReports</progressReportLink>
                        <projectLink>http://www.globalgiving.org/pr/1900/proj1883a.html</progressReportLink>
                        <remaining>56602.53</remaining>
                     </project>
                     <signupForCharityNewsletter>true</signupForCharityNewsletter>
                     <signupForGGNewsletter>true</signupForGGNewsletter>
                     <refcode>123456789</refcode>
                     <transactionId>abc123</transactionId>
                     <checkedOut>true</checkedOut>
                     <payment_detail>
                        <firstname>John</firstname>
                        <lastname>Doe</lastname>
                        <address>3380 Pearlman Avenue</address>
                        <address2>Suite 200</address2>
                        <city>Washington</city>
                        <state>DC</state>
                        <iso3166CountryCode>US</iso3166CountryCode>
                        <zip>20001</zip>
                        <creditCardNumber>4111-XXXX-XXXX-1111</creditCardNumber>
                        <securityCode>123</securityCode>
                        <expiryDateMonth>12</expiryDateMonth>
                        <expiryDateYear>2013</expiryDateYear>
                     </payment_detail>
                     <receipt>
                        <currencyCode>USD</currencyCode>
                        <receiptNumber>R39339-GC138918-CBcb01</receiptNumber>
                        <taxDeductibleContributionAmount>25.00</taxDeductibleContributionAmount>
                        <totalAmountBilled>25.00</totalAmountBilled>                        
                     </receipt>
                  </donation>

NOTE: If successful, response contains <receipt><receiptNumber>, <checkedOut>, and <datetime> elements.

HTTP POST Request paying with a gift certificate, using cURL:

                  curl -H "Accept: application/xml" -H "Content-Type: application/xml" -d "<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
                  <donation>
                     <refcode>123456789</refcode>
                     <transactionId>abc123</transactionId>
                     <email>john.doe@hotmail.com</email>
                     <amount>25</amount>
                     <currencyCode>USD</currencyCode>
                     <project>
                        <id>1883</id>
                     </project>
                     <signupForGGNewsletter>true</signupForGGNewsletter>
                     <signupForCharityNewsletter>true</signupForCharityNewsletter>
                     <giftCertificate_detail>
                        <giftCertificateNumber>GL9JU52QT759</giftCertificateNumber>
                     </giftCertificate_detail>
                  </donation>" -X POST "https://api.globalgiving.org/api/secure/givingservice/donations?api_key=YOUR_API_KEY&api_token=SOME_API_TOKEN"

NOTE: Above request has carriage returns for readability.

XML Response:

            
                  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
                  <donation>
                     <amount>25.00</amount>
                     <chargedAmount>0.00</chargedAmount>
                     <currencyCode>USD</currencyCode>
                     <datetime>2008-08-21T18:26:22.717-07:00</datetime>
                     <email>john.doe@hotmail.com</email>
                     <project>
                        <funding>5897.47</funding>
                        <goal>62500</goal>
                        <id>1883</id>
                        <numberOfDonations>75</numberOfDonations>
                        <progressReportLink>http://www.globalgiving.org/pr/1900/proj1883a.html#progressReports</progressReportLink>
                        <projectLink>http://www.globalgiving.org/pr/1900/proj1883a.html</progressReportLink>
                        <remaining>56602.53</remaining>
                     </project>
                     <signupForCharityNewsletter>true</signupForCharityNewsletter>
                     <signupForGGNewsletter>true</signupForGGNewsletter>
                     <refcode>123456789</refcode>
                     <transactionId>abc123</transactionId>
                     <checkedOut>true</checkedOut>
                     <giftCertificate_detail>
                        <currencyCode>USD</currencyCode>
                        <giftCertificateNumber>GL9JU52QT759</giftCertificateNumber>
                        <redeemedAmount>25.00</redeemedAmount>
                        <remainingAmount>20.00</remainingAmount>
                     </giftCertificate_detail>
                     <receipt>
                        <receiptNumber>R39339-GC138918-CBcb01</receiptNumber>
                        <taxDeductibleContributionAmount>0.00</taxDeductibleContributionAmount>
                        <totalAmountBilled>0.00</totalAmountBilled>
                     </receipt>   
                  </donation>

NOTE: If successful, response contains <receipt><receiptNumber>, <checkedOut>, and <datetime> elements.

Submit a Donation Request Structure

donation
refcode string
transactionId string
email string
twitter_username string
amount decimal
addon
amount decimal
currencyCode string
project
id int
noteToOrganization string
signupForGGNewsletter boolean
signupForCharityNewsletter boolean
payment_detail
firstname string
lastname string
address string
address2 string
city string
state string
iso3166CountryCode string
zip string
phone string
creditCardNumber string
expiryDateMonth int
expiryDateYear int
securityCode int
giftCertificate_detail
giftCertificateNumber string

Element Definitions for Submit a Donation Request

Element Mandatory Description
refcode required The external identifier (maximum 100 characters) of the person who submitted the request which is returned in the response.
transactionId optional Your unique transaction identifier (maximum 100 characters) for this transaction stored in our records for future reference and possible reporting.
email required Email of user that made the donation.
twitter_username optional Twitter username of user that made the donation.
amount required Donation amount.
currencyCode optional (Defaults to USD) Contact GlobalGiving for questions about using any currency other than USD.
addon -> amount required if addon element was provided Add on donation amount funding GlobalGiving's operational expenses.
project -> id required Unique identifier for a GlobalGiving project.
noteToOrganization optional * A "note" to send to the organization along with the donation when it is disbursed
signupForGGNewsletter optional True if user should receive GlobalGiving newsletter. Default is false.
signupForCharityNewsletter optional True if user should receive Charity newsletter. Default is false.
firstname required First name of user making donation.
lastname required Last name of user making donation.
address required Address of user making donation.
address2 required Line 2 of address of user making donation.
city required City of user making donation.
state required State or Province of user making donation.
iso3166CountryCode required ISO 3166 Country codeexternal link of user making donation.
zip required Zip or Postal Code of user making donation.
phone optional Phone of user making donation.
creditCardNumber required Credit Card number used to make donation.
expiryDateMonth required Expiry month of Credit Card used to make donation.
expiryDateYear required Expiry year of Credit Card used to make donation.
securityCode required Security code of Credit Card used to make donation.
giftCertificateNumber optional if payment_detail was provided Gift Certificate Number provided by GlobalGiving.

* - Field is only recognized if api key has special permission to post notes to the organization. Please contact us with questions. Submitting this field is optional, and values will be ignored if your key does not have the permission to use.

Donation Response Structure

donation
amount decimal
chargedAmount decimal
currencyCode string
addon
amount decimal
datetime dateTime
email string
project
funding decimal
goal decimal
id int
numberOfDonations int
progressReportLink string
projectLink string
remaining decimal
refcode string
noteToOrganization string
signupForCharityNewsletter boolean
signupForGGNewsletter boolean
transactionId string
twitter_username string
checkedOut boolean
payment_detail
address string
address2 string
city string
creditCardNumber string
creditCardType string
expiryDateMonth int
expiryDateYear int
firstname string
iso3166CountryCode string
lastname string
phone string
securityCode int
state string
zip string
giftCertificate_detail
currencyCode string
giftCertificateNumber string
redeemedAmount decimal
remainingAmount decimal
receipt
currencyCode string
receiptNumber string
taxDeductibleContributionAmount decimal
totalAmountBilled decimal

Element Definitions for Donation Response

Element Mandatory Description
amount required Donation amount.
chargedAmount required Total donation amount that was charged. The sum of amount and addon amount minus any gift certificate redemptions.
currencyCode required Will be "USD" unless you have received a GlobalGiving UK api key, in which case currency will code be "GBP"
addon -> amount required if addon element was provided Add on donation amount funding GlobalGiving's operational expenses.
datetime required Date time of donation transaction (format YYYY-MM-DDThh:mm:ss[.s[s*]][TZD]).
email required Email of user that made the donation.
funding required Total funding project has received to date.
goal required Project goal.
id required Unique identifier for a GlobalGiving project.
numberOfDonations required Total number of donations received to date.
progressReportLink required URI of progress report for project.
projectLink optional URI of the project.
remaining required Total amount remaining for project to meet its goal.
refcode required The external identifier submitted with the request.
noteToOrganization optional * A "note" to send to the organization along with the donation when it is disbursed
signupForCharityNewsletter required True if user should receive Charity newsletter.
signupForGGNewsletter required True if user should receive GlobalGiving newsletter.
transactionId optional Your external identifier submitted with the request.
twitter_username required Twitter username of user that made the donation.
checkedOut required True if donation was successfully transacted.
address required Address of user making donation.
address2 optional Line 2 of address of user making donation.
city required City of user making donation.
creditCardNumber required Partial (obscured, e.g. 4111-XXXX-XXXX-1111) Credit Card number used to make donation.
creditCardType required Determined type of Credit Card used to make donation.
expiryDateMonth required Expiry month of Credit Card used to make donation.
expiryDateYear required Expiry year of Credit Card used to make donation.
firstname required First name of user making donation.
iso3166CountryCode required ISO 3166 Country codeexternal link of user making donation.
lastname required Last name of user making donation.
phone optional Phone of user making donation.
securityCode required Security code of Credit Card used to make donation.
state required State or Province of user making donation.
zip required Zip or Postal Code of user making donation.
giftCertificateNumber optional if payment_detail was provided Gift Certificate Number provided by GlobalGiving.
redeemedAmount optional if payment_detail was provided The amount redeemed off the gift certificate.
remainingAmount optional if payment_detail was provided Any remaining amount left on the gift certificate.
receiptNumber required GlobalGiving receipt number issued for donation.
taxDeductibleContributionAmount required The amount available as a tax deduction.
totalAmountBilled required The total amount billed.

* - This field will only be returned if it was submitted and accepted. See above fields for submitting donations for more.