donate

This method processes a donation by a constituent to a Donations 2 (not "Donations Classic") donation form.

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

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 ] [ &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 ] [ &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 ] [ &captcha_text=value ]

Usage Notes

Important: This method is used to process online credit card donations. To maintain PCI data security standards for payment card transactions, call this method directly from the client's browser and never proxy the call through an external server.

2021 Update: You can now provide Google reCAPTCHA v3 protection on your API-based donation form. See Secure donations with Google reCAPTCHA v3 in our new Luminate Online API site.

The Donation API 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 API also requires the ID of the appropriate Donation Level in the level_id parameter.

The donate method is intended specifically to enable online donation processing by payment card or bank transfer. To process payments via other online payment services (PayPal or Amazon), you must use instead startDonation. These methods do not support eCommerce purchases, TeamRaiser registration fees, additional registration gifts or offline gifts, or Personal Fundraising gifts.

Other API methods may also process payment card transactions, including:

Effect on Session State and Constituent Record

If donate is called in the context of a logged-in user session, the transaction will be credited to the logged-in constituent and the donor's constituent record will be updated with the name and address information provided in the call (billing information fields are used if the donor information fields are not included in the form).

If donate is called in the context of a session established by a remember-me cookie, the donation is credited to the constituent identified by the session, and updates are made to some tracking and status fields, however the constituent record is not updated with new contact information. The same is true when donate is called outside of any session context, but when the donor's email address matches exactly one existing constituent record.

Otherwise, if donate is called without a user session and the donor's email address cannot be matched to an existing constituent, a new constituent record will be created for the donor, a session will be established for the new constituent, and a session cookie will be pushed to the caller.

Validation

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 either credit card or ACH payment options specified.
  • There must be a billing name and address for transaction verification. These may be passed either as billing or donor parameters. If billing parameters (billing.name.first, billing.name.last, billing.address.street1, billing.address.city, billing.address.state, and billing.address.zip) are specified, those take precedence, otherwise donor parameter values are used.

    The reason for two sets of name and address fields is to allow the constituent record of the donor to be different from the name and address used for payment processing.

  • There must be a valid donor_email value.

Important: For security reasons, payment information may not be passed in the POST URL, and must be passed as multi-part form data of type Content-type: application/x-www-form-urlencoded in the request body.

Note: For testing purposes, you may use card_number=4111111111111111, card_cvv=111, and any date later than the transaction date for card_exp_date or card_exp_date_month and card_exp_date_year. Pass the df_preview parameter with any value when testing (the parameter value is not checked, only the presence of the parameter).
Note: Depending upon how the underlying donation form is configured, the tax-exempt amount returned may be different from the total amount of the donation. For example, if the donation is associated with a premium, the fair market value of the premium may be deducted.

Boolean Parameters in HTML Forms

Boolean parameters such as donor.email_opt_in and remember_me expect a value of "true" (ignoring case) to be set. Any other value is interpreted as "false". To set this in an HTML checkbox, include value="true" in the checkbox attributes.

Custom Fields

In the Donation Management application, administrators can define new custom fields to add to donation forms. To set a custom field with this method, the name of the API parameter is derived from the "Data Element Name" provided for the custom field. The Data Element Name is converted into a valid identifier by converting all letters to lower case and replacing all non-alphanumeric characters with underscores. So a Data Element Name of "My Custom String" should be passed into the donation API as "my_custom_string". Note that the "Data Element Name" is the same across all donation forms, and is not the same as the label that you actually specify in the form.

If validation is disabled (validate=false) and a Custom Field contains text longer than the maximum length for the field the text will be truncated to the maximum length and saved without an error.

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.

Sustaining (Recurring) Gifts

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

Donation Errors

If the call to the API succeeds but one or more errors are encountered during transaction processing, a donationResponse object will be returned listing reasons for the error. To correlate with the standard donation form processing, pageError elements in the response are the same messages that would be displayed near the top of the page and are sometimes generic. The fieldError elements 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.

Soft-crediting Gifts to TeamRaiser Participants, Teams, or Events

You can soft-credit donations processed through the donate or startDonation methods to TeamRaiser particpants, teams or events. In each case, you must include the TeamRaiser Event ID in the fr_id parameter. To soft-credit the gift to a participant: specify soft_credit_type as TR_PARTICIPANT, and pass the Constituent ID of the particpant in soft_credit_id. To soft-credit the gift to a team: specify soft_credit_type as TR_TEAM, and pass the Team ID in soft_credit_id. To soft-credit the gift to an event: specify soft_credit_type as TR_EVENT, and pass the Event ID (the same value as in fr_id) in soft_credit_id. The system returns an error if you attempt to soft-credit a donation to an event that is not currently accepting donations or to a team that does not accept team gifts.

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.
Parent topic: Donation API
Previous topic: cancelRecurringGift
Next topic: getDesignationTypes

Leave a Comment

Nickname
Comment
Enter this word:
Change