Questions answered in this document:

What is the Giving Gateway?

The Giving Gateway is a technology service provided by University Development. The Giving Gateway enables any group associated with or doing work with the University to transmit gift and pledge information to a payment processor over the Internet.

Should my Unit (School or Department) use the Giving Gateway?

The Giving Gateway is beneficial for several reasons. Providing your constituents with an easy and fast way to make a gift or pledge is a great way to supplement your fundraising efforts. Although University Development has provided secure online donation services with real-time credit card authorization since 2001, the Giving Gateway provides a highly customizable interface for unit's technical staff to work with. For units with their own websites and technical staff, the Giving Gateway gives them the highest level of control over the look and flow of the giving process while still taking advantage of the security and data management services provided by University Development. Units may also choose to use outside vendors for the web design, development and/or hosting.

How long does it take to go live?

The time it takes to go live will depend upon the technical resources available to your unit. If a solid infrastructure (web servers up and running along with staff knowledgeable in web design, scripting languages and database interactivity) already exists in your unit, going live could take a little as one week for a simple giving form.

Where do I go to start developing a website to use the Giving Gateway?

Everything you need to know in order to start developing a website that will use the Giving Gateway is outlined in the remainder of this document. If you are not the person that will be doing the website development then you will want to give a copy of this document to your technical staff.

Where is the Gateway?

The URL for the Gateway is https://ubfoundation.buffalo.edu/giving/gateway/gateway.php. All transactions submitted to https://ubfoundation.buffalo.edu/giving/gateway/gateway.php will be considered real and loaded into UB fundraising database called AWA. There is a test gateway for developers at https://ubfoundation.buffalo.edu/test/giving/gateway/gateway.php. Transactional information posted to https://ubfoundation.buffalo.edu/test/giving/gateway/gateway.php will be discarded periodically.

What information do I need to submit to the Gateway?

The following table of fields are the inputs to the Gateway. All passed in data is checked for validity as specified below and all data is checked for proper length. You should not rely on the Gateway for validation. Your scripts should validate the data before it is passed into the Gateway so that you can create a seamless application that allows the visitor to correct potential problems before being passed off to the Gateway.

