REST

donate

Process online donations. This method requires an Online Giving shadow donation form and is only compatible with credit card, debit card, and direct bank transfer transactions.

Client ServletServer ServletHTTP Methods SupportedRequires Authentication
CRDonationAPINone.POSTNo.

Client API Syntax

https://secure2.convio.net/organization/site/CRDonationAPI?method=donate &api_key=value &v=value
[ &center_id=value ] [ &error_redirect=value ] [ &redirect=value ] [ &response_format=xml | json ]
[ &sign_redirects=value ] [ &source=value ] [ &sub_source=value ] [ &success_redirect=value ]
[ &suppress_response_codes=value ] &billing.address.city=value &billing.address.state=value
&billing.address.street1=value &billing.address.zip=value &billing.name.first=value
&billing.name.last=value &donor.email=value &form_id=value &level_id=value [ &ach_account=value ]
[ &ach_account_type=CHECKING | SAVINGS ] [ &ach_bank=value ] [ &ach_routing=value ] [ &ach_transit=value ]
[ &additional_amount=value ] [ &anonymous=value ] [ &billing.address.country=value ]
[ &billing.address.county=value ] [ &billing.address.street2=value ] [ &billing.address.street3=value ]
[ &billing.name.middle=value ] [ &billing.name.profSuffix=value ] [ &billing.name.suffix=value ]
[ &billing.name.title=value ] [ &card_cvv=value ] [ &card_exp_date=value ] [ &card_exp_date_month=value ]
[ &card_exp_date_year=value ] [ &card_number=value ] [ &card_type=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 ] [ &single_designated_id=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.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 | mobile ]
[ &ecard.copy_sender=value ] [ &ecard.id=value ] [ &ecard.message=value ] [ &ecard.recipients=value ]
[ &ecard.send=value ] [ &ecard.send_date=value ] [ &ecard.subject=value ] [ &facebook_donation_id=value ]
[ &fr_id=value ] [ &gift_aid=value ] [ &installment.duration=value ]
[ &installment.frequency=one-time | monthly | quarterly | semi-annually | annually ]
[ &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 ] [ &level_autorepeat=value ]
[ &matching_eligible=value ] [ &organization_name=value ] [ &other_amount=value ] [ &premium_id=value ]
[ &premium_option=value ] [ &remember_me=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 ] [ &soft_credit_id=value ]
[ &soft_credit_type=TR_PARTICIPANT | TR_TEAM | TR_EVENT | TRIBUTE_GIFT ]
[ &summary=data | page | both ] [ &sustaining.duration=value ]
[ &sustaining.frequency=one-time | monthly | quarterly | semi-annually | annually ]
[ &teamraiser.message_to_participant=value ] [ &teamraiser.recognition_name=value ]
[ &teamraiser.show_gift_to_public=value ] [ &tribute.honoree.deceased=value ]
[ &tribute.honoree.name.first=value ] [ &tribute.honoree.name.full=value ]
[ &tribute.honoree.name.last=value ] [ &tribute.honoree.name.title=value ] [ &tribute.message.body=value ]
[ &tribute.message.closing=value ] [ &tribute.message.include_amount=value ]
[ &tribute.message.signature=value ] [ &tribute.notify.address.city=value ]
[ &tribute.notify.address.country=value ] [ &tribute.notify.address.county=value ]
[ &tribute.notify.address.state=value ] [ &tribute.notify.address.street1=value ]
[ &tribute.notify.address.street2=value ] [ &tribute.notify.address.street3=value ]
[ &tribute.notify.address.zip=value ] [ &tribute.notify.name.full=value ]
[ &tribute.notify.name.title=value ] [ &tribute.type=memorial | tribute ] [ &validate=value ]

Usage Notes



This method is only compatible with credit card, debit card, and direct bank transfer transactions. This method does not support offline donations, TeamRaiser registration fees, Additional registration gifts, eCommerce, or Personal Fundraising gifts.Currently there are no rest API methods supporting eCommerce or Personal Fundraising.

This method requires two donation forms. The first is your API donation form. The second is a shadow form used to validate data, associate donations with a Donation Campaign, and update your database. Each field on your API donation form must have a corresponding field on the shadow form. Link your API donation form to the shadow form with the required form_id parameter.

Session State - Matching Donors to Constituent Records

Information from the donation form may be used to update the constituent record depending on if and how the donor is matched to a record.

  • Donor is logged in. The donation is recorded on the constituent record. The record automatically updates if the name, address, or billing address on the donation form differs from the record. The billing address is assumed to be the mailing address unless the form has another address field.
  • Donor is not logged in.
    • Donor is matched to a constituent record by email address or a remember-me cookie. The donation is recorded on the record. Some tracking and status fields may update, but the record address does not update. To match a donor to a constituent record based on email address, the address must match exactly one constituent record.
    • Donor cannot be matched to an existing constituent record. A new record is created, a session is established and associated with that record, and a session cookie is pushed to the caller.

Conditionally Required Parameters

