Submit a Donation v2.0

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 payment gateway key and nonce
2. submitting payment gateway key and saved payment token
3. by providing a valid gift certificate number
4. by submitting payment gateway key and nonce along with a gift certificate number

Submitting payment gateway key and nonce
GlobalGiving will provide you with a payment gateway key after certifying that you will handle donor input and data in compliance with PCI-DSS standards. The payment gateway will generate a payment nonce once a user submits payment with the credit card information. (in an iframe). You must pass the payment gateway key and the nonce with the rest of the payment information. This effectively replaces the the credit card information (number, expiration date and security code). This results in no credit card data being stored on your server (we also don't store credit card information at GlobalGiving).

Submitting payment gateway key and saved payment token
GlobalGiving will provide you with a payment gateway key after certifying that you will handle donor input and data in compliance with PCI-DSS standards. You may generated a saved payment token through the payment processor (in this case Braintree) and submit it instead of credit card informaiton. This is useful if you would like to make donations or purchase gift certificates and cards using a single payment method, rather than an individual payment method for each donor. This results in no credit card data being stored on your server (we also don't store credit card information at GlobalGiving).

How a nonce is obtained
A nonce is obtained once a user submits payment fields hosted by the payment gateway: Braintree. You accomplish this with a javascript call-back in your form when a submit event takes place.

You have two options for implementation:

a) Client side: In a two step process, you get the nonce in the call-back, but submit the API post directly to GlobalGiving from the client web browser. Example (use view source to save and change values)
OR
b) Server side: In a three step process, you get the nonce in the call back, submit the form to your own server and THEN submit the API post like any other server-side API call. Example (use view source to save and change values)

Since a donation can be made with either payment data 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:

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 payment is sent to a test server and the transaction will not be processed. A TEST paymentGatewayKey will be provided for testing with fake credit card numbers. Only test credit cards may be used . Note: The test flag is not yet supported for purchaising gift certificates and gift cards through this endpoint. Optional.

Query String Example:

/api/secure/givingservice/donationsclient?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

exactly one [project, organization, giftCertificate_detail, or giftCard_detail and giftCard_design], required

Note that a giftCertificate_detail can either be used to provide an expiration date for the purchase of a gift certificate OR to provde a payment method, but NOT BOTH. This implies that a gift certificate cannoth be purchased with another gift certificate. Likewise, a gift card MAY NOT be purchased with a gift certificate.

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

organization

id - the numeric identifier for an active organization (one with active projects), required

giftCertificate_detail

expirationDate - when the purchased gift certificate should expire, required
see Order a Gift Certificate

giftCard_detail

Information describing the gift card, a giftCard_design must be included if you include a giftCard_detail, required
see Send A Gift Card

noteToOrganization - optional (maximum 255 characters)*

partnerCode - optional (maximum 40 characters)*

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 - optional (maximum 50 characters)

address2 - optional (maximum 50 characters)

city - optional (maximum 25 characters)

state - optional (maximum 25 characters)

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

phone - optional (maximum 20 characters)

paymentGateway - required, value must be "braintree"

paymentGatewayKey - required (maximum 100 characters); A different key is provided for testing with fake credit card numbers.

paymentGatewayNonce - required (maximum 200 characters)

paymentGatewaySavedPaymentToken - (maximum 200 characters) if this is provide, then the only required fields in a payment_detail are firstname, lastname, paymentGateway, and paymentGatewaySavedPaymentToken

ipAddress - optional; The donor's IP address found in the HTTP header 'x-forwarded-for' (rather than the IP address of your server)

userAgent - optional; The donor's user agent found in the HTTP header 'user-agent' (rather than your application's user agent)

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>
      <paymentGateway>braintree</paymentGateway>
      <paymentGatewayKey>9j4phxoh_346mrgcqabppmnhx</paymentGatewayKey>
      <paymentGatewayNonce>afjdlaljifoap[4kcx@dk</paymentGatewayNonce>
   </payment_detail>
   <ipAddress>192.168.1.1e</ipAddress>
   <userAgent>Mozilla/5.0 (OS 10.0) like Gecko</userAgent>
</donation>" -X POST "https://api.globalgiving.org/api/secure/givingservice/donationsclient?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>https://www.globalgiving.org/pr/1900/proj1883a.html#progressReports</progressReportLink>
      <projectLink>https://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>
      <paymentGateway>braintree</paymentGateway>
      <paymentGatewayKey>9j4phxoh_346mrgcqabppmnhx</paymentGatewayKey>
      <paymentGatewayNonce>afjdlaljifoap[4kcx@dk</paymentGatewayNonce>
      <creditCardNumber>4000-XXXX-XXXX-2224</creditCardNumber>
      <securityCode>XXX</securityCode>
      <expiryDateMonth>09</expiryDateMonth>
      <expiryDateYear>2014</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>
   <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>
      <paymentGateway>giftcertificate</paymentGateway>
   </payment_detail>
</donation>" -X POST "https://api.globalgiving.org/api/secure/givingservice/donationsclient?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>https://www.globalgiving.org/pr/1900/proj1883a.html#progressReports</progressReportLink>
      <projectLink>https://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 partnerCode 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 paymentGateway string paymentGatewayKey string paymentGatewayNonce string paymentGatewaySavedPaymentToken string giftCertificate_detail giftCertificateNumber string expirationDate date (yyyy-mm-dd) 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 giftCardDesign id int giftCard_detail dateToSend date (yyyy-mm-dd) firstname string lastname string email string phone string to string from string message 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 (maximum 255 characters)
partnerCode	optional *	A partnerCode associated with the API Key (maximum 40 characters)
signupForGGNewsletter	optional	True if user should receive GlobalGiving newsletter. Default is false.
signupForCharityNewsletter	optional	True if user should receive Charity newsletter. Default is false.
ipAddress	optional	The donor's IP address (rather than your server's IP address). Found in the X-Forwarded-For header sent by the donor's browser.
userAgent	optional	The donor's user agent (rather than your server's user agent). Found in the User-Agent header sent by the donor's browser.
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 code of user making donation.
zip	required	Zip or Postal Code of user making donation.
phone	optional	Phone of user making donation.
paymentGateway	required	if used, value must be "braintree" (without quotes)
paymentGatewayKey	required	reusable key provided to you by GlobalGiving
paymentGatewayNonce	required unless using the paymentGatewaySavedPaymentToken	Unique token generated by the payment gateway
paymentGatewaySavedPaymentToken	required unless providing a paymentGatewayNonce and payment method information	Unique token generated by the payment gateway for a saved payment method
giftCertificateNumber	optional if payment_detail was provided	Gift Certificate Number provided by GlobalGiving.
giftCardDesign		id int
giftCard_detail		dateToSend date (yyyy-mm-dd) firstname string lastname string email string phone string to string from string message string

* - 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 partnerCode string signupForCharityNewsletter boolean signupForGGNewsletter boolean transactionId string twitter_username string checkedOut boolean payment_detail address string address2 string city string paymentGateway string paymentGatewayKey string paymentGatewayNonce 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
partnerCode	optional *	A partnerCode associated with this API KEY
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.
paymentGateway	required	value is "braintree" (without quotes)
paymentGatewayKey	required	reusable key provided to you by GlobalGiving
paymentGatewayNonce	required	Unique token generated by the payment gateway
creditCardNumber	required	Partial (obscured, e.g. 4000-XXXX-XXXX-2224) 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 code 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.