variable data type length required? default
value		 notes
Primary person making the donation.
id_number STRING 10     The AWA "Entity" ID NUMBER of the primary person making the donation.
person_number STRING 10     The UB Person Number of the primary person making the donation.
pref_class_year STRING 4     The donor's preferred class year (usually their most recent year of graduation). For alumni only. Valid Values: 1900 - Current Year
pref_school_code STRING 4     The donor's preferred school (usually the school within UB where they got their most recent degree). For alumni only. Valid values: See xml file.
last_name STRING 25 X   The donor's last name.
first_name STRING 25 X   The donor's first name.
middle_name STRING 25     The donor's middle name or middle initial.
pers_suffix STRING 25     The donor's name suffix (III, Jr., etc.).
prefix STRING 25     The donor's salutation prefix (Ms., Mrs., Mr., Dr., etc.).
gender_code STRING 1     The donor's gender. Valid values: See xml file.
former_name STRING 60     The donor's former name - perhaps a maiden name.
birth_dt STRING/DATE 8     The donor's birth date in YYYYMMDD format. If you only have the birth year, you can pass zeros in for the MMDD part.
email_address STRING 255     The donor's email address.
home_street1 STRING 40 X   The donor's home street address (line 1).
home_street2 STRING 40     The donor's home street address (line 2).
home_street3 STRING 40     The donor's home street address (line 3).
home_city STRING 30 X The donor's home address city.
home_state_code STRING 3     The donor's home address state code. Valid values: See xml file.
home_zip STRING 30 X The donor's home address zip.
home_country_code STRING 5 X   The donor's home country code. Valid values: See xml file.
home_phone_number STRING 20     The donor's home phone number.
employment_type STRING 20     The donor's employment type. Required when any work address information is provided. Valid values: See xml file.
work_company_name_1 STRING 60     The donor's employer (line 1).
work_company_name_2 STRING 60     The donor's employer (line 2).
work_business_title STRING 35     The donor's work title.
work_street1 STRING 40     The donor's work street address (line 1).
work_street2 STRING 40     The donor's work street address (line 2).
work_street3 STRING 40     The donor's work street address (line 3).
work_city STRING 30     The donor's work address city.
work_state_code STRING 3     The donor's work address state. Valid values: See xml file.
work_zip STRING 30     The donor's work address zip.
work_country_code STRING 5     The donor's work address country. Valid values: See xml file.
work_phone_number STRING 20     The donor's work phone number.
work_fax_number STRING 20     The donor's work fax number.
marital_status_code STRING 1     The donor's marital status. Valid values: See xml file.
affinity_code_1
affinity_code_2
...
affinity_code_n		 STRING 20     How the donor is related to UB. Valid values: See xml file.
affinity_other STRING 200     Free-form text of how the donor is related to UB. To be used when the options in the valid values do not apply.
Spouse or Domestic Partner of the primary person making the donation.
spouse_id_number STRING 10     The AWA "Entity" ID NUMBER of the donor's spouse.
spouse_pref_class_year STRING 4     The spouse's preferred class year (usually their most recent year of graduation). For alumni only. Valid Values: 1900 - Current Year
spouse_pref_school_code STRING 4     The spouse's preferred school (usually the school within UB where they got their most recent degree). For alumni only. Valid values: See xml file.
spouse_last_name STRING 25     The spouse's last name.
spouse_first_name STRING 25     The spouse's first name.
spouse_middle_name STRING 25     The spouse's middle name or middle initial.
spouse_pers_suffix STRING 25     The spouse's name suffix (III, Jr., etc.).
spouse_prefix STRING 25     The spouse's salutation prefix (Ms., Mrs., Mr., Dr., etc.).
spouse_gender_code STRING 1     The spouse's gender. Valid values: See xml file.
spouse_former_name STRING 60     The spouse's former name - perhaps a maiden name.
spouse_birth_dt STRING/DATE 8     The spouse's birth date in YYYYMMDD format. If you only have the birth year, you can pass zeros in for the MMDD part.
spouse_email_address STRING 255     The spouse's email address.
spouse_employment_type STRING 20     The spouse's employment type. Required when any work address information is provided for the spouse. Valid values: See xml file.
sp_work_company_name_1 STRING 60     The spouse's employer (line 1).
sp_work_company_name_2 STRING 60     The spouse's employer (line 2).
sp_work_business_title STRING 35     The spouse's work title.
sp_work_street1 STRING 40     The spouse's work street address (line 1).
sp_work_street2 STRING 40     The spouse's work street address (line 2).
sp_work_street3 STRING 40     The spouse's work street address (line 3).
sp_work_city STRING 30     The spouse's work address city.
sp_work_state_code STRING 3     The spouse's work address state. Valid values: See xml file.
sp_work_zip STRING 30     The spouse's work address zip.
sp_work_country_code STRING 5     The spouse's work address country. Valid values: See xml file.
sp_work_phone_number STRING 20     The spouse's work phone number.
sp_work_fax_number STRING 20     The spouse's work fax number.
In Honor Of details.
honor_code STRING 25     The type of remembrance. Valid values: See xml file.
honor_name STRING 75     The person being honored.
honor_notify_first_name STRING 25     The first name of the person to notify of the remembrance.
honor_notify_last_name STRING 25     The last name of the person to notify of the remembrance.
honor_notify_street1 STRING 40     The street address (line 1) of the person to notify of the remembrance.
honor_notify_street2 STRING 40     The street address (line 2) of the person to notify of the remembrance.
honor_notify_city STRING 30     The city of the person to notify of the remembrance.
honor_notify_state_code STRING 3     The state of the person to notify of the remembrance. Valid values: See xml file.
honor_notify_country_code STRING 5     The country of the person to notify of the remembrance. Valid values: See xml file.
honor_relationship STRING 200     The relationship of the donor to the person being honored.
Donation details.
total_amount NUMBER   See Notes   The total gift amount. Required for certain payment options - see notes element of valid payment options xml.
installment_amount NUMBER   See Notes   The installment amount. Required for certain payment options - see notes element of valid payment options xml.
payment_option STRING 10   "CC" - "Pay the total amount now via credit card" The gift payment option. Valid values: See xml file.
deferred_pmt_start_date STRING/DATE       The day the first payment will be made. YYYYMMDD format. If populated, must be greater than the current date.
pledge_payment_ind STRING 1   "N" - "No" Is the donation a payment on a pledge previously made to UB?

