Send a Gift Card

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

HTTP Method:

POST

Content Type:

xml, json

Accept Type:

xml, json

Path:

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

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/giftcards?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

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

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'?>
                  <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 Response:

            
                  <?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.

Send A Gift Card Request Structure

giftCard
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
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 Send A Gift Card 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 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 codeexternal link 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.

Send A Gift Card 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
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 Gift Certificate Response

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]).
email 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 codeexternal link 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.