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 send a gift card. This is a secure request as indicated by the '/secure/' element in the URL path, therefore, an access token (authentication) is required. A purchase can be made by submitting credit card information.
POST
xml, json
xml, json
https://api.globalgiving.org/api/secure/givingservice/giftcards
&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
/api/secure/givingservice/giftcards?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 20 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)
amount - a numeric value greater than $10 USD or £5 when donating using a GlobalGiving UK API key, required
currencyCode - optional; defaults to "USD" (for US Dollars)
addon; - optional
amount - a numeric value greater than zero, required if addon element is provided
signupForGGNewsletter - optional; defaults to false
signupForCharityNewsletter - optional; defaults to false
payment_detail;
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
giftCardDesign;
id - required (must an id representing an available gift card design)
giftCard_detail;
dateToSend - required (must be in "yyyy-mm-dd" format and cannot be a past date)
firstname - required (maximum 100 characters)
lastname - required (maximum 100 characters)
email - required (maximum 200 characters)
phone - optional (maximum 20 characters), used to contact recipient if cannot deliver email
to - optional
from - optional
message - optional
curl -H "Accept: application/xml" -H "Content-Type: application/xml" -d "<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<giftCard>
<refcode>123456789</refcode>
<transactionId>abc123</transactionId>
<email>john.doe@hotmail.com</email>
<amount>25</amount>
<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>4000100011112224</creditCardNumber>
<securityCode>123</securityCode>
<expiryDateMonth>09</expiryDateMonth>
<expiryDateYear>2014</expiryDateYear>
</payment_detail>
<giftCardDesign>
<id>19</id>
</giftCardDesign>
<giftCard_detail>
<dateToSend>2010-09-10</dateToSend>
<firstname>Debbie</firstname>
<lastname>Gallagher</lastname>
<email>debbie.gallagher@gmail.com</email>
<phone>202-555-1212</phone>
<to>Debbie</to>
<from>Frank</from>
<message>Here's a gift card so you can donate to your favorite project!</message>
</giftCard_detail>
</giftCard>" -X POST "https://api.globalgiving.org/api/secure/givingservice/giftcards?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"?>
<giftCard>
<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>
<refcode>123456789</refcode>
<signupForCharityNewsletter>false</signupForCharityNewsletter>
<signupForGGNewsletter>false</signupForGGNewsletter>
<transactionId>abc123</transactionId>
<checkedOut>true</checkedOut>
<giftCertificate_detail>
<currencyCode>USD</currencyCode>
<giftCertificateNumber>GZTKACJEA0Q46</giftCertificateNumber>
<remainingAmount>25.00</remainingAmount>
</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>
<zip>20001</zip>
<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>
<giftCardDesign>
<id>19</id>
</giftCardDesign>
<giftCard_detail>
<dateToSend>2010-09-10T23:59:59-07:00</dateToSend>
<firstname>Debbie</firstname>
<lastname>Gallagher</lastname>
<email>debbie.gallagher@gmail.com</email>
<phone>202-555-1212</phone>
<to>Debbie</to>
<from>Frank</from>
<message>Here's a gift card so you can donate to your favorite project!</message>
</giftCard_detail>
</giftCard>
NOTE: If successful, response contains the <giftCertificate_detail> section containing the new <giftCertificateNumber> that can now be used, along with the <receipt> section, and <checkedOut>, and <datetime> elements.
giftCard |
|
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 gift card purchase. | |
amount | required | Gift card 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 amount funding GlobalGiving's operational expenses. |
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 gift card purchase. |
lastname | required | Last name of user making gift card purchase. |
address | required | Address of user making gift card purchase. |
address2 | required | Line 2 of address of user making gift card purchase. |
city | required | City of user making gift card purchase. |
state | required | State or Province of user making gift card purchase. |
iso3166CountryCode | required | ISO 3166 Country code of user making gift card purchase. |
zip | required | Zip or Postal Code of user making gift card purchase. |
phone | optional | Phone of user making gift card purchase. |
creditCardNumber | required | Credit Card number used to make gift card purchase. |
expiryDateMonth | required | Expiry month of Credit Card used to make gift card purchase. |
expiryDateYear | required | Expiry year of Credit Card used to make gift card purchase. |
securityCode | required | Security code of Credit Card used to make gift card purchase. |
giftCardDesign -> id | required | Unique identifier representing an available gift card design. |
dateToSend | required | Date of when to send out gift card. Must be in "yyyy-mm-dd" format and cannot be a past date. |
giftCard_detail -> firstname | required | The first name of the gift card recipient. |
giftCard_detail -> lastname | required | The last name of the gift card recipient. |
giftCard_detail -> email | required | The email of the gift card recipient. |
giftCard_detail -> phone | optional | The phone number of the gift card recipient. Used if email cannot be delivered. |
to | optional | The name that appears in the "to" section of gift card. |
from | optional | The name that appears in the "from" section of gift card. |
message | optional | The message that appears on the gift card. |
giftCertificate |
|
Element | Mandatory | Description |
---|---|---|
amount | required | Gift card amount. |
chargedAmount | required | Total amount charged. The sum of amount and addon amount. |
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 amount funding GlobalGiving's operational expenses. |
datetime | required | Date time of gift card purchase transaction (format YYYY-MM-DDThh:mm:ss[.s[s*]][TZD]). |
required | Email of user that made the gift card purchase. | |
refcode | required | The external identifier submitted with the request. |
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. |
checkedOut | required | True if gift card purchase was successfully transacted. |
currencyCode | required | Will be "USD" unless you have received a GlobalGiving UK API key, in which case currency will code be "GBP" |
giftCertificateNumber | required | Gift Certificate Number provided by GlobalGiving. |
remainingAmount | required | The amount on the gift certificate. |
address | required | Address of user making gift card purchase. |
address2 | optional | Line 2 of address of user making gift card purchase. |
city | required | City of user making gift card purchase. |
creditCardNumber | required | Partial (obscured, e.g. 4000-XXXX-XXXX-2224) Credit Card number used to make gift card purchase. |
creditCardType | required | Determined type of Credit Card used to make gift card purchase. |
expiryDateMonth | required | Expiry month of Credit Card used to make gift card purchase. |
expiryDateYear | required | Expiry year of Credit Card used to make gift card purchase. |
firstname | required | First name of user making gift card purchase. |
iso3166CountryCode | required | ISO 3166 Country code of user making gift card purchase. |
lastname | required | Last name of user making gift card purchase. |
phone | optional | Phone of user making gift card purchase. |
securityCode | required | Security code of Credit Card used to make gift card purchase. |
state | required | State or Province of user making gift card purchase. |
zip | required | Zip or Postal Code of user making gift card purchase. |
currencyCode | required | Will be "USD" unless you have received a GlobalGiving UK API key, in which case currency will code be "GBP" |
receiptNumber | required | GlobalGiving receipt number issued for gift card purchase. |
taxDeductibleContributionAmount | required | The amount available as a tax deduction. |
totalAmountBilled | required | The total amount billed. |
giftCardDesign -> id | required | Unique identifier representing an available gift card design. |
dateToSend | required | Date of when to send out gift card. |
giftCard_detail -> firstname | required | The first name of the gift card recipient. |
giftCard_detail -> lastname | required | The last name of the gift card recipient. |
giftCard_detail -> email | required | The email of the gift card recipient. |
giftCard_detail -> phone | optional | The phone number of the gift card recipient. |
to | optional | The name that appears in the "to" section of gift card. |
from | optional | The name that appears in the "from" section of gift card. |
message | optional | The message that appears on the gift card. |