Send a Gift Card

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:

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

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

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