startDonation

This method initiates processing of a donation through an external payment processor (PayPal, Amazon, or Blackbaud MobilePay).

Client ServletServer ServletHTTP Methods SupportedRequires Authentication
CRDonationAPI None. POST No.

Client API Syntax

https://secure2.convio.net/organization/site/CRDonationAPI?method=startDonation &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 &extproc=amazon | paypal | mobilepay &form_id=value &level_id=value [ &ach_account_type=CHECKING | SAVINGS ] [ &ach_bank=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_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 | other ] [ &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 ] [ &finish_error_redirect=value ] [ &finish_success_redirect=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

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.

This method allows you to process a donation through Amazon, PayPal, or Blackbaud MobilePay. To use it, you must have a gateway to your Amazon, PayPal, or Blackbaud MobilePay account set up in your Luminate Online merchant account configuration. Also, the shadow donation form you reference by the form_id parameter must allow payments through the external payment processor gateway.

For the most part, the startDonation method takes the same input parameters, functions the same way, and returns the same response data as the donate method. It supports the same types of transactions. There are a few differences:

  • The extproc parameter is required. You must specify either "amazon" or "paypal" or "mobilepay."
  • The ach_account, ach_routing, card_cvv, card_exp_date, card_exp_date_month, card_exp_date_year, and card_number fields, if specified, are ignored, since payment information is maintained by the external payment processor.
  • You may optionally provide finish_success_redirect and finish_error_redirect URLs to guide page flow after returning from the external processor's site.

The external payment processor may return billing and/or shipping address information for the transaction, in which case the returned data will override any information you provided when calling startDonation.

This method works by redirecting the user to the external payment processor's payment gateway, which then redirects to another URL on Luminate Online to complete the transaction. For additional information on the information returned by a completed transaction, refer to the donate method.

If you are hosting the donation page on an external domain, you must obtain a valid session cookie from your site's Luminate Online secure domain before calling startDonation. The session cookie allows Luminate Online to associate the authorization response from the payment processor with the donation context created by startDonation. You can obtain a session cookie by embedding a PixelServer image somewhere in the page, for example:

<img src="https://secure2.convio.net/myorg/site/PixelServer" />

The PixelServer URL is the same as the secure site URL for the startDonation method.

Note: This API does not support a separate confirmation page on the calling site after the user enters their payment information on PayPal, which is the default behavior when PayPal is configured as a payment gateway for Luminate Online. You must contact Support to request that this be changed, otherwise the label of the final button shown to the user in the PayPal flow will read "Continue" instead of "Pay Now," but clicking the button will complete the payment before returning to the calling code. The change will also affect the behavior of Luminate Online donation forms that include PayPal as a payment method.

Client API Parameters

Common Client Parameters

See topic Common Parameters.

billing.address.city

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

Type xsd:string.

billing.address.state

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

Type xsd:string.

billing.address.street1

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

Type xsd:string.

billing.address.zip

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

Type xsd:string.

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.

extproc

Required. The value designating which external payment processor to use.

Type xsd:string.

Options are:
  • amazon
  • paypal
  • mobilepay
form_id

Required. The ID of the donation form.

Type xsd:nonNegativeInteger.

level_id

Required. The ID of the donation level.

Type xsd:nonNegativeInteger.

ach_account_type

Optional. ACH account type (CHECKING/SAVINGS).

Type xsd:string.

Default is CHECKING.

Options are:
  • CHECKING
  • SAVINGS
ach_bank

Optional. ACH bank number (Canada).

Type xsd:string.

ach_transit

Optional. ACH transit number (Canada).

Type xsd:string.

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

Optional. Credit card type

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

Optional. The donor's address.

Type xsd:string.

donor.address.country

Optional. The donor's address.

Type xsd:string.

donor.address.county

Optional. The donor's address.

Type xsd:string.

donor.address.state

Optional. The donor's address.

Type xsd:string.

donor.address.street1

Optional. The donor's address.

Type xsd:string.

donor.address.street2

Optional. The donor's address.

Type xsd:string.

donor.address.street3

Optional. The donor's address.

Type xsd:string.

donor.address.zip

Optional. The donor's address.

Type xsd:string.

donor.email_opt_in

Optional. The donor's email opt-in selection.

Type xsd:string.

donor.employer

Optional. The donor's employer.

Type xsd:string.

donor.name.first

Optional. The donor's name.

Type xsd:string.

donor.name.last

Optional. The donor's name.

Type xsd:string.

donor.name.middle

Optional. The donor's name.

Type xsd:string.

donor.name.profSuffix

Optional. The donor's name.

Type xsd:string.

donor.name.suffix

Optional. The donor's name.

Type xsd:string.

donor.name.title

Optional. The donor's name.

Type xsd:string.

donor.occupation

Optional. The donor's occupation.

Type xsd:string.

donor.phone