Valid values: See xml file.
joint_ind STRING 1   "N" - "No" Is the donation from both people above (i.e. the gift is joint from the couple)? This can affect how the tax receipt and thank you letter is worded.

Valid values: See xml file.
associated_allocation_1 STRING 16 X   Where the gift is allocated. Must be a valid and active allocation - See AWA or consult with Development Staff in your unit.
associated_amount_1 NUMBER   X   The portion of the gift that will go towards the allocation in associated_allocation_1. If the donor designated all of their gift to one allocation then this must be equal to either total_amount or installment_amount (which ever one is greater).
associated_allocation_2,
associated_allocation_3,
...
associated_allocation_n		 STRING 16     If the donor chooses to split their gift across multiple allocations, then one or more of these will be populated. If passed, must be a valid and active allocation - See AWA or consult with Development Staff in your unit.
associated_amount_2,
associated_amount_3,
...
associated_amount_n		 NUMBER       If the donor chooses to split their gift across multiple allocations, then there must be an associated_amount that corresponds to every associated_allocation. Additionally, the sum of all associated_amounts must equal either the total_amount or the installment_amount (which ever one is greater).
premium_code_1,
premium_code_2,
...
premium_code_n		 STRING 4     The premiums that the donor received as a result of this gift. For each premium_code passed, there must be a corresponding premium_qty and premium_unit_value passed. Valid values: See xml file.
premium_qty_1,
premium_qty_2,
...
premium_qty_n		 NUMBER       The quantity of each premium received. Must be a whole number > 0 if the code is passed in.
premium_unit_value_1,
premium_unit_value_2,
...
premium_unit_value_n		 NUMBER       The value of one premium with the corresponding code - if a jazz CD is worth $9 and they received 2, then the premium_unit_value is $9 and the premium_qty is 2.
Other Information
appeal_code STRING 5   "370" (On-Line-Giving) The appeal that this gift resulted from. Must be a valid appeal code - See AWA or consult with Development Staff in your unit.
pledge_number STRING 10     Unique number assigned to a pledge that the donor has made to UB - See AWA or consult with Development Staff in your unit.
payment_frequency_code STRING 5     Payment Frequency for pledges (INVOICE transactions) Must be a valid payment frequency code - See AWA or consult with Development Staff in your unit.
special_handling_code STRING 5     Handling code. Must be a valid handling code - See AWA or consult with Development Staff in your unit.
gift_processing_comment STRING 500     Pass any special instructions that you want the Gift Processing staff to read before posting the gift to our donor database. If the gift is joint with someone other than the spouse, or the gift is made on behalf of someone else, or the gift is in memory of someone... or anything not explicitly addressed by the other gateway fields.
   
