getDonationFormInfo

Use this method to return standard information elements that are required to submit a donation form. You can also use this method to return custom elements by using the include_custom_elements parameter.

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.

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

Client API Syntax

https://secure2.convio.net/organization/site/CRDonationAPI?method=getDonationFormInfo &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 ] &form_id=value [ &fr_id=value ] [ &include_custom_elements=value ]

Usage Notes

reCAPTCHA v3

2021 Update: See also Secure donations with Google reCAPTCHA v3 in our new Luminate Online API site.

reCAPTCHA v3 is a completely seamless Captcha implementation that scores the probability that the end user is a human based on their interactions with their web browser and your site. Most of the implementation is handled automatically by the reCAPTCHA v3 library, as covered in Google's documentation.

You must call the Google reCAPTCHA code when the donation is submitted and include the resulting token in the subsequent API call to donate and startDonation.

Luminate Online provides a public key to be used when including and calling the reCAPTCHA v3 library. This key is returned from the getDonationFormInfo method in the publicKey element of the recaptchaData.

You can extract the publicKey with the following code example:

            
                var recaptchaKey;
                $.ajax({
                    url: "https://secure2.convio.net/organization/site/CRDonationAPI",
                    method: "POST",
                    data: 'method=getDonationFormInfo&v=1.0&api_key=' + apiKey + '&form_id=1001',
                    success: function( result ) {
                        recaptchaKey = $(result).find('recaptchaData publicKey').text()
                    }
                });

You could then load the reCAPTCHA v3 library using jQuery:

           
                     $.getScript( "https://www.google.com/recaptcha/api.js?render=" + recaptchaKey );

On form submission, you must include the Captcha token parameter, captcha_text in the donate or startDonation call. For instance:

  
                    grecaptcha.ready(function() {
                         grecaptcha.execute(recaptchaKey, {action: 'submit'}).then(function(token) {
                             // add the token to the value of a hidden input with name="captcha_text"
                             $('#captcha_text').val(token);
                             // serialize the donation form into a text string
                             var formData = $('#donate_form').serialize();
                             $.ajax({
                                 url: "https://secure2.convio.net/organization/site/CRDonationAPI",
                                 method: "POST",
                                 data: formData,
                                 success: function( result ) {
                                     // Handle form success here.
                                 }
                             });
                         });
                    });

Client API Parameters

Common Client Parameters

See topic Common Parameters.

form_id

Required. The ID of the donation form.

Type xsd:nonNegativeInteger.

fr_id

Optional. The ID of the teamraiser.

Type xsd:nonNegativeInteger.

include_custom_elements

Optional. When this value is true, the method returns all custom donation elements, whether required or optional, in addition to returning standard required elements. When not specified, the default value is false.

Type xsd:boolean.

Default is false.

Response

See topic HTTP Status Codes.

XML response