Optional. The donor's phone number.

Type xsd:string.

donor.phone_type

Optional. The type of the donor's phone number .

Type xsd:string.

Options are:
  • home
  • work
  • other
ecard.copy_sender

Optional. Whether to send a copy of the e-card to the sender.

Type xsd:boolean.

ecard.id

Optional. The unique ID of the pre-defined Luminate Online e-card template to use.

Type xsd:nonNegativeInteger.

ecard.message

Optional. The message body of the e-card.

Type xsd:string.

ecard.recipients

Optional. The email addresses of intended e-card recipients (RFC-5322 format) e.g. 'John Doe, Jane Roe'.

Type xsd:string.

ecard.send

Optional. Whether or not to send an e-card recognizing the gift.

Type xsd:boolean.

Default is false.

ecard.send_date

Optional. Date to send the e-card (ISO 8601 format) e.g. '2009-12-31'.

Type xsd:date.

ecard.subject

Optional. The subject of the e-card.

Type xsd:string.

finish_error_redirect

Optional. Specifies a URL that the method should redirect to on an error response from the external payment processor.

Type xsd:anyURI.

facebook_donation_id

Optional. Specifies the ID of the Facebook donation associated with this donation.

Type xsd:string.

finish_success_redirect

Optional. Specifies a URL that the method should redirect to on a success response from the external payment processor.

Type xsd:anyURI.

fr_id

Optional. Specifies the ID of the TeamRaiser event associated with this donation.

Type xsd:nonNegativeInteger.

gift_aid

Optional. Gift aid status (UK Only).

Type xsd:string.

installment.duration

Optional. The duration of an installment plan donation, which is the number of payments that the donation is divided into. To make an installment plan donation, both installment.frequency and installment.duration must be specified.

Type xsd:nonNegativeInteger.

installment.frequency

Optional. The frequency of an installment plan donation, which is the interval between payments. To make an installment plan donation, both installment.frequency and installment.duration must be specified.

Type crm:donationSustainingFrequency.

Options are:
  • one-time
  • monthly
  • quarterly
  • semi-annually
  • annually
joint_donor.name.first

Optional. The name of a joint donor.

Type xsd:string.

joint_donor.name.last

Optional. The name for a joint donor.

Type xsd:string.

joint_donor.name.middle

Optional. The name for a joint donor.

Type xsd:string.

joint_donor.name.suffix

Optional. The name for a joint donor.

Type xsd:string.

joint_donor.name.title

Optional. The name for a joint donor.

Type xsd:string.

level_autorepeat

Optional. Whether or not the "recurring gift" option on the Donation Level shadow form should be selected. Valid only for Level shadow forms on which a recurring gift option has been defined.

Type xsd:boolean.

Default is false.

matching_eligible

Optional. Whether or not the donation is eligible for a matching gift.

Type xsd:boolean.

organization_name

Optional. The name of the organization on whose behalf donor is making the gift.

Type xsd:string.

other_amount

Optional. User specified donation amount.

Type xsd:string.

premium_id

Optional. Unique ID of premium.

Type xsd:nonNegativeInteger.

premium_option

Optional. Premium option.

Type xsd:string.

remember_me

Optional. Whether to set a log-in cookie.

Type xsd:boolean.

send_receipt

Optional. Whether to send a receipt email to the donor. The default behavior is to send a receipt.

Type xsd:boolean.

Default is true.

send_registration_email

Optional. If a new constituent record is created for the donor, this specifies whether to send a registration "welcome" email to the donor. The default behavior is to send it.

Type xsd:boolean.

Default is true.

shipping.address.city

Optional. Shipping address for premium.

Type xsd:string.

shipping.address.country

Optional. Shipping address for premium.

Type xsd:string.

shipping.address.county

Optional. Shipping address for premium.

Type xsd:string.

shipping.address.state

Optional. Shipping address for premium.

Type xsd:string.

shipping.address.street1

Optional. Shipping address for premium.

Type xsd:string.

shipping.address.street2

Optional. Shipping address for premium.

Type xsd:string.

shipping.address.street3

Optional. Shipping address for premium.

Type xsd:string.

shipping.address.zip

Optional. Shipping address for premium.

Type xsd:string.

shipping.email

Optional. Email address of the recipient.

Type xsd:string.

shipping.name.first

Optional. Premium recipient's name.

Type xsd:string.

shipping.name.last

Optional. Premium recipient's name.

Type xsd:string.

shipping.name.middle

Optional. Premium recipient's name.

Type xsd:string.

shipping.name.profSuffix

Optional. Premium recipient's name.

Type xsd:string.

shipping.name.suffix

Optional. Premium recipient's name.

Type xsd:string.

shipping.name.title

Optional. Premium recipient's name.

Type xsd:string.

shipping.phone

Optional. Phone number of the recipient.

Type xsd:string.

