Extension to connect to the Twingle fundraising service via its API.
The extension is licensed under AGPL-3.0.
Please refer to the Twingle FAQ on using Twingle with CiviCRM (currently only available in German).
Make sure you use an XCM profile with the option Match contacts by contact ID enabled.
Be careful when enabling the "Change Primary Detail?" option. While it might
appear useful to update even primary contact details, this might lead to a
loss of contact information due to the fact that along with a submission that
contains e.g. a PayPal donation the user_country is transmitted as the only
address detail. The user_country then will be treated by the XCM as a whole
new address. So the contact may end up with a new address that contains only
the country.
- Go to the Administration console at
/civicrm/admin - Open "Twingle API Configuration" at
/civicrm/admin/settings/twingle
Open "Configure extension settings" at
/civicrm/admin/settings/twingle/settings and configure whether to integrate
with the CiviSEPA extension.
This enables you to map incoming donations from Twingle with a specific payment method (e.g. debit_manual) to be processed with CiviSEPA, that is, creating a SEPA mandate and managing recurring payments.
Open "Configure profiles" at /civicrm/admin/settings/twingle/profiles.
The default profile is used whenever the plugin cannot match the Twingle project ID from any other profile. Therefore the default profile will be used for all newly created Twingle projects.
| Label | Description |
|---|---|
| Profile name | Internal name, used inside the extension. |
| Project IDs | Twingle project IDs. Separate multiple IDs with commas. |
| Location type | Specify how the address data sent by the form should be categorised in CiviCRM. The list is based on your CiviCRM configuration. |
| Location type for organisations | Specify how the address data sent by the form should be categorised in CiviCRM for organisational donations. The list is based on your CiviCRM configuration. |
| Financial type | Specify which financial type incoming one-time donations should be recorded with in CiviCRM. The list is based on your CiviCRM configuration. |
| Financial type (recurring) | Specify which financial type incoming recurring donations should be recorded with in CiviCRM. The list is based on your CiviCRM configuration. |
| CiviSEPA creditor | When enabled to integrate with CiviSEPA, specify the CiviSEPA creditor to use. |
| Gender options | Specify which CiviCRM gender option the incoming Twingle gender value should be mapped to. The list is based on your CiviCRM configuration. |
| Record Payment method as | Specifiy the payment methods mapping for incoming donations for each Twingle payment method. |
| Double Opt-In | Let CiviCRM handle the double opt-in. Group memberships for newsletter mailing lists stay pending until the subscription gets confirmed. Note that this only works for public mailing lists. Any non-public mailing list will be ignored. Do not forget to disable Twingle's double opt-in option in the Twingle Manager. |
| Sign up for groups | Whenever the donor checked the newsletter/postal mailing/donation receipt checkbox on the Twingle form, the contact will be added to the groups listed here. |
| Assign donation to campaign | The donation will be assigned to the selected campaign. If a campaign ID is being submitted using the campaign_id parameter, this setting will be overridden with the submitted value. |
| Create membership of type | A membership of the selected type will be created for the Individual contact for incoming one-time donations. If no membership type is selected, no membership will be created. |
| Create membership of type (recurring) | A membership of the selected type will be created for the Individual contact for incoming recurring donations. If no membership type is selected, no membership will be created. |
| Contribution source | The configured value will be set as the "Source" field for the contribution. |
| Custom field mapping | Additional field values may be set to CiviCRM custom fields using a mapping. See the option's help text for the exact format. |
The extension provides a new CiviCRM API entity TwingleDonation with API
actions to record a new donation, end a previously submitted recurring donation
and cancel previously submitted donation.
This API action processes submitted Twingle donations and donor information.
- Entity:
TwingleDonation - Action:
Submit
The action accepts the following parameters:
| Parameter | Type | Description | Values/Format | Required |
|---|---|---|---|---|
project_id |
String | The Twingle project ID | Yes | |
trx_id |
String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes |
confirmed_at |
String | The date when the donation was issued | A string representing a date in the format YmdHis |
Yes |
purpose |
String | The purpose of the donation | ||
amount |
Integer | The donation amount in minor currency unit | Yes | |
currency |
String | The ISO-4217 currency code of the donation | A valid ISO-4217 currency code | Yes |
newsletter |
Boolean | Whether to subscribe the contact to the newsletter group defined in the profile | ||
postinfo |
Boolean | Whether to subscribe the contact to the postal mailing group defined in the profile | ||
donation_receipt |
Boolean | Whether the contact requested a donation receipt | ||
payment_method |
String | The Twingle payment method used for the donation | One of:
|
Yes |
donation_rhythm |
String | The interval which the donation is recurring in | One of:
|
Yes |
debit_iban |
String | The IBAN for SEPA Direct Debit payments | A valid ISO 13616-1:2007 IBAN | Yes, if payment_method is debit_manual and CiviSEPA is used |
debit_bic |
String | The BIC for SEPA Direct Debit payments | A valid ISO 9362 BIC | Yes, if payment_method is debit_manual and CiviSEPA is used |
debit_mandate_reference |
String | The mandate reference for SEPA Direct Debit payments | ||
debit_account_holder |
String | The account holder for SEPA Direct Debit payments | ||
is_anonymous |
Boolean | Whether the donation is submitted anonymously | ||
user_gender |
String | The gender of the contact | ||
user_birthdate |
String | The date of birth of the contact | A string representing a date in the format Ymd |
|
user_title |
String | The formal title of the contact | ||
user_email |
String | The e-mail address of the contact | A valid e-mail address | |
user_firstname |
String | The first name of the contact | ||
user_lastname |
String | The last name of the contact | ||
user_street |
String | The street address of the contact | ||
user_postal_code |
String | The postal code of the contact | ||
user_city |
String | The city of the contact | ||
user_country |
String | The country of the contact | ISO 3166-1 Alpha-2 country codes | |
user_telephone |
String | The telephone number of the contact | ||
user_company |
String | The company of the contact | ||
user_extrafield |
String | Additional information of the contact | ||
campaign_id |
Integer | The CiviCRM ID of a campaign to assign the contribution | A valid CiviCRM Campaign ID. This overrides the campaign ID configured within the profile. |
You may also refer to the code for more insight into this API action.
- Entity:
TwingleDonation - Action:
Endrecurring
The action accepts the following parameters:
| Parameter | Type | Description | Values/Format | Required |
|---|---|---|---|---|
project_id |
String | The Twingle project ID | Yes | |
trx_id |
String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes |
ended_at |
Integer | The date when the recurring donation was ended | A string representing a date in the format YmdHis |
Yes |
You may also refer to the code for more insight into this API action.
- Entity:
TwingleDonation - Action:
Cancel
The action accepts the following parameters:
| Parameter | Type | Description | Values/Format | Required |
|---|---|---|---|---|
project_id |
String | The Twingle project ID | Yes | |
trx_id |
String | The unique transaction ID of the donation | A unique transaction ID for the donation. | Yes |
cancelled_at |
String | The date when the recurring donation was cancelled | A string representing a date in the format YmdHis |
Yes |
cancel_reason |
String | The reason for the donation being cancelled | Yes |
You may also refer to the code for more insight into this API action.