donate

The "donate" method processes a donation by a constituent to a Donations 2 (not "Donations Classic") donation form and is only available when calling from a Web Client. Please review the authentication and security guidance before using this or any other API method available in the site configuration.

Validation can either simply check for the minimally required fields necessary to process a transaction or it can perform all of the same field-level validation done by the ghost form when accessed via its web page. 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. The name and address can be in either the Billing Information or Donor Information sets of parameters or both.

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.

Post URL

Deconstructing the URL
* In most cases secure2.convio.net matches a client's secure domain. However, in some cases this will be different. The correct secure domain for the API is identical to the secure domain for your fundraising forms. So if the sample above does not work, look for the unique secure domain used for your organization and replace the secure2.convio.net portion above with this URL.

*Here, organization is a client's unique identifier in the Convio system. Every client has a unique value that represents their instance of the product. If you're organization uses a custom secure URL for donations, the organization portion of the URL may not be necessary, contact support for assistance.

Example: https://demo-secure.convio.net/demo829/site/CRDonationAPI. Here you'll notice that demo-secure.convio.net is used for the domain, and demo829 is used for the organization.

Authentication

No authentication is required, since anyone can donate!

Parameters

The following parameters apply:

Name	Description
General Parameters
api_key	Required. An arbitrary value that must be passed when invoking the Convio Client and Server APIs. The value passed by the caller must match the value in the CONVIO_API_KEY site configuration parameter, which is unique for each Convio site.
v	Required. API version to invoke. Must be "1.0".
method	Required. Specifies which method to perform. To invoke this method use the value "donate"
response_format	Optional. Specifies the format in which to return the response. Can be either "xml" (the default value) or "json".
error_redirect	Optional. A URL to which to redirect after processing that results in an error.
success_redirect	Optional. A URL to which to redirect after successful processing.
redirect	Optional. A URL to which to redirect after processing. If you want to use the same URL regardless of success or error, you can use this parameter instead of specifying both error_redirect and success_redirect. Note that error_redirect and success_redirect take precedence over redirect.
Processing Parameters
validate	Whether to enforce validation of every field according to the specification in the ghost form ("true" or "false"). The default is "false". Some validation is always in effect, such as ensuring that the campaign, form, and level IDs reference published entities and that there is sufficient information to process the transaction.
form_id	Required. The ID of the donation form.
level_id	Required. The ID of the donation level.
summary	The type of donation summary to return. There are three options: data: returns a structured list of information about every form field. page: returns the HTML content (within the "body" element) of the "Thank you" page shown after donations via web page. both: returns both types of summary.
send_receipt	Whether to send a receipt email to the donor ("true" or "false"). The default behavior is to send it ("true").
send_registration_email	If a new constituent record is created for the donor, this specifies whether to send a registration "welcome" email to the donor ("true" or "false"). The default behavior is to send it ("true").
Payment Parameters
other_amount	User specified donation amount.
additional_amount	Donation amount in addition to level amount.
anonymous	Whether to mark the donation as "anonymous" ("true" or "false").
card_number	Credit card number. For security, this must be specified in the form -- it is an error to include it in the URL.
card_cvv	Credit card Verification Value. This is usually required, depending on the configuration of the Convio site.
card_exp_date_month	Credit card expiration month (1...12).
card_exp_date_year	Credit card expiration year
card_exp_date	Credit card expiration date in "MM/YYYY" format. Use either this or both card_exp_date_month and card_exp_date_year.
ach_account	ACH (debit) account number.
ach_routing	ACH routing number.
gift_aid	Gift aid status.
Billing Parameters
billing.address.street1	The billing address of the credit card owner.
billing.address.street2	The billing address of the credit card owner.
billing.address.city	The billing address of the credit card owner.
billing.address.state	The billing address of the credit card owner.
billing.address.zip	The billing address of the credit card owner.
billing.address.country	The billing address of the credit card owner.
billing.name.title	The billing name of the credit card owner.
billing.name.first	The billing name of the credit card owner.
billing.name.middle	The billing name of the credit card owner.
billing.name.last	The billing name of the credit card owner.
billing.name.suffix	The billing name of the credit card owner.
billing.name.proSuffix	The billing name of the credit card owner.
Donor Information Parameters
donor.address.street1	The donor's address.
donor.address.street2	The donor's address.
donor.address.city	The donor's address.
donor.address.state	The donor's address.
donor.address.zip	The donor's address.
donor.address.country	The donor's address.
donor.name.title	The donor's name.
donor.name.first	The donor's name.
donor.name.middle	The donor's name.
donor.name.last	The donor's name.
donor.name.suffix	The donor's name.
donor.name.proSuffix	The donor's name.
donor.email	The donor's email address.
donor.email_opt_in	Email opt-in selection ("true" or "false").
donor.phone	The donor's phone number.
donor.phone_type	The type of the donor's phone number ("home", "work", or "other").
donor.employer	The donor's employer.
donor.occupation	The donor's occupation.
remember_me	Whether to set a log-in cookie ("true" or "false").
Joint Gift Parameters
joint_donor.name.title	The name for a joint donor.
joint_donor.name.first	The name for a joint donor.
joint_donor.name.middle	The name for a joint donor.
joint_donor.name.last	The name for a joint donor.
joint_donor.name.suffix	The name for a joint donor.
Tribute or Memorial Gift Parameters
tribute.type	The type of tribute ("memorial" or "tribute").
tribute.honoree.deceased	Whether the tribute honoree is deceased ("true" or "false"). If set, it overrides "tribute.type" by setting it to "memorial" if deceased and "tribute" if not deceased.
tribute.notify.address.street1	The address of the person to notify of the tribute.
tribute.notify.address.street2	The address of the person to notify of the tribute.
tribute.notify.address.city	The address of the person to notify of the tribute.
tribute.notify.address.state	The address of the person to notify of the tribute.
tribute.notify.address.zip	The address of the person to notify of the tribute.
tribute.notify.address.country	The address of the person to notify of the tribute.
tribute.notify.name.title	The name title of the person to notify of the tribute.
tribute.notify.name.full	The full name of the person to notify of the tribute.
tribute.honoree.name.title	The name title of the person to honor with the tribute.
tribute.honoree.name.full	The full name of the person to honor with the tribute. Only used if the first and last names are not specified.
tribute.honoree.name.first	The first name of the person to honor with the tribute. Takes precedence over tribute.honoree.name.full.
tribute.honoree.name.last	The last name of the person to honor with the tribute. Takes precedence over tribute.honoree.name.full.
tribute.message.body	The body of the tribute notification message.
tribute.message.closing	The closing of the tribute notification message.
tribute.message.signature	The signature of the tribute notification message.
tribute.message.include_amount	Whether to include the donation amount in the tribute notification message ("true" or "false").

