addOfflineDonation

This method records offline donations (that were already processed by an external payment processor) into Luminate Online.

This method does not process donation transactions.

Client Servlet	Server Servlet	HTTP Methods Supported	Requires Authentication
None.	SRDonationAPI	POST	No.

Server API Syntax

https://secure2.convio.net/organization/site/SRDonationAPI?method=addOfflineDonation & api_key =value & login_name =value & login_password =value & v =value [ & center_id =value ] [ & response_format =xml |json ] [ & source =value ] [ & sub_source =value ] [ & suppress_response_codes =value ] & billing.name.first =value & billing.name.last =value & donor.email =value & form_id =value & level_id =value & offline_payment_method =cash |check |credit [ & additional_amount =value ] [ & anonymous =value ] [ & billing.address.city =value ] [ & billing.address.country =value ] [ & billing.address.county =value ] [ & billing.address.state =value ] [ & billing.address.street1 =value ] [ & billing.address.street2 =value ] [ & billing.address.street3 =value ] [ & billing.address.zip =value ] [ & billing.name.middle =value ] [ & billing.name.profSuffix =value ] [ & billing.name.suffix =value ] [ & billing.name.title =value ] [ & card_exp_date =value ] [ & card_exp_date_month =value ] [ & card_exp_date_year =value ] [ & card_number =value ] [ & card_type =value ] [ & check_number =value ] [ & designated.X.amount =value ] [ & designated.X.id =value ] [ & designated_write_in.X.amount =value ] [ & designated_write_in.X.contact =value ] [ & designated_write_in.X.name =value ] [ & donor.address.city =value ] [ & donor.address.country =value ] [ & donor.address.county =value ] [ & donor.address.state =value ] [ & donor.address.street1 =value ] [ & donor.address.street2 =value ] [ & donor.address.street3 =value ] [ & donor.address.zip =value ] [ & donor.cons_id =value ] [ & donor.email_opt_in =value ] [ & donor.employer =value ] [ & donor.name.first =value ] [ & donor.name.last =value ] [ & donor.name.middle =value ] [ & donor.name.profSuffix =value ] [ & donor.name.suffix =value ] [ & donor.name.title =value ] [ & donor.occupation =value ] [ & donor.phone =value ] [ & donor.phone_type =home |work |other ] [ & gift_aid =value ] [ & joint_donor.name.first =value ] [ & joint_donor.name.last =value ] [ & joint_donor.name.middle =value ] [ & joint_donor.name.suffix =value ] [ & joint_donor.name.title =value ] [ & matching_eligible =value ] [ & other_amount =value ] [ & premium_id =value ] [ & send_receipt =value ] [ & send_registration_email =value ] [ & shipping.address.city =value ] [ & shipping.address.country =value ] [ & shipping.address.county =value ] [ & shipping.address.state =value ] [ & shipping.address.street1 =value ] [ & shipping.address.street2 =value ] [ & shipping.address.street3 =value ] [ & shipping.address.zip =value ] [ & shipping.email =value ] [ & shipping.name.first =value ] [ & shipping.name.last =value ] [ & shipping.name.middle =value ] [ & shipping.name.profSuffix =value ] [ & shipping.name.suffix =value ] [ & shipping.name.title =value ] [ & shipping.phone =value ] [ & validate =value ]

Usage Notes

The addOfflineDonation method allows offline donations (meaning transactions that are processed by an external payment processor) to be recorded in Luminate Online.

The refundOfflineDonation method may be used to refund transactions logged through this API.

In a typical use case, a third-party payment service provider might use this API to notify Luminate Online of donation and refund transactions on behalf of a client. Because the same third-third party service provider may implement this API for multiple clients, clients should strictly limit the permissions of the API Administrator account that has access to this API.

API Administrator accounts that access this API must be assigned the Offline Donation API permission type, under which they may be granted permission either to "Add Offline Donations via API" or to "Add and Refund Offline Donations via API". You should grant these accounts only the minimum required permissions.

Note: API Administrator accounts are limited to API access, they are never permitted to log in to Luminate Online.