soft_credit_id

Optional. Specifies the ID of the entity to which this donation will be soft credited. This will be either the event ID, team ID, or participant (constituent) ID, depending on the value specified for soft_credit_type.

Type xsd:nonNegativeInteger.

soft_credit_type

Optional. Specifies the type of entity to which this donation will be soft credited. Donations that specify a soft credit type must also specify a soft_credit_id value.

Type xsd:string.

Options are:
  • TR_PARTICIPANT
  • TR_TEAM
  • TR_EVENT
  • TRIBUTE_GIFT
summary

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

Type xsd:string.

Options are:
  • data
  • page
  • both
sustaining.duration

Optional. The duration of a sustaining donation, which is the interval between payments. Specify zero to indicate that the donation should repeat indefinitely. To make a sustaining donation, both sustaining.frequency and sustaining.duration must be specified.

Type xsd:nonNegativeInteger.

sustaining.frequency

Optional. The frequency of a sustaining donation, which is how often the donation is repeated. To make a sustaining donation, both sustaining.frequency and sustaining.duration must be specified.

Type crm:donationSustainingFrequency.

Options are:
  • one-time
  • monthly
  • quarterly
  • semi-annually
  • annually
teamraiser.message_to_participant

Optional. If this donation is a TeamRaiser Gift, the body of the message to send to the TeamRaiser participant.

Type xsd:string.

teamraiser.recognition_name

Optional. If this donation is a TeamRaiser Gift, the recognition name.

Type xsd:string.

teamraiser.show_gift_to_public

Optional. If this donation is a TeamRaiser Gift, whether or not to the TeamRaiser gift is publicly visible.

Type xsd:boolean.

tribute.honoree.deceased

Optional. Whether the tribute honoree is deceased. If set, it overrides "tribute.type" by setting it to "memorial" if true (deceased) and "tribute" if false (not deceased).

Type xsd:boolean.

tribute.honoree.name.first

Optional. The first name of the person to honor with the tribute. Takes precedence over tribute.honoree.name.full.

Type xsd:string.

tribute.honoree.name.full

Optional. The full name of the person to honor with the tribute. Only used if the first and last names are not specified.

Type xsd:string.

tribute.honoree.name.last

Optional. The last name of the person to honor with the tribute. Takes precedence over tribute.honoree.name.full.

Type xsd:string.

tribute.honoree.name.title

Optional. The name title of the person to honor with the tribute.

Type xsd:string.

tribute.message.body

Optional. The body of the tribute notification message.

Type xsd:string.

tribute.message.closing

Optional. The closing of the tribute notification message.

Type xsd:string.

tribute.message.include_amount

Optional. Whether to include the donation amount in the tribute notification message.

Type xsd:boolean.

tribute.message.signature

Optional. The signature of the tribute notification message.

Type xsd:string.

tribute.notify.address.city

Optional. The address of the person to notify of the tribute.

Type xsd:string.

tribute.notify.address.country

Optional. The address of the person to notify of the tribute.

Type xsd:string.

tribute.notify.address.county

Optional. The address of the person to notify of the tribute.

Type xsd:string.

tribute.notify.address.state

Optional. The address of the person to notify of the tribute.

Type xsd:string.

tribute.notify.address.street1

Optional. The address of the person to notify of the tribute.

Type xsd:string.

tribute.notify.address.street2

Optional. The address of the person to notify of the tribute.

Type xsd:string.

tribute.notify.address.street3

Optional. The address of the person to notify of the tribute.

Type xsd:string.

tribute.notify.address.zip

Optional. The address of the person to notify of the tribute.

Type xsd:string.

tribute.notify.name.full

Optional. The full name of the person to notify of the tribute.

Type xsd:string.

tribute.notify.name.title

Optional. The name title of the person to notify of the tribute.

Type xsd:string.

tribute.type

Optional. The type of tribute.

Type xsd:string.

Options are:
  • memorial
  • tribute
validate

Optional. Whether to enforce validation of every field according to the specification in the ghost form ("true" or "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.

Type xsd:boolean.

Default is false.

captcha_text

Required when using reCAPTCHA v3 protection on the donation form. Use the getDonationFormInfo method to retrieve a publicKey for the Google reCAPTCHA v3 library. Include the publicKey value with this parameter.

Type xsd:string.

Response

See topic HTTP Status Codes.

XML response 
<?xml version="1.0" encoding="UTF-8"?>
<donationResponse 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">
  <redirect>
    <url>https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&amp;amp;token=EC-4PM50326PB7342636</url>
  </redirect>
</donationResponse>
JSON response 
{"donationResponse":{"redirect":{"url":"https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-4PM50326PB7342636"}}}
Parent topic: Donation API
Previous topic: refundTransaction
Next topic: skipNextPayment

Leave a Comment

Nickname
Comment
Enter this word:
Change