Payment information is required for processing, but each payment detail parameter is optional because the donor is required to input card OR bank transfer information, not both.

  • Bank transfer parameters depend upon the country from which the funds are distributed and may include ach_account, ach_account_type, ach_bank (required for Canadian ACSS transactions), ach_routing, and ach_transit (required for Canadian ACSS transactions).
  • Card parameters include card_cvv, card_exp_date, card_exp_date_month, card_exp_date_year, card_number, and card_type.

Boolean Parameters in HTML Forms

Boolean parameters such as donor.email_opt_in and remember_me expect a value of TRUE. Any other value is interpreted as FALSE. To set this in an HTML checkbox, include value="true" in the checkbox attributes.

Designated Giving Parameters

Designated giving allows donors to direct their donation to a focus within the greater mission. For example, a donor to a hospital may want to direct money to the pediatrics or cancer ward. A donor to a school may want to direct funds to the art, music, or STEM programs.

  • getDesignationTypes returns a list of designation types.

  • getDesignees returns a list of valid designees.

  • Gifts can be designated to one entity or multiple entities.

    • Allowing a single designee

      • When allowing a single designee you must include the Single Gift Designation data element in your standard donation form. See Donation Form Data Elements for more details.

      • When allowing only a single designee for a donation, include the single_designated_id parameter instead of the designated.X parameters in your call. The designated.x parameters, if included, are ignored when a single_designated_id has been assigned.

    • Allowing multiple designees

      • When allowing multiple designees you must include the Designated Gift Donation Level data element in your standard donation form. See Donation Form Data Elements for more details.

      • When allowing a donor to assign specific donation amounts to multiple designees, you may add an Add a designee button that inserts fields for the designee selection, or write in designee information, and amount onto the form. The code for that button should start with an integer and be incremented for each additional designee. That integer identifies which designation is being referenced, and is the X value inserted in parameters such as designated.X.id.

    • Designees may be pre-configured or write-in.

      • Pre-configured designee information is passed in a pair of parameters: designated.X.id and designated.X.amount.

      • Write-in designee information is passed in set of three parameters: designated_write_in.X.name, designated_write_in.X.contact, designated_write_in.X.amount.

Soft-credit Parameters

You can soft-credit donations processed through the donate or startDonation methods to TeamRaiser participants, teams or events. In each case, you must include the TeamRaiser Event ID in the fr_id parameter.

  • Soft-credit a participant
    • soft_credit_type=TR_PARTICIPANT
    • soft_credit_id is participant's constituent id
  • Soft-credit a team
    • soft_credit_type=TR_TEAM
    • soft_credit_id is the team id
  • Soft-credit an event
    • soft_credit_type=TR_EVENT
    • soft_credit_id is the same as the fr_id

Sustaining (Recurring) Gifts Parameters

Sustaining giving lets donors set up recurring, automatic gifts, with either pre-set amounts and durations or flexible donor-specified commitments. Use the sustaining.frequency and sustaining.duration parameters to make sustaining donations. The shadow donation form must contain one of the sustaining giving donation level elements.

Installment programs enable higher-dollar giving levels with payment programs that offer the benefits of large gifts but automatically pay out over the schedules you design and donors select. Use the installment.frequency and installment.duration parameters to make installment donations. The shadow donation form must contain the installment plan donation level element.

Custom Fields and Parameters

Custom fields on your API donation form must map to data elements on your shadow form. Pass custom field input from your API donation form to your shadow form with custom parameters. The parameter name must match the data element name. The parameter name must be all lower case letters. Replace non-alphanumeric characters with underscores. Custom text fields have a default length of 50 characters and a maximum length of 512 characters.

How to add a custom data element to your shadow form in Luminate Online

  1. Find the form in the list in Fundraising, Donation Management, Online Giving. Select Edit and Design Donors Screen.
  2. Select Edit from the form Actions.
  3. Select New under Select data elements to include in this form.
  4. Name your element, select a data type and associated settings. Select Apply.
  5. Select your new data element under Select data elements to include in this form and Add it to Arrange the order of the selected data elements. You can change the placement of your field by selecting it and using the up and down Order arrows.
  6. Save before continuing.
  7. Select the data element to Edit Data Element and Preview Data Element.
  8. Select Test Drive to try out the donation form with your custom field and Publish.

Validation

The optional validate parameter default is FALSE. When validate=FALSE or the parameter is omitted, validation only checks the minimally-required fields necessary to process a transaction. Set to TRUE to perform all available field-level validation.

Testing the form

Include the df_preview parameter to evaluate the success of the API call without creating a transaction in your database. The parameter must be present with a TRUE or FALSE value. There is no difference between these settings. The presence of this parameter establishes a test call, regardless of the value you set for the parameter.

For credit card testing purposes, use the following parameters.

  • card_number=4111111111111111
  • card_cvv=111
  • Set card_exp_date or card_exp_date_month and card_exp_date_year to a future date.

Error Responses

If the API call succeeds, but one or more errors are encountered during transaction processing, a donationResponse object is returned listing reasons for the error. To correlate with the standard donation form processing, pageError elements in the response are the same messages that display near the top of the page and are sometimes generic. The fieldError elements in the response are the same messages that display near input fields throughout the page and are always specific to the validation of input for an input field.

For common API errors such as authentication errors, the common error response is returned.


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>
JSON example
JSON 
{"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.

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