All donation methods must reference a shadow Donation Form on the Luminate Online web site. This shadow form is used to perform validation and to associate donations with the appropriate fundraising Campaign. The ID of this shadow Donation Form is passed in the required form_id parameter. The Donation Form must be designated as either online/offline or offline-only. The API also requires the ID of the appropriate Donation Level in the level_id parameter.

Validation can either simply check for the minimally required fields necessary to process a transaction (validate=false) or it can perform all of the same field-level validation done by the a Luminate Online donation form when accessed via its web page (validate=true). In addition to the parameters marked as always being required, the following conditions must also be met:

There must be a valid donor_email value.

Designated Giving

The Designated Giving feature in Online Giving allows you to set up Designees within your organization and then assign all funds from a donation form to a specific designee or permit your donors to specify which Designee(s) they would like to target with their gifts. To use this feature, you must first set up your list of Designees and Designation Types. Designation Types help organize your designees for display to your donors. For example, an educational institution might create the following Designation Types: Academic, Athletic, and Administrative. Individual designees, such as the football program or the biology department, can then be assigned to the appropriate Type.

To get the designation types and designees to use for a form, call the getDesignationTypes and getDesignees methods. To specify designations for a donation, use the designated.X.id and designated.X.amount parameters, substituting numbers for the "X" part of the parameter names to identify ID and amount pairs (the numbers do not need to be sequential). To specify "write-in" designations, use the designated_write_in.X.name, designated_write_in.X.contact, and designated_write_in.X.amount parameters.

Donation Errors

If the call to the API succeeds but one or more errors are encountered during transaction processing, adonationResponseobject will be returned listing reasons for the error. To correlate with the standard donation form processing,pageErrorelements in the response are the same messages that would be displayed near the top of the page and are sometimes generic. ThefieldErrorelements in the response are the same messages that would be displayed near input fields throughout the page and are always specific to the validation of input for an input field.

Error Responses

For common API errors such as authentication errors, the common error response is returned. An XML example:

<errorResponse xmlns="http://convio.com/crm/v1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://convio.com/crm/v1.0 http://service.convio.net/xmlschema/crm.public.v1.xsd">
  <code>2</code>
  <message>Incorrect API key.  Verify that the value of the parameter api_key matches the value of the SDP CONVIO_API_KEY.</message>
</errorResponse>

A JSON example:

{"errorResponse":{
  "code": "2",
  "message": "Incorrect API key.  Verify that the value of the parameter api_key matches the value of the SDP CONVIO_API_KEY.",
}}

For donation-specific errors, the "donationResponse" is returned and contains a list of the error messages. An XML example:


<donationResponse xmlns="http://convio.com/crm/v1"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://convio.com/crm/v1.0 http://service.convio.net/xmlschema/crm.public.v1.xsd">
  <errors>
    <code>101</code>
    <message>Error: There was a problem encountered while processing your donation.</message>
    <reason>FIELD_VALIDATION</reason>
    <pageError>There was a problem processing your request.  Please see below.</pageError>
    <fieldError>An email address is required.</fieldError>
    <fieldError>Billing state or province is required.</fieldError>
    <fieldError>Billing last name is required.</fieldError>
    <fieldError>Billing zip or postal code is required.</fieldError>
    <fieldError>Billing street address is required.</fieldError>
    <fieldError>Billing first name is required.</fieldError>
    <fieldError>Billing city is required.</fieldError>
  </errors>
</donationResponse>

A JSON example:

{"donationResponse":
  {"errors":
    {"code":"101",
     "reason":"FIELD_VALIDATION",
     "message":"Error: There was a problem encountered while processing your donation.",
     "fieldError":["An email address is required.",
                   "Billing state or province is required.",
                   "Billing last name is required.",
                   "Billing zip or postal code is required.",
                   "Billing street address is required.",
                   "Billing first name is required.",
                   "Billing city is required."],
     "pageError":"There was a problem processing your request.  Please see below."}
  }
}

Note: If you specify "true" in the optional suppress_response_codes parameter, both success and error results will return a donationResponse document with an HTTP return code of 200 - OK. You must parse the donationResponse document for an errors element to determine whether or not the call succeeded.

Server API Parameters

Common Server Parameters

See topic Common Parameters.

billing.name.first