user_data_1,
user_data_2,
...
user_data_n		 STRING 2000     Fields for you to use that will be returned with the response. It is recommended that you use one of these fields to store the transaction identifier that you use in your system so that you can link the response you receive from the Gateway back to the transaction data you stored and sent to the Gateway.
post_back_url STRING 2000 X    
Fund Drive Related Information - Optionally, and you must have a current fund drive set up in AWA
fd_unit_id STRING 4     Your unit_id for fund drives (usually your AWA school code)
fd_premium_code_1,
fd_premium_code_2,
...
fd_premium_code_n		 STRING 10     The premiums that the donor received as a result of this gift. For each fd_premium_code passed, there must be a corresponding fd_premium_qty passed. Check your fund drive set up in AWA for valid values. IT IS RECOMMENDED THAT YOU DO NOT USE THE OTHER PREMIUM FIELDS IN COMBINATION WITH THESE - CHOOSE ONE OR THE OTHER.
fd_premium_qty_1,
fd_premium_qty_2,
...
fd_premium_qty_n		 NUMBER       The quantity of each premium received. Must be a whole number>
fd_flex_field_1,
fd_flex_field_2,
...
fd_flex_field_n		 STRING 10     The Field ID for the Flex Field.
fd_flex_data_1,
fd_flex_data_2,
...
fd_flex_data_n		 STRING 500     The data to be stored in the flex field specified in the corresponding fd_flex_field.
Security and Site Identification Information
partner_site_code STRING 20     Sites wishing to customize the Gateway payment form using html must contact Development Services to have a partner_site_code and password setup.
transaction_key_in STRING 20     Anything random that is 20 characters long - used to verify md5_in. What you send should change every time.
md5_in STRING 32     See Below.
md5_in: This must be the md5 hash value of the concatenation of your passord + transaction_key_in.

For example, if your password is BreadAndButter and you set transaction_key_in to be RedWhiteAndBlue, then the value of md5_in should be the md5 hash of BreadAndButterRedWhiteAndBlue. In php, you would generate the value like this:

$md5_in = md5($your_password . $transaction_key_in);

Only you and the Gateway know the password so the Gateway will use the password + transaction_key_in to generate an md5 hash that must match md5_in.

If you do not pass in a valid md5_in value, all the html tags will be stripped out of payment_form_html_header and payment_form_html_footer for security reasons.

For more code help see:
PHP Examples
Microsoft's ASP.NET Examples
Macromedia's ColdFusion Examples
PERL Example
Here is another helpful MD5 resource.
Information specific to processing a credit card payment
charge_description STRING 255 X   This description will appear in the email generated when credit card gifts are made (Applies only for Payment Options CC, CMCC and MCC where customer_receipt_email is passed).
customer_receipt_email STRING 255     The email address where the customer version of the receipt from authorize.net will be sent. Must be in valid email format if passed.
customer_receipt_header STRING 2000     Text header for the customer version of the email receipt. DO NOT USE HTML TAGS HERE.
customer_receipt_footer STRING 2000     Text footer for the customer version of the email receipt. DO NOT USE HTML TAGS HERE.
merchant_receipt_email STRING 255     The email address where the merchant version (no header or footer) of the receipt from authorize.net will be sent. Must be in valid email format if passed. This should be someone in you office that works with the transaction data on your end.
payment_form_option STRING 1   "A" Choose from form layouts A - E. Try them to see what one you like.
payment_form_html_header HTML/CSS N/A     Html header for the form that collects the credit card information. This is the page that is hosted on our server - so all urls in your html must be absolute. It is recommended that if you must reference style sheet, images or other files that they are referenced securely (https url), other wise visitor may get nasty messages in their browser that the page contain unsecure items.

For security reasons, in order to pass html to the gateway you must pass a valid md5_in value.
payment_form_html_footer HTML/CSS N/A     Html footer for the form that collects the credit card information.
arb_ref_id STRING 20     Reference ID of your choosing for recurring transactions (Applies only for Payment Options CMCC and MCC ).

What information do I get back from the Gateway?

The following table of fields are what the Gateway returns to your website via an HTTP POST to the url that you specified it the the post_back_url.