<?xml version="1.0" encoding="UTF-8"?>
<getDonationFormInfoResponse xsi:schemaLocation="http://convio.com/crm/v1.0 http://service.convio.net/xmlschema/crm.public.v1.xsd" xmlns="http://convio.com/crm/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <donationLevels>
    <donationLevel>
      <level_id>10</level_id>
      <name>Sample Donation Level $10</name>
      <amount>
        <decimal>0.10</decimal>
        <formatted>$10.00</formatted>
      </amount>
      <userSpecified>false</userSpecified>
    </donationLevel>
    <donationLevel>
      <level_id>20</level_id>
      <name>Sample Donation Level $20</name>
      <amount>
        <decimal>0.20</decimal>
        <formatted>$20.00</formatted>
      </amount>
      <userSpecified>false</userSpecified>
    </donationLevel>
    <donationLevel>
      <level_id>30</level_id>
      <name>Sample Donation Level $30</name>
      <amount>
        <decimal>0.30</decimal>
        <formatted>$30.00</formatted>
      </amount>
      <userSpecified>false</userSpecified>
    </donationLevel>
  </donationLevels>
  <paymentCards>
    <paymentCard>Visa</paymentCard>
    <paymentCard>MasterCard</paymentCard>
    <paymentCard>American Express</paymentCard>
    <paymentCard>Discover</paymentCard>
  </paymentCards>
  <bankTransfers>true</bankTransfers>
  <externalProcessors>
    <externalProcessor>PayPal</externalProcessor>
    <externalProcessor>Amazon</externalProcessor>
  </externalProcessors>
  <donationFields>
    <donationField>
      <elementName>form_id</elementName>
      <required>true</required>
      <defaultValue>0</defaultValue>
    </donationField>
    <donationField>
      <elementName>level_id</elementName>
      <required>true</required>
      <defaultValue/>
    </donationField>
    <donationField>
      <elementName>billing.name.first</elementName>
      <required>true</required>
      <defaultValue/>
    </donationField>
    <donationField>
      <elementName>billing.name.last</elementName>
      <required>true</required>
      <defaultValue/>
    </donationField>
    <donationField>
      <elementName>billing.address.street1</elementName>
      <required>true</required>
      <defaultValue/>
    </donationField>
    <donationField>
      <elementName>billing.address.city</elementName>
      <required>true</required>
      <defaultValue/>
    </donationField>
    <donationField>
      <elementName>billing.address.state</elementName>
      <required>true</required>
      <defaultValue/>
    </donationField>
    <donationField>
      <elementName>billing.address.zip</elementName>
      <required>true</required>
      <defaultValue/>
    </donationField>
    <donationField>
      <elementName>donor.email</elementName>
      <required>true</required>
      <defaultValue/>
    </donationField>
    <donationField>
      <elementName>remember_me</elementName>
      <required>false</required>
      <defaultValue/>
    </donationField>
    <donationField>
      <elementName>captcha_text</elementName>
      <required>true</required>
      <defaultValue/>
      <recaptchaData><publicKey>8LGC8X1VBCBCADEopD_X353jNNoQQ551XyLmDpPC</publicKey></recaptchaData>
    </donationField>
  </donationFields>
  <supportsDesignation>false</supportsDesignation>
  <supportsWriteInDesignation>false</supportsWriteInDesignation>
  <supportsEcard>false</supportsEcard>
  <supportsInstallments>false</supportsInstallments>
  <supportsSustaining>false</supportsSustaining>
  <supportsLevelAutorepeat>false</supportsLevelAutorepeat>
  <supportsGiftAid>false</supportsGiftAid>
  <supportsTribute>false</supportsTribute>
  <teamraiserTeamGiftsAllowed>false</teamraiserTeamGiftsAllowed>
</getDonationFormInfoResponse>

JSON response

{"getDonationFormInfoResponse":{"supportsTribute":"false","externalProcessors":{"externalProcessor":["PayPal","Amazon"]},"teamraiserTeamGiftsAllowed":"false","supportsEcard":"false","donationFields":{"donationField":[{"defaultValue":"0","required":"true","elementName":"form_id"},{"defaultValue":{},"required":"true","elementName":"level_id"},{"defaultValue":{},"required":"true","elementName":"billing.name.first"},{"defaultValue":{},"required":"true","elementName":"billing.name.last"},{"defaultValue":{},"required":"true","elementName":"billing.address.street1"},{"defaultValue":{},"required":"true","elementName":"billing.address.city"},{"defaultValue":{},"required":"true","elementName":"billing.address.state"},{"defaultValue":{},"required":"true","elementName":"billing.address.zip"},{"defaultValue":{},"required":"true","elementName":"donor.email"}]},"supportsSustaining":"false","donationLevels":{"donationLevel":[{"amount":{"formatted":"$10.00","decimal":"0.10"},"level_id":"10","name":"Sample Donation Level $10","userSpecified":"false"},{"amount":{"formatted":"$20.00","decimal":"0.20"},"level_id":"20","name":"Sample Donation Level $20","userSpecified":"false"},{"amount":{"formatted":"$30.00","decimal":"0.30"},"level_id":"30","name":"Sample Donation Level $30","userSpecified":"false"}]},"supportsLevelAutorepeat":"false","supportsDesignation":"false","supportsGiftAid":"false","paymentCards":{"paymentCard":["Visa","MasterCard","American Express","Discover"]},"bankTransfers":"true","supportsWriteInDesignation":"false","supportsInstallments":"false"}}

Luminate Online

getDonationFormInfo

Client API Syntax

Usage Notes

Client API Parameters

Response

Leave a Comment