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:
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.
POST
xml, json
xml, json
https://api.globalgiving.org/api/secure/givingservice/donationsclient
&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.
/api/secure/givingservice/donationsclient?api_key=YOUR_API_KEY&api_token=SOME_API_TOKEN
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)
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 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.
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 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.
donation |
|
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. | ||||||||||||||||
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 |
|
|||||||||||||||||
giftCard_detail |
|
* - 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 |
|
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]). |
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.