Purchase a Gift Certificate

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 purchase a gift certificate. 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.

HTTP Method:

POST

Content Type:

xml, json

Accept Type:

xml, json

Path:

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

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/giftcertificates?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)

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

sigupForCharityNewsletter - 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

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'?>
                  <giftCertificate>
                     <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>
                  </giftCertificate>" -X POST "https://api.globalgiving.org/api/secure/givingservice/giftcertificates?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"?>
                  <giftCertificate>
                     <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>
                  </giftCertificate>
               

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.

Purchase A Gift Certificate Request Structure

giftCertificate
refcode string
transactionId string
email string
amount decimal
addon
amount decimal
currencyCode 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

Element Definitions for Purchase A Gift Certificate 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 gift certificate purchase.
amount required Gift certificate purchase 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 certificate purchase.
lastname required Last name of user making gift certificate purchase.
address required Address of user making gift certificate purchase.
address2 required Line 2 of address of user making gift certificate purchase.
city required City of user making gift certificate purchase.
state required State or Province of user making gift certificate purchase.
iso3166CountryCode required ISO 3166 Country codeexternal link of user making gift certificate purchase.
zip required Zip or Postal Code of user making gift certificate purchase.
phone optional Phone of user making gift certificate purchase.
creditCardNumber required Credit Card number used to make gift certificate purchase.
expiryDateMonth required Expiry month of Credit Card used to make gift certificate purchase.
expiryDateYear required Expiry year of Credit Card used to make gift certificate purchase.
securityCode required Security code of Credit Card used to make gift certificate purchase.

Purchase A Gift Certificate Response Structure

giftCertificate
amount decimal
chargedAmount decimal
currencyCode string
addon
amount decimal
datetime dateTime
email string
refcode string
signupForCharityNewsletter boolean
signupForGGNewsletter boolean
transactionId string
checkedOut boolean
giftCertificate_detail
currencyCode string
giftCertificateNumber string
remainingAmount decimal
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
receipt
currencyCode string
receiptNumber string
taxDeductibleContributionAmount decimal
totalAmountBilled decimal

Element Definitions for Gift Certificate Response

Element Mandatory Description
amount required Gift certificate purchase 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 certificate purchase transaction (format YYYY-MM-DDThh:mm:ss[.s[s*]][TZD]).
email required Email of user that made the gift certificate 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 certificate 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 certificate purchase.
address2 optional Line 2 of address of user making gift certificate purchase.
city required City of user making gift certificate purchase.
creditCardNumber required Partial (obscured, e.g. 4000-XXXX-XXXX-2224) Credit Card number used to make gift certificate purchase.
creditCardType required Determined type of Credit Card used to make gift certificate purchase.
expiryDateMonth required Expiry month of Credit Card used to make gift certificate purchase.
expiryDateYear required Expiry year of Credit Card used to make gift certificate purchase.
firstname required First name of user making gift certificate purchase.
iso3166CountryCode required ISO 3166 Country codeexternal link of user making gift certificate purchase.
lastname required Last name of user making gift certificate purchase.
phone optional Phone of user making gift certificate purchase.
securityCode required Security code of Credit Card used to make gift certificate purchase.
state required State or Province of user making gift certificate purchase.
zip required Zip or Postal Code of user making gift certificate 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 certificate purchase.
taxDeductibleContributionAmount required The amount available as a tax deduction.
totalAmountBilled required The total amount billed.