Response

Success

The HTTP status code is 200. The response is formatted as XML by default, but the response_format input parameter can be used to specify either XML or JSON formatting. For example:

XML format:

<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">
  <donation>
  	<amount>
  	  <decimal>35.00</decimal>
  	  <formatted>$35.00</formatted>
  	</amount>
  	<tax_deductible_amount>
  	  <decimal>35.00</decimal>
  	  <formatted>$35.00</formatted>
  	</tax_deductible_amount>
    	<value_of_goods>
  	  <decimal>0.00</decimal>
  	  <formatted>$0.00</formatted>
  	</value_of_goods>
  	<confirmation_code>1-1203-1-1202-1404</confirmation_code>
  	<date_time>2008-02-27T14:54:21.758-06:00</date_time>
  	<reward_points_earned>0</reward_points_earned>
  	<transaction_id>1404</transaction_id>
  	<org_tax_id>fake tax id : 123456-789</org_tax_id>
    <summary_data>
  	<field>
  	  <is_header>false</is_header>
  	  <label>Transaction Date:</label>
  	  <value>2/27/08</value>
  	  <name>date_id</name>
  	</field>
  	<field>
  	  <is_header>true</is_header>
  	  <label>Gift Information</label>
  	  <value/>
             <name>section-header</name>
  	</field>
  	<field>
 	  <is_header>false</is_header>
  	  <label>Amount:</label>
  	  <value>$60.00</value>
  	  <name>level_id</name>
  	</field>
  	<field>
  	  <is_header>true</is_header>
  	  <label>Billing Information</label>
  	  <value/>
  	  <name>section-header</name>
  	</field>
  	<field>
  	  <is_header>false</is_header>
  	  <label>Billing First Name:</label>
  	  <value>Jeff</value>
  	  <name>billing.name.first</name>
  	</field>
  	...
  	<field>
  	  <is_header>true</is_header>
  	  <label>Payment Information</label>
  	  <value/>
  	  <name>section-header</name>
  	</field>
  	<field>
  	  <is_header>false</is_header>
  	  <label>Payment type:</label>
  	  <value>Credit Card</value>
  	  <name>payment_type</name>
  	</field>
  	<field>
  	  <is_header>false</is_header>
  	  <label>Credit Card Number:</label>
  	  <value>***************1111</value>
  	<name>payment_type</name>
  	</field>
    </summary_data>
  </donation>

JSON format:

{"donationResponse":
  {"donation":
    {"summary_data":
      {"field":[{"value":"2/27/08","label":"Transaction Date:",
                   "name":"date_id","is_header":"false"},
                {"value":{},"label":"Gift Information",
                   "name":"section-header","is_header":"true"},
                {"value":"$60.00","label":"Amount:",
                   "name":"level_id","is_header":"false"},
                {"value":{},"label":"Billing Information",
                   "name":"section-header","is_header":"true"},
                {"value":"Jeff","label":"Billing First Name:",
                   "name":"billing.name.first","is_header":"false"},
                {"value":{},"label":"Payment Information",
                   "name":"section-header","is_header":"true"},
                {"value":"Credit Card","label":"Payment type:",
                   "name":"payment_type","is_header":"false"},
                {"value":"***************1111",
                   "label":"Credit Card Number:","name":"payment_type",
                   "is_header":"false"}]
      },
      "tax_deductible_amount":{"decimal":"35.00",
                               "formatted":"$35.00"},
      "amount":{"decimal":"35.00",
                "formatted":"$35.00"},
      "confirmation_code":"1-1203-1-1203-1406",
      "value_of_goods":{"decimal":"0.00",
                        "formatted":"$0.00"},
      "org_tax_id":"fake tax id : 123456-789",
      "reward_points_earned":"0",
      "date_time":"2008-02-27T14:58:56.825-06:00",
      "transaction_id":"1406"
    }
  }
}

Error

If there is an error, this returns either a URL redirection request (if the redirect parameter was specified) or the error code and message. The HTTP status code is 403.

For errors common to APIs, such as site configuration errors, the common error response is returned.

XML format:

<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></code>
	<message>.</message>
</errorResponse >

JSON format:

{"errorResponse":{"code":"","message":""}}

Donation Specific Errors

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

XML format:

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

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

Client Community
Log in to chat with other clients and partners using APIs and share code snippets.

donate

Post URL

Authentication

Parameters

Name

Description

Response

Success

Error

Donation Specific Errors