Required. The billing name of the credit card owner. If not supplied, defaults to donor.name.first.

Type xsd:string.

billing.name.last

Required. The billing name of the credit card owner. If not supplied, defaults to donor.name.last.

Type xsd:string.

donor.email

Required. The donor's email address.

Type xsd:string.

form_id

Required. The ID of the donation form.

Type xsd:nonNegativeInteger.

level_id

Required. The ID of the donation level.

Type xsd:nonNegativeInteger.

offline_payment_method

Required. Payment method for this offline transaction

Type xsd:string.

Default is cash.

Options are:

cash
check
credit

additional_amount

Optional. Donation amount in addition to level amount.

Type xsd:string.

anonymous

Optional. Whether to mark the donation as "anonymous".

Type xsd:boolean.

billing.address.city

Optional. The billing address of the credit card owner. If not supplied, defaults to donor.address.city.

Type xsd:string.

billing.address.country

Optional. The billing address of the credit card owner.

Type xsd:string.

billing.address.county

Optional. The billing address of the credit card owner.

Type xsd:string.

billing.address.state

Optional. The billing address of the credit card owner. If not supplied, defaults to donor.address.state.

Type xsd:string.

billing.address.street1

Optional. The billing address of the credit card owner. If not supplied, defaults to donor.address.street1.

Type xsd:string.

billing.address.street2

Optional. The billing address of the credit card owner.

Type xsd:string.

billing.address.street3

Optional. The billing address of the credit card owner.

Type xsd:string.

billing.address.zip

Optional. The billing address of the credit card owner. If not supplied, defaults to donor.address.zip.

Type xsd:string.

billing.name.middle

Optional. The billing name of the credit card owner.

Type xsd:string.

billing.name.profSuffix

Optional. The billing name of the credit card owner.

Type xsd:string.

billing.name.suffix

Optional. The billing name of the credit card owner.

Type xsd:string.

billing.name.title

Optional. The billing name of the credit card owner.

Type xsd:string.

card_exp_date

Optional. Credit card expiration date in MM/YYYY format. Use either this or both card_exp_date_month and card_exp_date_year. Note: This method does not process transactions.

Type xsd:string.

card_exp_date_month

Optional. Credit card expiration month (1-12). Note: This method does not process transactions.

Type xsd:nonNegativeInteger.

card_exp_date_year

Optional. Credit card expiration year. Note: This method does not process transactions.

Type xsd:nonNegativeInteger.

card_number

Optional. Credit card number. Bowlderize values in the format "************1234." For security and method handling, specify the number in the form, not the URL. Note: This method does not process transactions.

Type xsd:string.

card_type

Optional. Credit card type. Note: This method does not process transactions.

Type xsd:string.

check_number

Optional. Check number for an offline donation made by check

Type xsd:string.

designated.X.amount

Optional. The amount of a donation to designate to a designee. The "X" part of the parameter must be an integer used to correspond to designated.X.id or, in the case of write-in designations, designated.X.name and designated.X.contact. This allows multiple pairs of ID/amount for multiple designations.

Type xsd:nonNegativeInteger.

designated.X.id

Optional. The ID of a designee to which to designate all or part of a donation. The "X" part of the parameter must be an integer used to correspond to designated.X.amount. This allows multiple pairs of ID/amount for multiple designations.

Type xsd:nonNegativeInteger.

designated_write_in.X.amount

Optional. The amount of a donation to designate to a designee. The "X" part of the parameter must be an integer used to correspond to designated_write_in.X.name and designated_write_in.X.contact. This allows multiple pairs of ID/amount for multiple designations.

Type xsd:nonNegativeInteger.

designated_write_in.X.contact

Optional. The contact information of an organization to which to designate all or part of a donation. The "X" part of the parameter must be an integer used to correspond to designated_write_in.X.name and designated_write_in.X.amount. This allows multiple sets of name/contact/amount for multiple designations.

Type xsd:string.

designated_write_in.X.name

Optional. The name of an organization to which to designate all or part of a donation. The "X" part of the parameter must be an integer used to correspond to designated_write_in.X.contact and designated_write_in.X.amount. This allows multiple sets of name/contact/amount for multiple designations.

Type xsd:string.

donor.address.city