ProDon:Integration with Online Donation Forms

Template:Header ProDon

Definition of the 3 possible Integration Methods

1. Link

This is the simplest integration method allowing you to guide your donors to your online donation forms.

Typical Uses:

• Integration to your own website
• Emailing the link

Characteristics:

• Possibility to access your list of forms, or to access a form directly
• No programming required (addition of a hyperlink only)

2. Link with Information Transfer

This is a more advanced integration, allowing you to prefill a form.
Typical Uses:

• Integration from a microsite
  • Registration of teams / participants
  • Donation to a team / participant
  • Viral campaigns
• Integration from a third-party organization
  • Telemarketing firm
  • Web development firm
• Integration from a third-party system
  • In-house system (members, alumni management, etc.)

Characteristics:

• Programming required (examples provided)
• Simple integration by GET (encrypted) or POST parameters
• Possibility to send information to the form, to auto-populate:
  • Personal information
  • Transaction information (except for credit card information)
  • Customized form information (e.g. name/team ID, specific questions, etc.)

3. Link with Information Transfer and Transaction Retrieval

This includes the possibility of a “link with information transfer” (see second method) while allowing you to retrieve the completed transaction.
Typical Uses:

• Integration from a microsite allowing you to manage objectives
• It allows the microsite or the organization to monitor in real time the progress of the donations

Characteristics:

• Programming required (examples provided)
• Additional programming required for “CallBack” (to receive the transaction information in XML format)

Technical Explanations

1. Link

Format of the link:

https://www.imakeanonlinedonation.org/ or https://www.jedonneenligne.org/
ORG_DIR[/test][/index.php?form=FORM_NAME]

Definition:

• ORG_DIR: Organization directory on IMakeAnOnlineDonation or JeDonneEnLigne
• [/test]: Test Mode active (unspecified = production mode)
• [/index.php?form=FORM_NAME]: Name of the form to call (unspecified = list of forms)

Examples of links:

• List of forms: https://www.jedonneenligne.org/logilys_pbrochu
• DGEN form: https://www.jedonneenligne.org/logilys_pbrochu/index.php?form=DGEN
• List of forms (test mode): https://www.jedonneenligne.org/logilys_pbrochu/test
• DGEN forms (test mode): https://www.jedonneenligne.org/logilys_pbrochu/test/index.php?form=DGEN

2. Link with information transfer

This type of integration requires programming skills. See working prototype on https://www.imakeanonlinedonation.org/tools/integration_prototype.php

The prototype has been prefilled to make you to experience the integration simply by clicking on “send data”.

Here are the possible settings of the prototype:

• Key: Unique encryption key for each organization. The key in this example works for the “logilys_pbrochu” organization. This key is generated by Logilys upon request from the organization and then sent to the integrator (if necessary).
• Directory: Organization directory on IMakeAnOnlineDonation (add “/test” to activate test mode).
• Form (UID): Number of the form to be used for the information transfer.
• Personal information used in the example: Country, Title, First name, Last name, Address, City, Postal code, Email, Home phone.
• Transaction information used in the example: Amount, Activity (UID), Payment method (UID) and Receipt (logical value).
• The different UID parameters are specific to the organization, but can easily be found by examining the source code of the form.

You can also download the complete sources of the prototype by clicking on “download sources”. Here are the contents of the zip file:

• integration_prototype.php: the source code of the prototype
• integration_js_prototype.php: other example in java script
  • encode64.js, mcrypt.js, rijndael.js: used by integration_js_prototype.php
• list_parameters.txt: brief descriptions of the possible parameters.
• callback return xml example.txt: example for integration method 3, described below. 

3. Link with Information Transfer and Transaction Recovery

See technical explanations of “link with information transfer”, prior. This integration allows you to recover the transaction after.

The transaction information will be transferred (POST) in XML format to the URL of your choice (which will have to be specified in parameters when calling the form).

Additional inbound parameters to send when calling the form:

• PersonalUrl (encrypted): the URL of your callback, example: &PersonalUrl=http://www.mysite.com/jdel_callback.php(encrypted).
• PersonalId (not encrypted): Unique ID for your transaction, example: &PersonalId=00000001(not encrypted).

Outbound parameters sent to your “PersonalUrl”:

• trx_xml (encrypted): xml of the transaction. See “callback return xml example.txt” in the sources of the prototype to view an example.
• mode (not encrypted): Contains “TEST” or “PROD” whether the transaction was made in test or production mode.
• PersonalId (not encrypted): Your unique ID.

---- Document name: ProDon:Integration with Online Donation Forms

Printable version