variable data type length notes
user_data_1,
user_data_2,
...
user_data_n		 STRING 2000 What you passed in. It is recommended that you use one of these fields to store the transaction identifier that you use in your system so that you can link the response you receive from the Gateway back to the transaction data you stored and sent to the Gateway.
transaction_id STRING 10 The unique transaction identifier that the Gateway uses. You should keep this in your records for use when contacting the UB Foundation about a particular submission to the Gateway.
non_cc_transaction_recorded STRING Y If an non credit card transaction is submitted and accepted, this will contain "Y". For transactions submitted for credit card payment, see fields below.
authnet_response_code STRING 1

Authorize.net Response:
1 = This transaction has been approved.
2 = This transaction has been declined.
3 = There has been an error processing this transaction.
Please code accordingly. Only when receiving a "1" should you confirm with the site visitor that the transaction is a success.

The following actions are recommended for your web scripts when dealing with this field:

For "1": Show a confirmation or Thank You page.
For "2": Show a page that tells the user that their card was declined. Ask if they want to choose an alternate payment method or try another card, then have them resubmit.
For "3": Show a page that tells the user that the Credit Card processing system produced an error. Ask if they want to choose an alternate payment method or try another card, then have them resubmit. (more info on the particular error is in authnet_response_reason_text)

Important note regarding CMCC and MCC transactions:
Note that for payment types of CMCC and MCC your web script should also check the arb_result_code value as well. This field is outlined below under "Automated Recurring Billing information". A value of "Ok" indicates that a successful Automated Recurring Billing subscription was set up without error, otherwise "Error" will be the value. For CMCC and MCC payment types, it is possible that authnet_response_code will return a successful response ("1") and arb_result_code will return an error response ("Error"). When this happens, the customer's credit card has been charged the first installment of their payment, however, the Automated Recurring Billing subscription has not been set up.

- empty for non credit card transactions
authnet_response_reason_code STRING 2 Authorize.net Response: See authnet_response_reason_text Below

- empty for non credit card transactions
authnet_response_reason_text STRING varies Authorize.net Response:
See Pages 21-27 of Authorize.net documentation at http://www.authorizenet.com/support/AIM_guide.pdf

- empty for non credit card transactions
credit_card_name STRING 50 The name on the card charged - empty for an unsuccessful transaction

- empty for non credit card transactions
credit_card_number_last4 STRING 4 The last 4 digits on the card charged - empty for an unsuccessful transaction

- empty for non credit card transactions
credit_card_type STRING 20 The type of card charged - empty for an unsuccessful transaction (VISA, MASTERCARD, AMERICANEXPRESS, DISCOVER)

- empty for non credit card transactions
authnet_auth_code STRING 6 Authorize.net's Authorization Code - empty for an unsuccessful transaction

- empty for non credit card transactions
authnet_transaction_id STRING 10-20 Authorize.net's Transaction ID - empty for an unsuccessful transaction

- empty for non credit card transactions
transaction_key_out STRING 20 Random string generated by the gateway - it is the key you will need to test the md5_out value sent back
md5_out STRING 32 The md5 hash value generated by the Gateway from the concatenation of your password + transaction_key_out. For security reasons, you should verify this and reject any responses where md5_out is not valid (does not equal your md5 hash of your password + transaction_key_out).
Automated Recurring Billing information - Applies only for Payment Options CMCC and MCC
arb_ref_id STRING 20 What you passed in.
arb_result_code STRING varies

Authorize.net Response:
Ok = indicates that the recurring billing transaction was processed and accepted without error.
Error = indicates that the recurring billing transaction resulted in one or more errors.
arb_code STRING 6 Authorize.net Response: See arb_text Below

I00001 indicates a transaction was successfully processed.
arb_text STRING varies Authorize.net Response:
See Pages 19-21 of Authorize.net documentation at http://www.authorize.net/support/ARB_guide.pdf
arb_subscription_id STRING 13 Authorize.net-assigned ID number for the subscription. Empty for unsuccessful ARB transactions.

Demo Page

To see what a post to and from the gateway looks like, see this test page.